Base Element API
Base classes
Element classes in HTML_QuickForm2, including HTML_QuickForm2 itself, are descended from either HTML_QuickForm2_Container or HTML_QuickForm2_Element, class tree for those two abstract classes given below. Common API for elements is mostly defined in HTML_QuickForm2_Node.
HTML_QuickForm2_Container - a common parent class for form elements that can contain other elements (e.g. fieldsets, groups).
HTML_QuickForm2_Element - a common parent class for "scalar" form elements.
Handling HTML attributes
As can be seen from the above tree, all elements are descended from HTML_Common2, so you have access to attribute-handling methods defined in that class. Please refer to HTML_Common2 documentation for more info.
Many elements in HTML_QuickForm2 take advantage of $watchedAttributes
feature of HTML_Common2 to prevent e.g. changing method
attribute of <form> tag and type attribute of
<input> tag or to update the element's value when its name changes.
As all elements need an id attribute for proper
<label> output and for client-side validation, such an attribute will be
automatically generated based on element's name if not given explicitly.
Automatic generation of id attributes
<?php
echo HTML_QuickForm2_Factory::createElement(
'text', 'name', array('id' => 'explicitId')
)->getAttribute('id') . "\n";
echo HTML_QuickForm2_Factory::createElement('text', 'name')
->getAttribute('id') . "\n";
echo HTML_QuickForm2_Factory::createElement('text', 'name')
->getAttribute('id') . "\n";
echo HTML_QuickForm2_Factory::createElement('text', 'name[key]')
->getAttribute('id') . "\n";
echo HTML_QuickForm2_Factory::createElement('submit')
->getAttribute('id') . "\n";
?>
The above code will output:
explicitId
name-0
name-1
name-key-0
qfauto-0
Note that unique ids are generated and that by default an index is appended to a generated
id. If you want to generate an id attribute equal to
name by default, you can set an option named
'id_force_append_index' to FALSE
Automatic generation of id attributes without mandatory indexes
<?php
HTML_Common2::setOption('id_force_append_index', false);
echo HTML_QuickForm2_Factory::createElement(
'text', 'name', array('id' => 'explicitId')
)->getAttribute('id') . "\n";
echo HTML_QuickForm2_Factory::createElement('text', 'name')
->getAttribute('id') . "\n";
echo HTML_QuickForm2_Factory::createElement('text', 'name')
->getAttribute('id') . "\n";
echo HTML_QuickForm2_Factory::createElement('text', 'name[key]')
->getAttribute('id') . "\n";
echo HTML_QuickForm2_Factory::createElement('submit')
->getAttribute('id') . "\n";
?>
The above code will output:
explicitId
name
name-0
name-key
qfauto-0
Methods defined in HTML_QuickForm2_Node
Constructors of all the elements have the same list of parameters, as defined in HTML_QuickForm2_Node:
- string
$name Element name
- string|array
$attributes HTML attributes
- array
$data Additional element-specific data. A
'label'key in this array is understood by every element and is used for element's label. Other possible keys are described in the list of built-in elements.
As a result, HTML_QuickForm2_Factory::createElement() and HTML_QuickForm2_Container::addElement() that pass their arguments to the element's constructor also have constant list of parameters, the first being element type and subsequent ones corresponding to constructor parameters.
Getters and setters for miscellaneous element properties: setName() / getName(), setId() / getId(), setLabel() / getLabel(), getContainer(), getData(), getType().
Setter methods in HTML_QuickForm2 tend to return
$this, so that it is possible to chain their invocations:<?php
$text->setName('aText')
->setLabel('Text input field:');
?>
Methods for getting and changing elements' values: setValue(), getValue(), getRawValue(). Their detailed description is in the section on values and data sources.
Filtering the elements' values is done by addFilter() and addRecursiveFilter() methods. The former is applied directly to element's value on getValue() call and the latter is propagated to contained elements if the element is a Container or applied recursively to the value if element's value is an array.
Validation-related methods: setError() / getError(), createRule(), addRule() / removeRule(), isRequired(). Described in the section on validation.
Output-related methods
The elements implement magic __toString() method so they can be used in string contexts:
<?php
$element = new HTML_QuickForm2_Element_InputText(
'textBox', array('size' => 20, 'id' => 'textBoxId')
);
echo $element;
?>
with output being
<input type="text" id="textBoxId" size="20" name="textBox" />
Complex output needs of form elements (including HTML_QuickForm2 itself) are covered by render() method accepting a specialized Renderer object.
A helpful feature of HTML_QuickForm2 is the ability to "freeze" form elements, displaying their values without HTML input tags. This may be used for an additional confirmation step after form submit or for sending a filled form via email, among other things. Two methods deal with this: toggleFrozen() and persistentFreeze(), the former toggling the "frozen" status and the latter "persistent freeze" behaiour. If persistent freeze is on, element's value will be kept (and possibly submitted) in a hidden field.
Freezing the element
<?php
$box = new HTML_QuickForm2_Element_InputCheckbox(
'aBox', array('value' => 'boxValue', 'checked' => 'checked')
);
echo $box . "\n\n";
$box->toggleFrozen(true);
echo $box . "\n\n";
$box->persistentFreeze(false);
echo $box;
?>
the above code results in
<input type="checkbox" value="boxValue" checked="checked" name="aBox" id="aBox-0" />
<code>[x]</code><input type="hidden" name="aBox" value="boxValue" id="aBox-0" />
<code>[x]</code>