This is documentation for Kohana v2.3.x.

Status	Final Draft
Todo	Proof read

Form Helper

The Form helper provides methods to assist you in creating forms. It does not do validation or filtering. If you want to generate your forms with validation and filtering you can do so with the Forge library

Getting Started

You'll need to use a line like this to begin the form.

print form::open(string $submit, array $attr, array $hidden );

Where $submit is a relative URL like '/class/method' and $attr is an array with attributes, like array('id' ⇒ 'forumid', 'class'⇒'login_form'). All three can be left blank. If you leave the first blank, the submission URL will be assumed to be the page being submitted from. $hidden is an array of hidden form fields.

Adding Fields

You may add form fields as you would in straight HTML, but the option exists to create them using php. Here are some examples.

print form::dropdown($data, $options, $selected)
print form::textarea($data)
print form::input($data)

Methods

open()

Opens a form for submitting data. The parameters are:

[string] (optional) URI of a form processing agent (defaults to current URL)
[array] (optional) array of HTML attributes (defaults to method=post)
[array] (optional) parameters for hidden fields to be created immediately after the form tag

In order to open the form, you simply need to:

print form::open()

This uses the default values, using POST to submit the form to the current page.

To add attributes:

// Submits the page to: domain.tld/products/search.php
// CSS class 'search_form' is applied
print form::open('products/search', array('class'=>'search_form'));
 
// Stay on the current page, and add a hidden input field named 'type' with value: 'product'
print form::open(NULL, array(), array('type'=>'product'));
 
// Sending a form to the current page using GET
print form::open(NULL, array('method'=>'get'));

open_multipart()

Opens a form for submitting binary data via POST. The parameters are:

[string] (optional) URI of a form processing agent (defaults to current URL)
[array] (optional) array of HTML attributes (defaults to method=post)
[array] (optional) parameters for hidden fields to be created immediately after the form tag

Examples:

// Opens multipart form with action set to current url
print form::open_multipart();

Results in HTML

<form action="http://localhost/index.php/welcome" enctype="multipart/form-data" method="post">

input()

Creates an HTML form input tag. Defaults to a text type. The parameters are:

[string]/[array] data input name and id or an array of HTML attributes
[string] input value, when using a name
[string] extra string attached to the end of the attributes
[bool] encode existing html entities (default TRUE)

Example:

print form::input('field_name', 'field_value', ' style="text-align: right;"');

Result in HTML:

<input type="text" id="field_name" name="field_name" value="field_value" style="text-align: right;" />

It's not necessary to use all parameters.

Example:

print form::input(); // don't use parameters
print form::input('field_name'); // use only 1 parametr - for name and id
print form::input('field_name', 'field_value'); // use only 2 parameters - for name, id and value

Result in HTML:

<input type="text" id="" name="" value="" />
<input type="text" id="field_name" name="field_name" value="" />
<input type="text" id="field_name" name="field_name" value="field_value" />

To create a form reset button, add the attribute of “type” set to “reset”.

Example:

form::input(array('type'=>'reset','name'=>'reset'),"Clear Form");

Result in HTML:

<input type="reset" name="reset" value="Clear Form"  />

hidden()

'hidden' generates a hidden form field. The parameters are:

[string]/[array] data for key attributes
[string] value of the field – default = ””

Example:

// Please note that the print() statements are for display purposes only
print form::hidden("fieldName","fieldValue");
 
$array = array('field1' => 'value1', 'field2' => 'value2');
print form::hidden($array);

It will result in HTML as:

<input type="hidden" name="fieldName" value="fieldValue" />
 
<input type="hidden" name="field1" value="value1" />
<input type="hidden" name="field2" value="value2" />

password()

'password' generates a password form field. The parameters are:

[string]/[array] data for key attributes
[string] value of the field – default = ””
[string] extra string to be added to the end of the attributes – default = ””

Example:

// Please note that the print() statements are for display purposes only
print Kohana::debug(form::password("fieldName","fieldValue"));
print Kohana::debug(form::password("fieldName","fieldValue",' id="fieldId"'));
$array=array('name'=>'fieldName','value'=>'fieldValue','id'=>'fieldId','class'=>'formField');
print Kohana::debug(form::password($array));

It will result in HTML as:

<input type="password" id="fieldName" name="fieldName" value="fieldValue" />
 
<input type="password" id="fieldName" name="fieldName" value="fieldValue"id="fieldId" />
 
<input type="password" id="fieldId" name="fieldName" value="fieldValue" class="formField" />

upload()

Generate HTML form input tag type “file” for upload files:

The parameters are:

[string]/[array] - attribute name or array of attributes
[string] - attribute value [optional]
[string] - extra additional [optional]

Example

$attributes = array('name' => 'file_1', 'class' => 'your-class');
echo form::upload($attributes, 'path/to/local/file')

Result in HTML:

<input type="file" name="file_1" value="path/to/local/file" class="your-class" />

textarea()

Creates an HTML form textarea tag.

print form::textarea(string/array $data, string $value)

The parameters are:

[string]/[array] textarea name or an array of HTML attributes
[string] textarea value, when using a name
[string] extra string attached to the end of the attributes
[bool] encode existing html entities (default TRUE)

Example

print form::textarea('field_name', 'field_value');

Result in HTML:

<textarea id="field_name" name="field_name">field_value</textarea>

We can also use array for the first parameter. Look at this example:

print form::textarea(array('name' => 'field_name', 'value' => 'field_value', 'class' => 'our_class'));

