Form API

Form API – Methods of HTML_QuickForm2 class

Overview

HTML_QuickForm2 is a class representing HTML form. It is a subclass of HTML_QuickForm2_Container and thus inherits the API of Container and its ancestors. Only a few additional form-specific methods are defined (and a few previously protected methods are declared public).

Those familiar with HTML_QuickForm package should notice that this approach is quite different from that of HTML_QuickForm class which defined dozens of custom methods. As a result QuickForm2.php file containing HTML_QuickForm2 class is an order of magnitude smaller than QuickForm.php containing HTML_QuickForm.

Constructor of HTML_QuickForm2

HTML_QuickForm2::__construct() accepts the following parameters:

string $id

id attribute for <form> tag

string $method = 'post'

HTTP method used to submit the form.

string|array $attributes = NULL

Additional attributes for <form> tag.

boolean $trackSubmit = TRUE

Whether to track if the form was submitted.

The only way to set id and method attributes is through the constructor. Attempts to change them afterwards will result in an Exception.

When $trackSubmit is on, a hidden field with a specially crafted name is added to the form. If that name is present in $_REQUEST then the form is considered submitted. This is especially useful if you have several HTML_QuickForm2-backed forms on one page or if the form uses GET submit method and the page may receive other $_GET parameters.

When $trackSubmit is off the form only checks that either $_GET or $_POST array (depending on form submit method) is not empty.

Element behind $trackSubmit

<?php
$form 
= new HTML_QuickForm2('trackMe');

// iterating over supposedly empty form
foreach ($form as $element) {
    echo 
$element;
}
?>

output:


<input type="hidden" id="qf:trackMe" name="_qf__trackMe" />

Form values and validation

Unlike simpler elements, form's values cannot be set via setValue() method, data sources should be used. getDataSources() returns the list of form's data sources, setDataSources() replaces that list with a new one and addDataSource() adds a data source to the list. Data source containing submit values (based on a superglobal $_GET or $_POST array) is added automatically if the form is considered submitted.

Coincidentally isSubmitted() method checks whether the list of form data sources contains an instance of HTML_QuickForm2_DataSource_Submit, which usually happens when the form was submitted.

validate() method performs server-side validation.

<?php
if ($form->isSubmitted() && $form->validate()) {
    
// form is valid, process its values
    
doSomeProcessing($form->getValue());
}
?>

is redundant, validate() checks submit status and will return FALSE if the form wasn't submitted.