Form Builder Class

The Form Builder class creates forms based on an array of field information. FUEL uses this class to create the forms for modules.

This class uses the Form class for rendering form fields.

Initializing the Class

Like most other classes in CodeIgniter, the Form Builder class is initialized in your controller using the $this->load->library function:

$this->load->library('form_builder');

Alternatively, you can pass initialization parameters as the second parameter:

$this->load->library('form_builder', array('id'=>'contact_form','submit_value' => 'Send Message', 'textarea_rows' => '5', 'textarea_cols' => '28'));

Configuring Form Builder Information

Preference	Default Value	Options	Description
form	None	None	Form object to be used
id	None	None	ID to be used for the containing table or id
css_class	form	None	CSS class to be used with the form
form_attrs	method="post" action=""	can be array or string	Form tag attributes
label_colons	FALSE	TRUE/FALSE (boolean)	Add colons to form labels?
textarea_rows	10	None	Number of rows for a textarea
textarea_cols	60	None	Number of columns for a textarea
text_size_limit	40	None	Text size for a text input
submit_value	Submit	None	Submit value (what the button says)
cancel_value	None	None	Cancel value (what the button says)
cancel_action	None	None	What the cancel button does
reset_value	None	None	Reset button value (what the button says)
other_actions	None	None	Additional actions to be displayed at the bottom of the form
use_form_tag	TRUE	TRUE/FALSE (boolean)	Include the form opening/closing tags in rendered output
exclude	array()	None	Array of fields to exclude from the form
hidden	array('id')	None	Array of fields to display as hidden
readonly	array()	None	Readonly fields
disabled	array()	None	Disabled fields
displayonly	array()	None	Array of fields for display purposes only
date_format	m/d/Y	m/d/Y	Date format for date type fields
section_tag	h3	Any HTML tag	Section html tag
copy_tag	p	Any HTML tag	Copy html tag
fieldset	None	None	Field set name
name_array	None	None	Put the form fields into an array for namespacing
name_prefix	None	None	Prefix the form fields as an alternatie to an array for namespacing
key_check	None	None	The keycheck value used for forms that create session unique session variables to prevent spamming. If CSRF protection is enabled in CodeIgniter 2, then this value will be automatically filled out.
key_check_name	None	None	The keycheck form name used for forms that create session unique session variables to prevent spamming. If CSRF protection is enabled in CodeIgniter 2, then this value will be automatically filled out.
tooltip_format	[?]	None	Tooltip formatting string
tooltip_labels	TRUE	TRUE/FALSE (boolean)	Use tooltip labels?
single_select_mode	auto	auto, enum, select	Auto will use enum if 2 or less and a single select if greater than 2. Other values are enum or select
multi_select_mode	auto	auto, multi, checkbox	Auto will use a series of checkboxes if 5 or less and a multiple select if greater than 5. Other values are multi or checkbox
boolean_mode	checkbox	checkbox or enum	Booleon mode can be checkbox or enum (which will display radio inputs)
display_errors_func	display_errors	None	The function used to generate errors... usually display_errors is the name
display_errors	FALSE	TRUE/FALSE (boolean)	Displays errors at the top of the form if TRUE
question_keys	array('how', 'do', 'when', 'what', 'why', 'where', 'how', 'is', 'which', 'did', 'any')	None	adds question marks to the label if has these words in the label
show_required	TRUE	TRUE/FALSE (boolean)	Show the required fields text at the bottom of the form
required_indicator	*	None	Indicator for a required field
required_text	{required_indicator} required fields	None	The required field text
label_layout	left	left, top	Where to place the labels when using a table
has_required	FALSE	TRUE/FALSE (boolean)	Has a required field
render_format	table	table, divs	The HTML structure to render the form
row_id_prefix	None	None	The id prefix to be used for assigning ids to each row of the form
lang_prefix	form_label	None	The prefix to be used for looking up associated language strings for form labels. If a field's name is 'last_modified', it will look for a language string of {lang_prefix}last_modified.

Field Options

name - the name of the field
type - the type of the field. If no type is specified it will default to a text input. Options are , hidden, textarea/text, enum, multi, select, file date, time, checkbox boolean, section, copy, custom
You'll notice above that a type of 'text' is a textarea and NOT a 'text' input. This is due to integration with database table types. If you want a normal text field, don't specify a type value or specify one not on the list.
default - the default value of the field if no value is specified
max_length - the max length value of the field
comment - a comment for the field
label - the label of the field
required - is it required
size - the size of the field
class - the css class
options - select and enum options
checked - whether the input value is checked (for checkbox and radios)
value - the value of the field
readonly - the readonly attribute of the field
disabled - the disabled attribute of the field
order - the order in the form the field should appear
first_option - (for the select)
before_html - HTML to display before the form field
after_html - HTML to display after the form field
displayonly - will show the value text instead of a disabled field?
overwrite - overwrite the file when uploading
accept - file types to accept for uploading
upload_path - the server path to upload the file to
filename - the file name to convert the upload to
sorting - for multi selects that may need to keep track of selected options (combo jquery plugin)
mode - used for enums and multiple select fields whether to use selects or radios/checkbox

