^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 [[addons:forge|Forge library]] 

===== Getting Started =====

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

<code php>
print form::open(string $submit, array $attr, array $hidden );
</code>

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.

<code php>
print form::dropdown($data, $options, $selected)
print form::textarea($data)
print form::input($data)
</code>

===== 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:

<code php>print form::open()</code>
This uses the default values, using POST to submit the form to the current page.


To add attributes:

<code php>
// Submits the page to: domain.tld/products/search.html
// 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'));
</code>





==== 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:**
<code php>
// Opens multipart form with action set to current url
print form::open_multipart();
</code>
Results in HTML
<code html>
<form action="http://localhost/index.php/welcome" enctype="multipart/form-data" method="post">
</code>

==== 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:**

<code php>
print form::input('field_name', 'field_value', ' style="text-align: right;"');
</code>

Result in HTML:

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


It's not necessary to use all parameters.

**Example:**

<code php>
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
</code>

Result in HTML:
<code 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" />
</code>

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

**Example:**

<code php>
form::input(array('type'=>'reset','name'=>'reset'),"Clear Form");
</code>
Result in HTML:
<code html>
<input type="reset" name="reset" value="Clear Form"  />
</code>
==== hidden() ====

'hidden' generates a hidden form field. 
The parameters are:
  * [string]/[array] data for key attributes
  * [string] value of the field -- default = "" 

**Example:**

<code php>
// 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);
</code>

It will result in HTML as:

<code html>
<input type="hidden" name="fieldName" value="fieldValue" />

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


==== 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:**

<code php>
// 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));
</code>

It will result in HTML as:

<code html>
<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" />
</code>



==== 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**
<code php> 
$attributes = array('name' => 'file_1', 'class' => 'your-class');
echo form::upload($attributes, 'path/to/local/file')
</code>

Result in HTML:

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

==== textarea() ====

Creates an HTML form textarea tag.

<code php>
print form::textarea(string/array $data, string $value)
</code>

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**
<code php>
print form::textarea('field_name', 'field_value');
</code>

Result in HTML:
<code html>
<textarea id="field_name" name="field_name">field_value</textarea>
</code>

We can also use array for the first parameter. Look at this example:
<code php>
print form::textarea(array('name' => 'field_name', 'value' => 'field_value', 'class' => 'our_class'));
</code>

Result in HTML:
<code html>
<textarea id="field_name" name="field_name" class="our_class">field_value</textarea>
</code>



==== 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:**
<code php>
$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'));
</code>
**Browser output:**
<html>
<select id="input_dropdown" name="input_dropdown">
<option value="basic">Basic</option>
<option selected="selected" value="standard">Standard</option>
<option value="custom">Custom</option>
</select>

<select id="input_dropdown[]" multiple="multiple" size="4" name="input_dropdown[]">
<option selected="selected" value="basic">Basic</option>
<option selected="selected" value="standard">Standard</option>
<option value="custom">Custom</option>
<option value="something">Something</option>
</select>

<select id="input_dropdown[]" multiple="multiple" size="6" name="input_dropdown[]">
<optgroup label="basic">
<option selected="selected" value="basic1">Basic1</option>
<option value="basic2">Basic2</option>
</optgroup>
<option selected="selected" value="standard">Standard</option>
<option value="custom">Custom</option>
<option value="something">Something</option>
</select>
</html>


==== 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:**
<code php>
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);
</code>
Results in HTML
<code 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" />
</code>
**Browser output:**

<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" />
</html>


==== 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:**
<code php>
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 />';
</code>
Results in HTML

<code 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 />
</code>
**Browser output**

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






==== 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:**
<code php>
print form::submit('submit', 'Send');
</code>

Results in HTML
<code html>
<input type="submit" id="submit" name="submit" value="Send" />
</code>




==== 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:**
<code php>
print form::button('button', 'Does not do Much');
</code>

Results in HTML
<code html>
<button type="button" id="button" name="button">Does not do Much</button>
</code>



==== 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:**
<code php>
print form::label('imageup', 'Image Uploads');
</code>

Results in HTML
<code html>
<label for="imageup">Image Uploads</label>
</code>


==== 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:**
<code php>
print form::attributes(array('id' => 'input_name', 'class' => 'submission'));
</code>

Outputs 
<code html>
id="input_name" class="submission"
</code>

==== 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:**
<code php>
print form::open_fieldset(array('class' => 'important'));
</code>

Results in HTML
<code html>
<fieldset class="important">
</code>

==== close_fieldset() ====

Generates a fieldset closing tag

**Example:**
<code php>
print form::close_fieldset();
</code>

Results in HTML
<code html>
</fieldset>
</code>

==== 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:**
<code php>
print form::legend('More about you', array('id' => 'more_infos'));
</code>

Results in HTML
<code html>
<legend id="more_infos">More about you</legend>
</code>

==== close() ====

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

<code php>print form::close()
</code>

Or you can set parameter:

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

Result in HTML:

<code html></form></div>
</code>