Base Element API

Base Element API – Common methods for Elements and Containers

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.

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>