Form Builder Class
The Form_builder class allows you to create forms by passing in configurable array values. Each field has a base set of parameters that can be set for it. Other fields have additional parameters you can pass to it (e.g. the date field). This class works with the MY_Model form_fields method which returns table meta information regarding the fields of a table.
The Form.php class is required if a form object is not passed in the initialization process.
Custom form fields can be configured in the fuel/application/config/custom_fields.php file.
Additional information about creating forms using Form_builder can be found in the General Topics area.
Properties Reference
| Property | Default Value | Description |
|---|---|---|
| public | ||
| form | object | |
| id | none | Id to be used for the containing table or div |
| css_class | form | Css class to be used with the form |
| form_attrs | method="post" action="" | Form tag attributes |
| label_colons | none | Add colons to form labels? |
| textarea_rows | 10 | Number of rows for a textarea |
| textarea_cols | 60 | Number of columns for a textarea |
| text_size_limit | 40 | Text size for a text input |
| submit_name | none | Submit id and name values |
| submit_value | Submit | Submit value (what the button says) |
| cancel_value | none | Cancel value (what the button says) |
| cancel_action | none | What the cancel button does |
| reset_value | none | Reset button value (what the button says) |
| other_actions | none | Additional actions to be displayed at the bottom of the form |
| use_form_tag | 1 | Include the form opening/closing tags in rendered output |
| exclude |
array() |
Exclude these fields from the form |
| hidden |
array('id') |
Hidden fields |
| readonly |
array() |
Readonly fields |
| disabled |
array() |
Disabled fields |
| displayonly |
array() |
For display purposes only |
| date_format | m/d/Y | Date format for date type fields |
| section_tag | h3 | Section html tag |
| copy_tag | p | Copy html tag |
| fieldset | none | Field set name |
| name_array | none | Put the form fields into an array for namespacing |
| name_prefix | none | Prefix the form fields as an alternatie to an array for namespacing |
| class_type_prefix | field_type_ | The CSS class prefix to associate with each field type |
| names_id_match | 1 | Determines if the names and ids match if using a name_prefix or name_array |
| key_check | none | The keycheck value used for forms that create session unique session variables to prevent spamming |
| key_check_name | none | The keycheck form name used for forms that create session unique session variables to prevent spamming |
| tooltip_format | <span title="{?}" class="tooltip">[?]</span> | Tooltip formatting string |
| tooltip_labels | 1 | Use tooltip labels? |
| single_select_mode | auto | 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 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 | Booleon mode can be checkbox or enum (which will display radio inputs) |
| display_errors_func | display_errors | The function used to generate errors... usually display_errors is the name |
| display_errors | none | Displays errors at the top of the form if TRUE |
| question_keys |
array('how', 'do', 'when', 'what', 'why', 'where', 'how', 'is', 'which', 'did', 'any', 'would', 'should', 'could') |
Adds question marks to the label if has these words in the label |
| show_required | 1 | Show the required fields text at the bottom of the form |
| required_indicator | * | Indicator for a required field |
| required_text | <span class="required">{required_indicator}</span> required fields | The required field text |
| label_layout | left | Label layout... can be left or top |
| has_required | none | Does the form have required fields |
| render_format | table | Default render format |
| row_id_prefix | none | The row id prefix |
| lang_prefix | form_label_ | Language prefix to be applied before a label |
| custom_fields |
array() |
Custom fields |
| auto_execute_js | 1 | Autmoatically execute the javascript for the form |
| html_prepend | none | Prepended HTML to the form HINT: Can include JS script tags |
| html_append | none | Appended HTML to the form HINT: Can include JS script tags |
| representatives |
array() |
An array of fields that have arrays or regular expression values to match against different field types (e.g. 'number'=>'bigint|smallint|tinyint|int') |
| js |
array() |
|
| css |
array() |
|
| no_css_js | none | Used to not display the CSS and JS when rendering to prevent issues with nested forms and post_processing |
| template | none | The html template view file to use for rendering the form when using "render_template" |
| is_pre_processing | none | Flag set when form builder is pre processing fields |
| is_post_processing | none | Flag set when form builder is post processing fields |
| protected | ||
| _html | N/A | |
| _fields | N/A | |
| _values | N/A | |
| _cached | N/A | |
| _pre_process | N/A | |
| _post_process | N/A | |
| _rendering | N/A | Used to prevent infinite loops when calling form_builder reference from within a custom form field |
| _rendered_field_types | N/A | Holds all the fields types rendered |
| _is_nested | N/A | Used to detect nested fields |
| CI | N/A | |
Function Reference [+]
$this->form_builder->initialize([$params=array()])
Initialize preferences.
Returns
void
Parameters
(array) $params
$this->form_builder->set_params($params)
Set object parameters.
Returns
void
Parameters
(array) $params
$this->form_builder->clear()
Same as reset.
Returns
void
$this->form_builder->reset()
Clear class values.
Returns
void
$this->form_builder->set_fields($fields)
Set the fields for the form. Check the normalize_params method for possible values.
Returns
void
Parameters
(array) $fields
$this->form_builder->add_field('$key', $val, ['$order'=NULL])
Set the fields for the form. Check the normalize_params method for possible values.
Returns
void
Parameters
(string) $key The key to associate with the field (array) $val The field parameters (int) $order The order value of the parameter
$this->form_builder->remove_field('$key')
Removes a field before rendering.
Returns
void
Parameters
(string) $key
$this->form_builder->fields(['$key'=NULL])
Returns the fields for the form. If a key value is passed, it will only return that one field.
Returns
array
Parameters
(string) $key field key
$this->form_builder->values(['$key'=NULL])
Returns the values of the form fields. If a key value is passed, it will only return that one value.
Returns
array
Parameters
(string) $key field key
$this->form_builder->set_field_values($values)
Sets the value attribute for the fields of the form. Often times this is database or post data.
Returns
void
Parameters
(array) $values
$this->form_builder->render(['$fields'=NULL], ['$render_format'=NULL], ['$template'=NULL])
Render the HTML output.
Returns
string
Parameters
(array) $fields fields values... will overwrite anything done with the set_fields method previously (string) $render_format 'divs or table (string) $template 'a view path (only used for the template)
$this->form_builder->render_divs(['$fields'=NULL])
Render the HTML output.
Returns
string
Parameters
(array) $fields fields values... will overwrite anything done with the set_fields method previously
$this->form_builder->render_table(['$fields'=NULL])
Render the HTML output.
Returns
string
Parameters
(array) $fields fields values... will overwrite anything done with the set_fields method previously
$this->form_builder->render_template('$template', ['$fields'=NULL], ['$parse'=TRUE])
Render the HTML output using a specified template. Will provide an array of form fields that can be parsed like so {my_field}.
Returns
string
Parameters
(string) $template the name of the template view file to use (array) $fields fields values... will overwrite anything done with the set_fields method previously
$this->form_builder->id()
Returns the id for a form.
Returns
string
$this->form_builder->normalize_params($val, [$defaults=array()])
Get the default values for any field.
Returns
array
Parameters
(array) $val fields values... will overwrite anything done with the set_fields method previously
$this->form_builder->create_field($params, ['$normalize'=TRUE])
Looks at the field type attribute and determines which form field to render. IMPORTANT! You probably shouldn't call this method from within a custom field type because it may create an infinite loop!.
Returns
string
Parameters
(array) $params fields parameters (boolean) $normalize shoud the normalization be ran again?
$this->form_builder->create_label($params, ['$use_label'=TRUE])
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.
Returns
string
Parameters
(array) $params fields parameters (boolean) $use_label shoud the label be displayed?
$this->form_builder->create_text($params)
Creates the text input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_password($params)
Creates the password input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_select($params)
Creates the select input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_checkbox($params)
Creates the checkbox input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_radio($params)
Creates the radio input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_textarea($params)
Creates the textarea input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_hidden($params)
Creates the hidden input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_submit($params)
Creates a submit button input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_button($params)
Creates a basic form button for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_enum($params)
Creates the either select field or a set of radio buttons. If set to auto and their are less than 2 options, then it will render radio inputs. Otherwise it will render a select input.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_multi($params)
Creates the multi select input for the form (this is overwritten by the Fuel_custom_fields to give more functionaltity).
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_file($params)
Creates the file input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_date($params)
Creates the date input for the form. Adds the datepicker so that you can use jquery to add the datepicker jquery plugin.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_time($params)
Creates the time input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_datetime($params)
Creates the date/time input for the form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_number($params)
Creates a number field for the form... basically a text field.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_email($params)
Creates an email field for the form... supported by modern browsers.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_phone($params)
Creates a phone field for the form... supported by modern browsers.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_range($params)
Creates a range field for the form... supported by modern browsers.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_boolean($params)
Creates either a checkbox or a radio input for the form. This method check the boolean_mode class attribute to determine what type of field, either checkbox or radio, to render.
Returns
string
Parameters
(array) $params fields parameters
$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 section_tag.
Returns
string
Parameters
(array) $params fields parameters
$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.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_tooltip($params)
Creates a tooltip on the label. Creates a tooltip on the label. Uses the tooltip_format class attribute to determine how to render tooltip.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_readonly($params)
Creates a read only field.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_fieldset($params)
Creates a legend for a form.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_nested($params, ['$return_object'=FALSE])
Creates a nested form_builder object and renders it.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->create_custom($func, '$params')
Creates a custom input form field. Calls a function and passes it the field params.
Returns
string
Parameters
(array) $func fields parameters
$this->form_builder->load_custom_fields($file)
Adds multiple custom fields.
Returns
void
Parameters
(array) $file Array of custom fields to load
$this->form_builder->register_custom_field('$key', '$custom_field')
Add a custom field type.
Returns
void
Parameters
(string) $key key used to identify the field type (string) $custom_field function or class/method array to use for rendering
$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.
Returns
void
Parameters
(array) $validator fields parameters
$this->form_builder->get_validator()
Returns 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.
Returns
object
$this->form_builder->validate(['$validator'=NULL])
Handles validation for the form builder fields. If valid it will return TRUE. If not, it will return an array of errors.
Returns
mixed
Parameters
(object) $validator the validator object to use for validating (optional)
$this->form_builder->set_field_order([$order_arr=array()])
Sets the order of the fields. An array value with the keys as the order for the field.
Returns
string
Parameters
(array) $order_arr fields parameters
$this->form_builder->append_html('$html')
Appends HTML to the form. Used to append HTML after the form... good for Javascript files.
Returns
void
Parameters
(string) $html HTML to append
$this->form_builder->prepend_html('$html')
Prepends HTML to the form. Used to prepend HTML before the form... good for Javascript files.
Returns
void
Parameters
(string) $html HTML to prepend
$this->form_builder->set_pre_process('$field', $func)
Registers a pre process function for a field.
Returns
void
Parameters
(string) $field (array) $func
$this->form_builder->set_post_process('$field', $func)
Registers a post process function for a field.
Returns
void
Parameters
(string) $field (array) $func
$this->form_builder->pre_process_field_values()
Alters all the field values that have pre_process attribute specified.
Returns
void
$this->form_builder->post_process_field_values([$posted=array()], ['$set_post'=TRUE])
Alters all the field post values that have post_process attribute specified.
Returns
void
$this->form_builder->set_representative('$type', ['$match'=''])
Sets a representative for a field type. This allows for one field type to represent several field types (e.g. number = int, bigint, smallint, tinyint,...etc).
Returns
void
Parameters
(string) $type The field type to be the representative (mixed) $match Either an array or a regex that other fields must match
$this->form_builder->remove_representative('$type')
Removes a representative for a field type. This removes a representative globally for all fields.
Returns
void
Parameters
(string) $type The field type to be the representative
$this->form_builder->add_js(['$js'=NULL], ['$key'=NULL])
Adds a js file to be rendered with the form a representative for a field type.
Returns
void
Parameters
(string) $js A js file name (mixed) $key A key value to associate with the JS file (so it only gets loaded once). Or an associative array of keyed javascript file names
$this->form_builder->remove_js(['$key'=NULL])
Removes a javascript file.
Returns
void
Parameters
(string) $key A js file name or an array of file names
$this->form_builder->get_js(['$js'=NULL])
Returns the javascript used for the form.
Returns
array
Parameters
(string) $js The key name of a javascript file used when adding
$this->form_builder->add_css(['$css'=NULL], ['$key'=NULL])
Adds a CSS file to be rendered with the form a representative for a field type.
Returns
void
Parameters
(string) $css A CSS file name (mixed) $key A key value to associate with the CSS file (so it only gets loaded once). Or an associative array of keyed CSS file names
$this->form_builder->get_css(['$css'=NULL])
Returns the CSS used for the form.
Returns
array
Parameters
(string) $css The key name of a CSS file used when adding
$this->form_builder->remove_css(['$key'=NULL])
Removes a css file.
Returns
void
Parameters
(string) $key A css file name or an array of file names
$this->form_builder->options_from_model('$model', [$params=array()])
Returns an array of options if a model is specified.
Returns
array
Parameters
(mixed) $model model, model/method or module/model/method
$this->form_builder->simple_field_value($params)
Looks for value, label, then name as the values.
Returns
string
Parameters
(array) $params fields parameters
$this->form_builder->label_lang('$key')
Helper method that returns the language key value if it exist, otherwise it returns FALSE.
Returns
string
Parameters
(string) $key
$this->form_builder->is_nested()
Returns a boolean value as to whether the rendered form_builder instance is nested or not.
Returns
boolean