Form API
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 idattribute 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.