FUEL CMS User Guide : Version 0.9.3


Form Class

The Form class provides an alternative way to render forms from CodeIgniter's Form Helper.

Initializing the Class

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

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

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

$this->load->library('form', array('attrs' => 'method="get"', 'error_highlight_cssclass' => 'error'));

Why a Form Class?

CodeIgniter has it's own Form helper. There are a couple reasons why FUEL uses the Form class instead of the CI Form helper:

  1. The Form class is used in combination with the Form_builder and Validator classes and so code control is important
  2. The integration with other classes made it crucial to be bundled up as an object that could be shared

Unlike CI's helper, this Form class will automatically insert an ID attribute for most of the fields. This can be overwritten with id="[custam_value]" passed to any of the methods below that have an $attrs parameter.

Configuring Form Information

There are several public properties you can use to configure the Form Class:


Function Reference

$this->form->open([attrs], [validator])

Will create a form open tag. The $attrs parameter will be the attributes of the form (can be an array also). The $validator parameter is a Validator Class object (optional). 

$validator = new Validator();
echo $this->form->open('id="my_form"', $validator); 
// will echo the following
<form action="" method="post" id="my_form">

$this->form->open_multipart([attrs], [validator])

Will create a form open tag that has multipart attribute. The $attrs parameter will be the attributes of the form (can be an array also). The $validator parameter is a Validator Class object (optional). 

$validator = new Validator();
echo $this->form->open_multipart('id="my_form"', $validator); 
// will echo the following
<form action="" method="post" id="my_form">

$this->form->close([html_before_form][add_csrf_field])

Will create a form open tag that has multipart attribute. The $html_before_form parameter is HTML to insert before closing the tag (optional). The $add_csrf_field parameter is whether to include a hidden field of the csrf token if csrf is turned on. 

echo $this->form->close('');
// will echo the following
<</form>

$this->form->fieldset_open('legend', ['attrs'])

Will create a fieldset for the form. The $legend parameter is the name to use in the legend. The $attrs parameter is optional HTML attributes to use on the legend (optional). 

echo $this->form->fieldset_open('MY Form Legend', 'id="my_legend"');
// will echo the following


<legend id="my_legend">MY Form Legend</legend>

$this->form->fieldset_close()

Will create a closing fieldset for the form.

echo $this->form->fieldset_close();
// will echo the following
</fieldset>

$this->form->text('name', ['value'], [attrs])

Creates a text form field. The $name will also produce the id value of the field. The $value parameter is the value attribute of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->text('email', 'dvader@deathstar.com', 'class="txt_field"');
// will echo the following
<input type="text" name="email" id="email" value="dvader@deathstar.com" class="txt_field" />

$this->form->password('name', ['value'], [attrs])

Creates a password form field. The $name will also produce the id value of the field. The $value parameter is the value attribute of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->hidden('passowrd', 'abc134', 'class="txt_field"');
// will echo the following
<input type="passowrd" name="pwd" id="pwd"  value="" class="txt_field" />

$this->form->search('name', ['value'], [attrs])

Creates a search form field. The $name will also produce the id value of the field. The $value parameter is the value attribute of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->search('searh', 'Search...', 'class="txt_field"');
// will echo the following
<input type="searh" name="searh" id="searh" value="Search..." class="txt_field" />

$this->form->hidden('name', ['value'], [attrs])

Creates a hidden form field. The $name will also produce the id value of the field. The $value parameter is the value attribute of the field. The $attrs parameter can be either an array or a string(optional). Hidden fields don't normally have attributes. 

echo $this->form->hidden('id', '1', 'class="txt_field"');
// will echo the following
<input type="hidden" name="id" id="id" value="1" />

$this->form->radio('name', ['value'], [attrs])

Creates a radio form field. The $name will also produce the id value of the field. The $value parameter is the value attribute of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->radio('yesno', 'yes', '');
echo $this->form->radio('eitheror', 'no', '');

// will echo the following
<input type="radio" name="yesno" id="eitheror" value="yes" />
<input type="radio" name="yesno" id="eitheror" value="no" />

$this->form->checkbox('name', ['value'], [attrs])

Creates a checkbox form field. The $name will also produce the id value of the field. The $value parameter is the value attribute of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->checkbox('yesno', 'yes', '');
// will echo the following
<input type="checbock" name="yesno" id="yesno" value="yes" />

$this->form->file('name', [attrs])

Creates a file upload form field (notice there is no value attribute). The $name will also produce the id value of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->file('myfile', 'class="file_class"');
// will echo the following
<input type="file" name="myfile" id="myfile" value="" class="file_class" />

$this->form->select('name', [options], ['value'], [attrs], ['first_option'])

