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.
HTML_QuickForm2::__construct() accepts the following parameters:
$id
id
attribute for <form>
tag
$method
= 'post'
HTTP method used to submit the form.
$attributes
= NULLAdditional attributes for <form>
tag.
$trackSubmit
= TRUEWhether 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" />
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.