FUEL CMS User Guide : Version 1.5.2


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