Function Reference

$this->form_builder->set_fields(`fields`)

Set the fields for the form. Check the field table above for possible array values.

$fields['name'] = array('type' => 'text', 'label' => 'Full Name', 'required' => TRUE);
$fields['email'] = array('type' => 'text', 'label' => 'Email', 'required' => TRUE);
$fields['password'] = array('type' => 'password', 'label' => 'Password', 'required' => TRUE);
$fields['active'] = array('type' => 'enum', 'options' => array('yes' => 'yes', 'no' => 'no'), 'required' => TRUE);
$this->form_builder->set_fields($fields);

$this->form_builder->set_field_values(`values`)

Sets the values of the fields. This must be called AFTER the set_fields() method if used.

$values['name'] = 'Darth Vader';
$values['email'] = 'dvader@deathstar.com';
$values['password'] = 'd@rks1d3';
$values['active'] = 'yes';
$this->form_builder->set_field_values($values);

$this->form_builder->render(`[fields]`, `['render_format']`)

Renders the form. The $fields value is optional and will set the fields before rendering. The $render_format can be table or divs.

$fields['name'] = array('type' => 'text', 'label' => 'Full Name', 'required' => TRUE);
$fields['email'] = array('type' => 'text', 'label' => 'Email', 'required' => TRUE);
$fields['password'] = array('type' => 'password', 'label' => 'Password', 'required' => TRUE);
$fields['active'] = array('type' => 'enum', 'options' => array('yes' => 'yes', 'no' => 'no'), 'required' => TRUE);
$this->form_builder->render($field, 'divs');

$this->form_builder->render_divs(`[fields]`)

Renders the form using divs for the HTML structure The $fields value is optional and will set the fields before rendering.

$fields['name'] = array('type' => 'text', 'label' => 'Full Name', 'required' => TRUE);
$fields['email'] = array('type' => 'text', 'label' => 'Email', 'required' => TRUE);
$fields['password'] = array('type' => 'password', 'label' => 'Password', 'required' => TRUE);
$fields['active'] = array('type' => 'enum', 'options' => array('yes' => 'yes', 'no' => 'no'), 'required' => TRUE);
$this->form_builder->render_divs($field);

$this->form_builder->render_table(`[fields]`)

Renders the form using table for the HTML structure The $fields value is optional and will set the fields before rendering.

$fields['name'] = array('type' => 'text', 'label' => 'Full Name', 'required' => TRUE);
$fields['email'] = array('type' => 'text', 'label' => 'Email', 'required' => TRUE);
$fields['password'] = array('type' => 'password', 'label' => 'Password', 'required' => TRUE);
$fields['active'] = array('type' => 'enum', 'options' => array('yes' => 'yes', 'no' => 'no'), 'required' => TRUE);
$this->form_builder->render_table($field);

Other Functions

Although the following functions can be used, it is important to note that the render methods above will call the approprate create field function based on the type of the field and therefore, these functions are rarely used.

$this->form_builder->create_field(`params`, `[normalize]`)

Looks at the field type attribute and determines which form field to render. The $normalize value is optional and will normalize the params to a common array structure. Default is TRUE

$fields['name'] = array('type' => 'text', 'label' => 'Full Name', 'required' => TRUE);
$this->form_builder->create_field($field, TRUE);

$this->form_builder->create_label(`params`, `[use_label]`)

Creates the label for the form. By default, if no label value is given, the method will generate one based on the name of the field. The $use_label value is optional and will wrap the label in an HTML label tag. Default is TRUE

$params = array('name' => 'name', 'type' => 'text', 'label' => 'Full Name', 'required' => TRUE);
$this->form_builder->create_label($params);

$this->form_builder->create_text(`params`)

Creates the text input for the form.

$params = array('name' => 'name', 'label' => 'Full Name', 'required' => TRUE);
$this->form_builder->create_text($params);

$this->form_builder->create_submit(`params`)

Creates a submit button.

$params = array('value' => 'My Submit');
$this->form_builder->create_submit($params);

$this->form_builder->create_button(`params`)

Creates a button. The use_input parameter determines whether to use the input type of button or to use the <button> tag.

$params = array('value' => 'My Button', 'use_input' => FALSE);
$this->form_builder->create_button($params);

$this->form_builder->create_textarea(`params`)

Creates a textarea input for the form.

$params = array('name' => 'content', 'label' => 'Content', 'value' => 'This is content for the textarea field');
$this->form_builder->create_textarea($params);

$this->form_builder->create_hidden(`params`)

Creates a hidden input for the form.

$params = array('name' => 'id', 'value' => '1');
$this->form_builder->create_hidden($params);

$this->form_builder->create_enum(`params`)

Creates an enum input for the form. If the class paramenter boolean_mode is set to auto and their are less than 2 options, then it will render radio inputs. Otherwise it will render a select input

$options = array(
	'a' => 'Option A',
	'b' => 'Option B',
)
$params = array('name' => 'my_options', 'options' => $options);
$this->form_builder->create_enum($params);

