Elements
Вернуться к: HTML_QuickForm2
Elements
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.
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.
HTML_QuickForm2_Node API overview
Only public methods that are of interest to package users are described in this section. Other methods are mostly useful for those wishing to extends the package and will be described in a separate documentation section targeted at them.
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 tables below.
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 next section.
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(). Please consult the section on validation.
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" />
More complex output needs are covered by render() method.
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" />
<tt>[x]</tt><input type="hidden" name="aBox" value="boxValue" id="aBox-0" />
<tt>[x]</tt>
HTML_QuickForm2_Container API overview
In addition to methods defined in HTML_QuickForm2_Node, Container defines DOM-like API for handling of child elements: appendChild(), insertBefore(), removeChild(), getElementById(), getElementsByName(). Those who have worked with Javascript or PHP's DOM extension should find these familiar.
DOM-like API for Container
<?php
$fieldset = new HTML_QuickForm2_Container_Fieldset();
$radioOne = $fieldset->appendChild(
new HTML_QuickForm2_Element_InputRadio('aRadio', array('id' => 'radioOne'))
);
$radioThree = $fieldset->appendChild(
new HTML_QuickForm2_Element_InputRadio('aRadio', array('id' => 'radioThree'))
);
$radioTwo = $fieldset->insertBefore(
new HTML_QuickForm2_Element_InputRadio('aRadio', array('id' => 'radioTwo')),
$radioThree
);
echo $fieldset->getElementById('radioOne') . "\n\n";
$fieldset->removeChild($radioOne);
foreach ($fieldset->getElementsByName('aRadio') as $radio) {
echo $radio . "\n";
}
?> will output
<input type="radio" value="on" id="radioOne" name="aRadio" />
<input type="radio" value="on" id="radioTwo" name="aRadio" />
<input type="radio" value="on" id="radioThree" name="aRadio" />
A few convenience methods are also available: getElements() returns an array with all the Container's elements and addElement() creates an element of a given type and adds it to the Container. Thanks to method overloading you can also perform addEltype() calls where 'eltype' is an element type known to HTML_QuickForm2_Factory (see below for the list of such types and examples).
Container also implements Countable and IteratorAggregate SPL interfaces, allowing to easily count the immediate children and iterate over them. It also has getRecursiveIterator() method which returns an instance of HTML_QuickForm2_ContainerIterator for recursive iteration over all child elements.
SPL interfaces support
<?php
$outer = new HTML_QuickForm2_Container_Fieldset();
$inner = $outer->addElement('fieldset')->setId('inner');
$inner->addElement('text', 'textName')->setId('textId');
echo count($outer) . "\n";
foreach ($outer as $child) {
echo $child->getId() . "\n";
}
echo "\n";
foreach ($outer->getRecursiveIterator() as $child) {
echo $child->getId() . "\n";
}
?> The above code will output
1
inner
inner
textId
List of elements
The following is a list of non-abstract descendants of HTML_QuickForm2_Node. These elements are pre-registered with HTML_QuickForm2_Factory and thus can be instantiated with HTML_QuickForm2_Factory::createElement() and added to a Container with either HTML_QuickForm2_Container::addElement() or its overloaded addEltype() method using "Type name" from tables below.
<?php
// will create an instance of HTML_QuickForm2_Element_Textarea
$area = HTML_QuickForm2_Factory::createElement('textarea', 'areaName');
// will add a new instance of HTML_QuickForm2_Element_Select to $container
$select = $container->addElement('select', 'selectName');
// will add a new instance of HTML_QuickForm2_Element_InputText to $container
$text = $container->addText('textName');
?>
New element types can be registered by HTML_QuickForm2_Factory::registerElement(), HTML_QuickForm2_Factory::isElementRegistered() checks whether an element is known to Factory.
<?php
HTML_QuickForm2_Factory::registerElement(
'dualselect', 'HTML_QuickForm2_Element_DualSelect'
);
// ...
if (HTML_QuickForm2_Factory::isElementRegistered('dualselect')) {
$form->addElement('dualselect', 'dualselectDemo', $attributes, $config);
}
?>
| Type name | Class | Description, extra $data keys |
|---|---|---|
| 'button' | HTML_QuickForm2_Element_Button | <button></button> elements. $data may contain 'content' key with HTML to add between <button></button> tags. |
| 'checkbox' | HTML_QuickForm2_Element_InputCheckbox | <input type="checkbox" /> elements. $data may contain 'content' key with a label that should be "glued" to checkbox. |
| 'fieldset' | HTML_QuickForm2_Container_Fieldset | <fieldset></fieldset> elements, labels for them will be rendered as <legend></legend>. |
| 'file' | HTML_QuickForm2_Element_InputFile | <input type="file" /> elements. This element validates itself by checking a relevant 'error' field in $_FILES array. $data may contain 'messageProvider' and 'language' keys for setting up localized error messages. |
| 'hidden' | HTML_QuickForm2_Element_InputHidden | <input type="hidden" /> elements |
| 'image' | HTML_QuickForm2_Element_InputImage | <input type="image" /> elements |
| 'inputbutton' | HTML_QuickForm2_Element_InputButton | <input type="button" /> elements |
| 'password' | HTML_QuickForm2_Element_InputPassword | <input type="password" /> elements |
| 'radio' | HTML_QuickForm2_Element_InputRadio | <input type="radio" /> elements. $data may contain 'content' key with a label that should be "glued" to radiobutton. |
| 'reset' | HTML_QuickForm2_Element_InputReset | <input type="reset" /> elements |
| 'select' | HTML_QuickForm2_Element_Select | <select></select> elements. $data may contain the following keys
|
| 'submit' | HTML_QuickForm2_Element_InputSubmit | <input type="submit" /> elements |
| 'text' | HTML_QuickForm2_Element_InputText | <input type="text" /> elements |
| 'textarea' | HTML_QuickForm2_Element_Textarea | <textarea></textarea> elements |
| Type name | Class | Description, extra $data keys |
|---|---|---|
| 'date' | HTML_QuickForm2_Element_Date | Group of selects used to input dates (and times). $data may contain
|
| 'group' | HTML_QuickForm2_Container_Group | Group of form elements. Several elements may be grouped into a single entity and this entity used as a single element. Date and Hierselect are based on Group. |
| 'hierselect' | HTML_QuickForm2_Element_Hierselect | Hierarchical select element. Two or more select elements, selecting the value in the first changes options in the second and so on. $data may contain
Everything else is passed on to created selects. |
| 'script' | HTML_QuickForm2_Element_Script | Class for adding inline javascript to the form, based on Static. |
| 'static' | HTML_QuickForm2_Element_Static | A pseudo-element used to add text or markup to the form, when that text should be output similar to form element. $data may contain
|
Вернуться к: HTML_QuickForm2