Improve this Doc

Form Fields

When using Form::addField it will initialize an approirate field class and add associate it with the form (with Form_Field::form property).

class Form_Field_Line

Regular line of input

class Form_Field_Text

Textarea input

class Form_Field

Implements generic Form Field.

Form Field can operate in two modes. If you simply add the field into any object which does NOT have form as an owner, then field appears as a stand-alone view:

$menu->add('Form_Field_Line', 'search');

In most cases, however, you do add a field into a form:

$form->addField('Line', 'search');

Note

you can also add a search field inside any view within a Form, see form/layout for more info.

Form_Field::setForm()

Automatically called when Field appears to be inside Form. This will enable validation hook and will allow field to read data on POST.

When field is added into Form directly, it also surrounds itself with a field_row which often contains a label (See form/layout).

Form_Field::setCaption($label)

Changes label of the field. $label is localized.

Form_Field::displayFieldError($message)

Will execute field error assuming that js_widget is used. Use Form::error instead.

Form_Field::set($value)

Set default value for the field.

Form_Field::setNoSave()

Will make sure that field value is not saved when you call save()

Adjacent elements to the field

Here are several methods, which can be used to add other elements relatively to the field.

Form_Field::addButton($label, $position)

Will add button eihter position=’before’ or position=’after’ the field. If $position is a hash, then ‘position’ key will be used for positioning and the rest will be passed down into add('Button', <here>).

Additionally the button will automatically be linked with the field in the following way - every time the field value changes, it’s set as a “val” data attribute of the button. This allows you to easily capture value of a linked field when button is clicked (see Button::onClick):

$field = $form->addField('name');
$field->addButton('Greet')->onClick(function($b, $data){
    return "Hello, ".$data['val'];
} );
Form_Field::beforeField()
Form_Field::afterField()
Form_Field::aboveField()
Form_Field::belowfield()

Those methods return a new view, which is located just to the proper side of the field. You can chain this method with add() and drop another view in there:

$form->getElement('name')->beforeField()->add('Text')->set('Mr:');
Form_Field::setFieldHint()

Displays a hint under a field (usually with gray text).

Form_Field::addIcon()

Adds icon at the right side of the field. Second argument can be a link, or JS chain which will be executed when icon is clicked.

Field properties

Form_Field::get()

Returns value of the field. Use $val = $form['field'] unless you call this method from within a Field class.

Form_Field::setAttr($attr, $value)

Set attribute on the <input> such as setAttr('maxlength',50)

Buiding HTML

Field takes a slightly different path in building HTML it outputs. instead of using a template, it converts all the attributes into a tag with getTag() method.

Form_Field::getTag()

This method takes many differet argument variations and produces an HTML tag with properties.

Form_Field::getInput()

Will return HTML only for the <input> element.

Form_Field::render()

When inside form, will return whole form line, along with label (if form template supports)