Result in HTML:

<textarea id="field_name" name="field_name" class="our_class">field_value</textarea>

dropdown()

Creates a drop down selection box. The parameters are:

[string|array] input name or array of HTML attributes
[array] the select options, when using input name
[string|array] the option or an array of options to be selected by default
[string] extra string to be added to the end of the attributes – default = ””

Example:

$selection = array('basic' =>'Basic', 'standard' => 'Standard', 'custom' => 'Custom');
// The 'standard' option will be the default selection
print form::dropdown('input_dropdown',$selection,'standard');
 
$selection = array('basic' =>'Basic', 'standard' => 'Standard', 'custom' => 'Custom', 'something' => 'Something');
print form::dropdown(array('name' => 'input_dropdown[]', 'multiple' => 'multiple', 'size' => 4), $selection, array('standard', 'basic'));
 
$selection = array('basic' =>array('basic1' => 'Basic1', 'basic2' => 'Basic2'), 'standard' => 'Standard', 'custom' => 'Custom', 'something' => 'Something');
print form::dropdown(array('name' => 'input_dropdown[]', 'multiple' => 'multiple', 'size' => 6), $selection, array('standard', 'basic1'));

Browser output:

checkbox()

Creates a 'tick box' type selection box.

The parameters are:

[string/array] input name or an array of HTML attributes
[string] input value, when using a name
[boolean] make the checkbox checked by default
[string] a string to be attached to the end of the attributes

Example:

print form::label('check_spam_box', 'Always send me Spam (Opt in): ');
print form::checkbox('check_spam_box', 'send_spam');
print form::label('check_money_box', 'Never send me Money (Opt out): ');
print form::checkbox('check_money_box', 'send_no_money', TRUE);

Results in HTML

<label for="check_spam_box">Always send me Spam (Opt in): </label>
<input type="checkbox" id="check_spam_box" name="check_spam_box" value="send_spam" />
<label for="check_money_box">Never send me Money (Opt out): </label>
<input type="checkbox" id="check_money_box" name="check_money_box" value="send_no_money" checked="checked" />

Browser output:

Always send me Spam (Opt in): Never send me Money (Opt out):

radio()

Generates a 'radio' type selection box, similar to checkbox, but allows for easier multiple selections.

The parameters are:

[string/array] input name or an array of HTML attributes
[string] input value, when using a name
[boolean] make the radio selected by default
[string] a string to be attached to the end of the attributes

Example:

print form::label('radio_cute_box', 'I am cute: ');
print form::radio('radio_cute_box', 'is_cute').'<br />';
print form::label('radio_single_box', 'I am single: ');
print form::radio('radio_single_box', 'is_single', TRUE).'<br />';
print form::label('radio_rich_box', 'I am rich: ');
print form::radio('radio_rich_box', 'is_rich').'<br />';

Results in HTML

<label for="radio_cute_box">I am cute: </label>
<input type="radio" name="radio_cute_box" value="is_cute" /><br />
<label for="radio_single_box">I am single: </label>
<input type="radio" name="radio_single_box" value="is_single" checked="checked" /><br />
<label for="radio_rich_box">I am rich: </label>
<input type="radio" name="radio_rich_box" value="is_rich" /><br />

Browser output

I am cute:
I am single:
I am rich:

submit()

Creates a 'submit' type button for the form.

The parameters are:

[string/array] input name or an array of HTML attributes
[string] input value, when using a name
[string] a string to be attached to the end of the attributes

Example:

print form::submit('submit', 'Send');

Results in HTML

<input type="submit" id="submit" name="submit" value="Send" />

button()

Creates a button for the form. Note this is not the same as the button associated with input type 'submit' or 'reset'.

The parameters are:

[string/array] input name or an array of HTML attributes
[string] input value, when using a name
[string] a string to be attached to the end of the attributes

Example:

print form::button('button', 'Does not do Much');

Results in HTML

<button type="button" id="button" name="button">Does not do Much</button>

label()

Creates a label for a form entry field.

The parameters are:

[string/array] label “for” name or an array of HTML attributes
[string] label text or HTML
[string] a string to be attached to the end of the attributes

Example:

print form::label('imageup', 'Image Uploads');

Results in HTML

<label for="imageup">Image Uploads</label>

attributes()

Returns an attribute string, from an array of HTML attributes in key/value format, sorted by form attributes first.

The parameters are:

[array] HTML attributes array

Example:

print form::attributes(array('id' => 'input_name', 'class' => 'submission'));

Outputs

id="input_name" class="submission"

open_fieldset()

Creates a fieldset opening tag. The fieldset HTML element is used to logically group together elements in a form, and draw a box around them.

The parameters are:

[array] an array of HTML attributes
[string] a string to be attached to the end of the attributes

Example:

print form::open_fieldset(array('class' => 'important'));

Results in HTML

<fieldset class="important">

close_fieldset()

Generates a fieldset closing tag

Example:

print form::close_fieldset();

Results in HTML

</fieldset>

legend()

Creates a legend for describing a fieldset.

The parameters are:

[string] legend text or HTML
[array] an array of HTML attributes
[string] a string to be attached to the end of the attributes

Example:

print form::legend('More about you', array('id' => 'more_infos'));

Results in HTML

<legend id="more_infos">More about you</legend>

close()

In order to close the form, you simply need to:

print form::close()

Or you can set parameter:

print form::close('</div>')

Result in HTML:

</form></div>