Using HTML Forms

epesi uses the PEAR QuickForm library for HTML forms, wrapped in the Libs/QuickForm module. Create a form with init_module():

$form = & $this->init_module('Libs/QuickForm');

Use the $form object to build out and manage the form.

addElement

The most basic action is adding a QuickForm element. The general syntax is:

$form->addElement($type, $id, $label, $args);

Not every field type needs every argument. Here are the most common element types and the arguments each one takes:

$form->addElement('header', null, $label);
$form->addElement('static', $id, $label, $value);
$form->addElement('text', $id, $label);
$form->addElement('textarea', $id, $label);
$form->addElement('select', $id, $label, $array_of_options);
$form->addElement('checkbox', $id, $label);
$form->addElement('radio', $id, $label, $option_label, $option_id);
$form->addElement('button', $id, $label, $action);
$form->addElement('submit', $id, $label);
$form->addElement('reset', $id, $label);
$form->addElement('hidden', $id, null);
$form->addElement('file', $id, $label);

Notice: always pass labels through the translation function __().

To group several radio fields so the user can pick only one option, give them all the same $id. If you're using the default display function, give the label to only the first field in the group — otherwise the label is repeated next to every option.

addRule

You can attach any number of rules to a field. If a rule isn't satisfied, the form fails validation — though only one error per field is reported, no matter how many rules fail. The most common rules:

$form->addRule($id, $error_message, 'required');
$form->addRule($id, $error_message, 'maxlength');
$form->addRule($id, $error_message, 'minlength');
$form->addRule($id, $error_message, 'email');
$form->addRule($id, $error_message, 'numeric');
$form->addRule($id, $error_message, 'regex', $regex);

The rule names are self-explanatory.

Notice: always pass error messages through the __() translation function.

Adding submit buttons

The default display function puts each field on its own line. To place OK and Cancel buttons on the same line, group them together:

$submit = HTML_QuickForm::createElement('submit','submit_button',$this->lang->ht('Create'));
$cancel = HTML_QuickForm::createElement('button','cancel_button',$this->lang->ht('Cancel'), $place_href_here);
$form -> addGroup(array($submit,$cancel));

Validation

Validate the form, then extract and process its values if validation succeeds:

if ($form->validate()) {
    $values = $form->exportValues();
    ...
}

validate() returns true only if the form was submitted and no errors occurred. Access a field's value as $values[$id], where $id is the id you gave the field.

Notice: an unchecked checkbox submits no value at all for its field. Only a checked checkbox produces a value — 1 — under its $id.

Displaying the form

You're now ready to display the form. Call the display function only after validating the form — QuickForm generates its error messages during validation, and that has to happen before anything is displayed. To display the form:

$form->display();

Or render it to a variable instead of printing it directly:

$form->toHtml();

This is especially useful when working with Themes.

Displaying the form isn't required to retrieve its values — if $form->validate() returns true, you can process the form directly and skip displaying it altogether.