^Status|Draft|
^Todo|Fill in missing parts, Form_Group! |


====== Forge Module (Form Generation) ======

**This module is no longer distributed with Kohana versions 2.2 or later. This page will be left intact as a courtesy to existing Forge users.**

The Forge module is a module to easily create and manage forms. You can create forms with built-in validation in one go. Forge coexists with the Form helpers, it doesn't replace it. Forge provides help with rendering, validating and filtering forms, the form helper provides methods to create forms.



===== Creating a form =====

Creating a form is done by instantiating the Forge class

<code php>
$form = new Forge('', 'Add article', 'POST', array('id' => 'article_form'));

</code>

This is the start of each form. The Forge class will accept up to four arguments, all of which are optional. The first argument is the form action, the second is the form title, the third argument is the form submittal method, and the last argument is an array of attributes. 

Here you see only three arguments being used, the last of which is obviously the attribute array. You can also set any of these attributes after the fact or on the fly by using the method below. 

Say we want to change the class and method attribute of the form.

<code php>
$form->set_attr('class', 'form_class')->set_attr('method', 'post');
</code>


==== Adding elements ====

Next step is adding elements.
<code php>
$form->input('title');
</code>
This is the basis of adding elements. Now we set a label and add rules.

<code php>
$form->input('title')->label(true)->rules('required|length[3,40]|valid_alpha_numeric')->value('title');
</code>


==== A complete form ====

<code php>
$form = new Forge('', 'Add article','POST',array('id' => 'article_form'));
$form->set_attr('class', 'form_class')->set_attr('method', 'post');
$form->input('title')->label(true)->rules('required|length[3,40]|valid_alpha_numeric');
$form->input('article')->label('Article text')->rules('required||valid_alpha_numeric');
$form->submit('submit');

if($form->validate())
{
    echo $form->title->value;
    echo $form->article->value;
}
else
{
    // in Kohana < 2.2
    echo $form->html();
    // in Kohana 2.2
    echo $form->render(); 
}
</code>


==== Form methods ====

=== set_attr() ===

''set_attr()'' set an attribute of the <form> element.
There are two parameters:
  * **[array]/[string]** Either the attribute name or an array of attribute names and values
  * **[string]** Attribute value (Default NULL)

<code php>
$form = new Forge('', 'Add article', 'post',array('id', 'article_form'));
$form->set_attr('class', 'form_class');

$form->set_attr(array('class' => 'form_class','id' => 'article_form'));
</code>


=== validate() ===

''validate()'' validates a form, takes no arguments. Returns boolean.

=== as_array() ===

''as_array()'' returns an array with input names and values. Useful for putting your form values into the database.

=== error_format() ===

=== html() ===

Returns a rendered form as a string.
<box red>
In Kohana 2.2 changed to render()
</box>


===== Form Elements ======

Note that all elements except for Form_Group inherit from Form_Input so methods below apply to all of them.



==== Form_Input ====

=== Create input ===

Create an input. Method is chainable.
<code php>$form->input('input_name');</code>


=== Input label ===

Show the field label or not. If the argument is boolean the input label will be based on the input name. Also you can pass the custom label name. Method is chainable.
<code php>->label(TRUE);</code> or
<code php>->label('Custom input name');</code>


=== Input validation ===

Set the validation rules for the field. Method is chainable.
<code php>->rules('list|of|validation|rules')</code> 


=== Input validation using Kohana Validation helper ===

You can utlize rules from [[:helpers:valid|Validation helper]] by prefixing the rule with valid_.  Thus, a rule normally accessible by calling valid::ip would be utilized as: 
<code php>->rules('valid_ip')</code> 


=== Input value ===

Set the default value for the element. Method is chainable.
<code php>->value('input_value')</code> 

=== Extra Attributes ===

You can add extra attributes to input and all other form elements by using attribute name.

**example**
<code php>$form->input('title')->label(TRUE)->class('input_size');</code>

=== Example ===

<code php>
$form->input('title')->label(TRUE)->rules('required|length[0,255]')->value($this->page->title);
</code>



==== Form_Checkbox ====
By default a checkbox checked status is off to turn on just call the checked method and set to true.

=== Example ===

<code php>
$form->checkbox('test')->label(TRUE)->value('1')->checked(TRUE);
</code>

==== Form_Checklist ====

=== Example ===

