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 is done by instantiating the Forge class

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

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.

$form->set_attr('class', 'form_class')->set_attr('method', 'post');

Next step is adding elements.

$form->input('title');

This is the basis of adding elements. Now we set a label and add rules.

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

$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();
}

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)

$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'));

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

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

Returns a rendered form as a string.

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

Create an input. Method is chainable.

$form->input('input_name');

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.

->label(TRUE);

or

->label('Custom input name');

Set the validation rules for the field. Method is chainable.

->rules('list|of|validation|rules')

You can utlize rules from Validation helper by prefixing the rule with valid_. Thus, a rule normally accessible by calling valid::ip would be utilized as:

->rules('valid_ip')

Set the default value for the element. Method is chainable.

->value('input_value')

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

example

$form->input('title')->label(TRUE)->class('input_size');

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

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

$form->checkbox('test')->label(TRUE)->value('1')->checked(TRUE);

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

* $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('date')->label(TRUE)->years(date('Y')-3, date('Y')+5)->value(strtotime($your_date_var));

* 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.

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.

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

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

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().

$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');

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.

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

$form->hidden('id')->value(1);

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

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

$form->submit('Submit Button Name');

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

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.

$form->upload('file', TRUE)->label(TRUE)->rules('required|size[200KB]|allow[jpg,png,gif]');

The default upload path is configured your upload.php config file (system/config/upload.php).

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.php#msg3841

Controller: application/controllers/your_controller.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

View: application/views/login_form.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>

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.

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.