Built-in Elements
Prev		Next

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');
?>

Standard HTML form elements
Type name	Class	Description, extra `$data` keys, extra methods
`'button'`	HTML_QuickForm2_Element_Button	`<button></button>` elements. `$data` may contain `'content'` key with HTML to add between `<button></button>` tags. Implements setContent() / getContent() methods.
`'checkbox'`	HTML_QuickForm2_Element_InputCheckbox	`<input type="checkbox" />` elements. `$data` may contain `'content'` key with a label that should be "glued" to checkbox. Implements setContent() / getContent() methods.
`'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. Implements setContent() / getContent() methods.
`'reset'`	HTML_QuickForm2_Element_InputReset	`<input type="reset" />` elements
`'select'`	HTML_QuickForm2_Element_Select	`<select></select>` elements. `$data` may contain the following keys `'options'` Data to populate element's options with. Passed to HTML_QuickForm2_Element_Select::loadOptions(). `'intrinsic_validation'` By default only submit values corresponding to options present in the element are returned. Setting this to FALSE will return all submit values (useful if options are added on client side). Implements methods for adding options
`'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

Custom elements
Type name	Class	Description, extra `$data` keys, extra methods
`'date'`	HTML_QuickForm2_Element_Date	Group of selects used to input dates (and times). Described in a separate section.
`'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	Two or more select elements, selecting the value in the first changes options in the second and so on. Described in a separate section.
`'repeat'`	HTML_QuickForm2_Container_Repeat	Repeats a given 'prototype' Container multiple times. Described in a separate section.
`'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 `'content'` Content of the static element, text or markup. `'tagName'` Name of the tag to wrap around content, e.g. `'div'`. The tag will use Static element's attributes. `'forceClosingTag'` Whether to output closing tag in case of empty content, `<foo></foo>` vs. `<foo />`. Implements setContent() / getContent() methods and setTagName().

basic-elements.php example installed with the package shows all built-in elements.

Registering additional elements

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);
}
?>

setContent() / getContent() methods

"Content" these methods deal with differs from element to element. For Button elements it is the text to output between <button></button> tags, for Static elements this content is essentially the element itself, it may or may not be wrapped in a tag. For Checkbox and Radio elements this is the label that is returned "glued" to the element by its __toString() method, as opposed to a regular label that is only output by a Renderer.

Setting elements' content


<?php
echo HTML_QuickForm2_Factory::createElement(
         'button', 'aButton', array('type' => 'submit', 'id' => 'buttonId')
     )->setContent('Button text') . "\n";

echo HTML_QuickForm2_Factory::createElement('static')
     ->setContent('A static element') . "\n";

echo HTML_QuickForm2_Factory::createElement('static')
     ->setId('staticId')
     ->setTagName('div')
     ->setContent('Another static element') . "\n";

echo HTML_QuickForm2_Factory::createElement(
        'radio', 'aRadio', array('id' => 'radioId', 'value' => 'yes')
     )->setContent('Click the radio') . "\n";

echo HTML_QuickForm2_Factory::createElement(
        'checkbox', 'aBox', array('id' => 'boxId', 'value' => 'yes')
     )->setContent('Click the checkbox')
      ->setLabel('Will not be printed here') . "\n";
?>

output:


<button id="buttonId" type="submit" name="aButton">Button text</button>
A static element
<div id="staticId">Another static element</div>
<input type="radio" value="yes" id="radioId" name="aRadio" /><label for="radioId">Click the radio</label>
<input type="checkbox" id="boxId" value="yes" name="aBox" /><label for="boxId">Click the checkbox</label>

Adding options to Select elements

<option>s and <optgroup>s can be added either one by one using addOption() and addOptgroup() method or loaded from an associative array using loadOptions().

Two ways to add options


<?php
$selectSlow = new HTML_QuickForm2_Element_Select('slow');
$selectSlow->addOption('PEAR', 1);
$groupOne = $selectSlow->addOptgroup('HTML');
$groupOne->addOption('HTML_AJAX', 2);
$groupOne->addOption('HTML_Common2', 3);
$groupOne->addOption('HTML_QuickForm2', 4, array('style' => 'background: #808080'));
$groupTwo = $selectSlow->addOptgroup('HTTP');
$groupTwo->addOption('HTTP_Download', 5);
$groupTwo->addOption('HTTP_Request2', 6);


$selectFast = new HTML_QuickForm2_Element_Select('fast');
$selectFast->loadOptions(array(
    1 => 'PEAR',
    'HTML' => array(
        2 => 'HTML_AJAX',
        3 => 'HTML_Common2',
        4 => 'HTML_QuickForm2'
    ),
    'HTTP' => array(
        5 => 'HTTP_Download',
        6 => 'HTTP_Request2'
    )
));

echo $selectSlow . "\n" . $selectFast;
?>

output:


<select name="slow" id="slow-0">
        <option value="1">PEAR</option>
        <optgroup label="HTML">
                <option value="2">HTML_AJAX</option>
                <option value="3">HTML_Common2</option>
                <option style="background: #808080" value="4">HTML_QuickForm2</option>
        </optgroup>
        <optgroup label="HTTP">
                <option value="5">HTTP_Download</option>
                <option value="6">HTTP_Request2</option>
        </optgroup>
</select>
<select name="fast" id="fast-0">
        <option value="1">PEAR</option>
        <optgroup label="HTML">
                <option value="2">HTML_AJAX</option>
                <option value="3">HTML_Common2</option>
                <option value="4">HTML_QuickForm2</option>
        </optgroup>
        <optgroup label="HTTP">
                <option value="5">HTTP_Download</option>
                <option value="6">HTTP_Request2</option>
        </optgroup>
</select>

Note, however, that only the first way allows passing additional attributes.

Static elements

Static elements are used to add text or markup to the form that will be later output as if it was a form element. Unlike standard form elements it obviosly cannot have a submit value so will only consider getting its value (setValue() is equivalent to setContent() for these elements) from data sources that do not implement HTML_QuickForm2_DataSource_Submit.

Being descended from HTML_Common2, Static elements can have attributes as do all other elements. It is also possible to use setTagName() to provide a name for a tag that will use these attributes and wrap around element's content.


<?php
if ($pic = loadPictureDataFromSomewhere()) {
    $form->addStatic('picture', array(
              'src' => $pic['url'], 'width' => $pic['width'],
              'height' => $pic['height'], 'alt' => $pic['title']
           ))
         ->setTagName('img', false)
         ->setLabel('Existing picture:');
} else {
    $form->addFile('picture_upload')
         ->setLabel('Upload new picture');
}
?>

Static elements will prevent setting tag name to a name of form-related tag (i.e. 'div' will work, 'input' will not).

Prev	Form elements	Next
Form API	PEAR Manual	Groups

Built-in Elements

List of elements

Registering additional elements

setContent() / getContent() methods

Adding options to Select elements

Static elements