<code php>
$form->checklist('blocks')->label('Blocks available')->options($option)->rules('required');
</code>

* $option should be sent as an array with each value in the format {'value' = array('label', true|false)} where 'value' will be the value of the checkbox, 'label' will be used as the label and the true|false indicates if the item is checked by default.


==== Form_Dateselect ====

=== Example ===

<code php>
$form->dateselect('date')->label(TRUE)->years(date('Y')-3, date('Y')+5)->value(strtotime($your_date_var));
</code>

* In the above example we are instructing Forge to generate years ranging from 3 years prior and 5 years after the current year.

* Dateselect uses Unix timestamp format internally to calculate dates.  To pass a MySQL date field to the //value()// method, wrap it in the PHP //strtotime// function.



==== Form_Dropdown ====
You can set dropdown with single array or with two-dimensional array. The key will be the option value and the value will be the option text.

=== Example ===

<code php>
$form->dropdown('pizzas')->label(TRUE)->options(array('Hawaiian', 'Margarita'))->selected('1');
</code>

<code php>
$form->dropdown('pizzas')->label(TRUE)->options(array('HA'=>'Hawaiian', 'MA'=>'Margarita'))->selected('MA');
</code>

==== Form_Group ====

Is an instance of the Forge class so you can have groups in your forms. All methods of the Forge class are available save html(). 

=== Example ===

<code php>
$group = $form->group('pizzas')->label(TRUE);
$group->dropdown('pizzas')->label(TRUE)->options(array('Hawaiian', 'Margarita'))->selected('1');
$group->dropdown('bases')->label(TRUE)->options(array('Thin', 'Pan', 'Stuffed'))->selected('2');
</code>

In the view groups get special attention and are rendered differently. You can use groups for example when you need to group some form elements within a `<fieldset>` tag.

==== Form_Hidden ====

In the default template hidden forms are added straight after the <form> tag.

=== Example ===

<code php>$form->hidden('id')->value(1);</code>


==== Form_Password ====

The method 'matches' matches a form field with another form field.

=== Example ===

<code php>
$form->password('password')->label(TRUE);
$form->password('passconf')->label('Password Confirmation')->rules('required|length[5,32]')->matches($form->password);

</code>



==== Form_Submit ====

=== Example ===

<code php>
$form->submit('Submit Button Name');
</code>




==== Form_Textarea ====

=== Example ===

<code php>
$form->textarea('description')->label(TRUE)->rules('length[0,255]')->value($this->page->description);
</code>


==== Form_Upload ====

=== Example ===

If the file exists and the second argument of ''upload()'' method is TRUE, it will overwrite this file. Otherwise it will create an unique name.
<code php>
$form->upload('file', TRUE)->label(TRUE)->rules('required|size[200KB]|allow[jpg,png,gif]');
</code>
The default upload path is configured your upload.php config file (system/config/upload.php).

===== Using Custom Form Templates =====
If you need more control over your form, but still want to take advantage of the automated validation and field re-population provided by the Forge library, you can utilize a custom form template.  This allows you to design the form however you want using HTML.

from: http://forumarchive.kohanaphp.com/index.php/topic,616.msg3841.html#msg3841

=== Example ===
**Controller:** application/controllers/your_controller.php

<code php>
$form = new Forge();
$form->input('username')->label(TRUE)->rules('required');
$form->password('password')->label(TRUE)->rules('required');

if ($form->validate())
{
    // Do stuff
}

echo $form->html('login_form', TRUE);  // Only this is different, specifies to use a custom form
</code>

**View:** application/views/login_form.php

<code php>
<form method="post" action="<?= url::site('login') ?>">
    <?= $username->label() ?>
    <br />
    <?= $username->html() ?>
    <br />
    <?= $username_errors ?>
    <br /><br />
    <?= $password->label() ?>
    <br />
    <?= $password->html() ?>
    <br />
    <?= $password_errors ?>
    <br />
    <input type="submit" value="Login" />
</form>
</code>

**Note:** You don't have to use ''->label()''. You can write the HTML for label or form input fields directly into your form view (e.g. ''<label for="...">''). Use ''$username->value'' to fill in the values for input fields.


===== Saving forms as a library =====
Using Forge you can save forms as a library and thus have access to your form throughout your application. See http://learn.kohanaphp.com/2008/03/13/saving-forms-as-libraries/ for a short tutorial.