Creates a select form field. The $name will also produce the id value of the field. The $options parameter is a key value array for the options. A nested array will yield option groups. The $value parameter is the value attribute of the field and will select the appropriate option. The $attrs parameter can be either an array or a string(optional). The $first_option parameter is the first option value (e.g. "Select one of these..."). 

$options = array();
$options['a'] = 'Option A';
$options['b'] = 'Option B';
$options['c'] = 'Option C';
echo $this->form->select('my_options', $options, 'b', 'class="select_class"', 'Select one of these...');
// will echo the following
<select name="my_options" id="my_options" class="select_class">
	<option value="" label="Select one of these...">Select one of these...</option>
	<option value="a" label="A">A</option>
	<option value="b" label="B" selected="selected">B</option>
	<option value="b" label="C">C</option>
</select>

$this->form->textarea('name', ['value'], [attrs])

Creates a textarea form field. The $name will also produce the id value of the field. The $value parameter is the value attribute of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->textarea('mytextfield', 'My text goes here.', 'class="txt_field"');
// will echo the following
<textarea name="mytextfield" id="mytextfield" class="txt_field">
My text goes here.
</textarea>

$this->form->button('value', 'name', [attrs], 'use_input_type')

Creates a button form field. (note how the $value and $name are flip-flopped which is different from most of the other field creation methods). The $value parameter is the value attribute of the field. The $name will also produce the id value of the field. The $attrs parameter can be either an array or a string(optional). The $use_input_type parameter determines whether a button or input type of button is used. Default is TRUE. 

echo $this->form->button('mybutton', 'Click Me', 'class="btn"', FALSE);
// will echo the following
<button type="button" name="mybutton" id="mybutton" value="Click Me" class="btn" />mybutton</button>

// with the last parameter as TRUE
echo $this->form->button('mybutton', 'Click Me', 'class="btn"', TRUE);
// will echo the following
<input type="button" name="mybutton" id="mybutton" value="Click Me" class="btn" />

$this->form->submit('value', 'name', [attrs])

Creates a submit button. (note how the $value and $name are flip-flopped which is different from most of the other field creation methods). The $value parameter is the value attribute of the field. The $name will also produce the id value of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->submit('Submit', 'submit', 'class="submit"');
// will echo the following
<input type="submit" name="submit" id="submit" value="Submit" class="submit" />

$this->form->reset('value', 'name', [attrs])

Creates a password form field (note how the $value and $name are flip-flopped which is different from most of the other field creation methods). The $value parameter is the value attribute of the field. The $name will also produce the id value of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->reset('Reset', 'reset', 'class="reset_field"');
// will echo the following
<input type="reset" name="reset" id="reset" value="Reset" 'class="reset_field"' />

$this->form->image('src', 'name', ['value'], [attrs])

Creates a password form field. The $src the image src value. The $name will also produce the id value of the field. The $value parameter is the value attribute of the field. The $attrs parameter can be either an array or a string(optional). 

echo $this->form->image('assets/images/my_img.jpg', 'go_button', 'go', 'class="img_field"');
// will echo the following
<input type="image" src="assets/images/my_img.jpg" name="go_button" value="go" id="go_button" 'class="img_field"' />

Form::prep('str')

Static method that preps a form fields values. The $str is the value to be prepped. 

echo Form::prep('This will safely prep the form field text with entities like &amp; in it');
// will echo the following
This will safely prep the form field text with entities like &amp; in it

Form::do_checked('val')

Static method that checks a checkbox or radio. If a $val is 'yes', 'y', 1, or TRUE, then the checked attribute will be created 

$myval = (!empty($_POST['myval'])) ? $_POST['myval'] : '';
echo $this->form->checkbox('mycheckbox', 'yes', Form::do_checked($myval=='yes'));
// will echo the following
<input type="checbock" name="mycheckbox" id="mycheckbox" value="yes" checked="checked" />

Form::do_disabled('val')

Static method that sets disabled attribute of a form element. The $str will prep the form fields text value. 

$myval = (!empty($_POST['myval'])) ? $_POST['myval'] : '';
echo $this->form->text('mytext', '', Form::do_disabled($myval==''));
// will echo the following
<input type="text" name="mytext" id="mytext" value="" disabled="disabled" />

Form::do_read_only('val')

Static method that sets read only attribute of a form element The $str will prep the form fields text value. 

$myval = (!empty($_POST['myval'])) ? $_POST['myval'] : '';
echo $this->form->text('mytext', '', Form::do_read_only($myval==''));
// will echo the following
<input type="text" name="mytext" id="mytext" value="" readonly="readonly" />

Form::create_id('name')

Static method that creates the id attribute for the field and label. This will safely create an id field based on the name of a field. 

echo Form::create_id('my_array_field[1]');
// will echo the following
my_array_field_1