$this->form_builder->create_multi(`params`)

Creates a multi-select input for the form.

$options = array(
	'a' => 'Option A',
	'b' => 'Option B',
)
$params = array('name' => 'my_multi', 'options' => $options);
$this->form_builder->create_multi($params);

$this->form_builder->create_select(`params`)

Creates a select input for the form.

$options = array(
	'a' => 'Option A',
	'b' => 'Option B',
)
$params = array('name' => 'my_select', 'options' => $options);
$this->form_builder->create_select($params);

$this->form_builder->create_file(`params`)

Creates a file input for the form.

$params = array('name' => 'my_file', 'accept' => 'gif|jpg|png|jpeg', 'upload_path' => '/myuploads/', 'overwrite' => TRUE);
$this->form_builder->create_file($params);

$this->form_builder->create_date(`params`)

Creates an text field sized for date input with css classes ofdatepicker and fillin assigned to the field. jQuery is used to transform those fields into datepickers using those classes.

$params = array('name' => 'my_time', 'value' => '2010-01-01 12:00');
$this->form_builder->create_date($params);

$this->form_builder->create_time(`params`)

Creates two text fields and some am/pm radio buttons with css classes ofdatepicker_hh, datepicker_mm, datepicker_am_pm assigned to each field respectively. Additionally, each text field also has the class of fillin.

$params = array('name' => 'my_time', 'value' => '2010-01-01 12:00');
$this->form_builder->create_time($params);

$this->form_builder->create_checkbox(`params`)

Creates a checkbox input for the form.

$params = array('name' => 'my_checkbox', 'value' => 'yes', 'checked' => TRUE);
$this->form_builder->create_checkbox($params);

$this->form_builder->create_boolean(`params`)

Creates either a checkbox or a radio input for the form. This method check the boolean_mode attribute to determine what type of field, either checkbox or radio, to render.

$options = array(
	'y' => 'Yes',
	'n' => 'No',
)
$params = array('name' => 'my_checkbox', 'options' => $options);
$this->form_builder->create_boolean($params);

$this->form_builder->create_section(`params`)

Creates a section in the form. First checks the value, then the label, then the name attribute then wraps it in the copy_tag.

$params = 'This is a Section Heading';
$this->form_builder->create_section($params);

$this->form_builder->create_copy(`params`)

Creates a copy area for for the form. First checks the value, then the label, then the name attribute then wraps it in the copy_tag.

$params = 'This is a copy area';
$this->form_builder->create_copy($params);

$this->form_builder->create_tooltip(`params`)

Creates a tooltip on the label. Uses the tooltip_format class attribute to determine how to render tooltip.

$params = array('comment' => 'this is the comment for the tooltip', 'label' => 'My Tooltip example');
$this->form_builder->create_tooltip($params);

$this->form_builder->create_custom(`func`, `params`)

Creates a custom input form field. Calls a function and passes it the field params.

function my_custom_field($params)
{
	... code here
}

$this->form_builder->create_custom('my_custom_field', $params);

$this->form_builder->set_validator(`validator`)

Sets the validator object on the form object. The validator object is used to determine if the fields have been filled out properly and will display any errors at the top of the form.

$validator = new Validator();
$this->form_builder->set_validator($validator);

$this->form_builder->set_field_order(`[order_arr]`)

Sets the order of the fields. If an array is passed to the method, then that will be used as opposed to the field values order attribute.

$order = array('name', 'email', 'password');
$this->form_builder->set_field_order($order);

Basic Info

Getting Started

General Topics

Additional Resources

Modules

Specific Module Reference

View Parsing

Javascript

Classes

FUEL Classes Reference

Abstract FUEL Classes Reference

3rd Party Classes

Extended Base Classes

Helpers

FUEL Helpers

3rd Party Helpers

Extended Helpers

FUEL CMS User Guide : Version 0.9.3

Form Builder Class

Initializing the Class

Configuring Form Builder Information

Field Options

Function Reference

$this->form_builder->set_fields(fields)

$this->form_builder->set_field_values(values)

$this->form_builder->render([fields], ['render_format'])

$this->form_builder->render_divs([fields])

$this->form_builder->render_table([fields])

Other Functions

$this->form_builder->create_field(params, [normalize])

$this->form_builder->create_label(params, [use_label])

$this->form_builder->create_text(params)

$this->form_builder->create_submit(params)

$this->form_builder->create_button(params)

$this->form_builder->create_textarea(params)

$this->form_builder->create_hidden(params)

$this->form_builder->create_enum(params)

$this->form_builder->create_multi(params)

$this->form_builder->create_select(params)

$this->form_builder->create_file(params)

$this->form_builder->create_date(params)

$this->form_builder->create_time(params)

$this->form_builder->create_checkbox(params)

$this->form_builder->create_boolean(params)

$this->form_builder->create_section(params)

$this->form_builder->create_copy(params)

$this->form_builder->create_tooltip(params)

$this->form_builder->create_custom(func, params)

$this->form_builder->set_validator(validator)

$this->form_builder->set_field_order([order_arr])