Groups – Combining several form elements into a single entity

Groups overview

HTML_QuickForm2_Container_Group is a specialized subclass of Container which allows to combine several form elements into an entity behaving like a single form element. Key features:

  • A named group prepends its name to the contained elements' names;

  • HTML_QuickForm2_Container_Group implements setValue() method;

  • Grouped elements are processed in a different way than ungrouped ones by renderers.

Groups can be used for

  • Keeping together elements having the same name (checkboxes and radios).

  • Visual grouping of elements (e.g. 'Back', 'Next' and 'Cancel' buttons of a wizard).

  • Logical grouping of elements (e.g. fields to input first and last name of a person).

Groups are also used as a base for custom elements like Date and Hierselect.

Names of grouped elements

If you add an element to a group having a name itself, group's name will be prepended to the element's name. If an element is added to a group without a name, its name will not be changed:

$innerNamed $named->addText('elementName');
$innerComplex $named->addText('elementOuter[elementInner]');

$nameless $form->addGroup();
$innerNameless $nameless->addText('elementName');

$innerNamed->getName() . ', ' $innerComplex->getName()
', ' $innerNameless->getName();

results in the following output

groupName[elementName], groupName[elementOuter][elementInner], elementName

Note also the difference between a nameless element in a named group and vice versa:

$namelessElement $namedGroup->addText();

$namelessGroup $form->addGroup();
$namedElement $namelessGroup->addText('elementName');

$namelessElement->getName() . ', ' $namedElement->getName();

which results in

groupName[], elementName

The only elements which will work reliably if given a name like foo[] are checkboxes (assuming they have unique value attributes). Do not give such names to any other elements, use explicit indexes: foo[0], foo[1].

Groups' values

Unlike other Container-based elements, Group implements a working setValue() method. Values for the Group should be given as an associative array having a structure similar to what $_GET / $_POST will contain on form submit:


'bar' => 'bar value',
'baz' => array('quux' => 'baz[quux] value')


getValue() will return array having the same structure, output of the above code being

    [bar] => bar value
    [baz] => Array
            [quux] => baz[quux] value


Outputting groups

$data parameter for group's constructor may contain the custom 'separator' key. It is either a string or an array of strings that will be used to separate elements' HTML in output. setSeparator() / getSeparator() methods are also available:

= new HTML_QuickForm2_Container_Group(
'foo'null, array('separator' => "<br />\n")




$group->setSeparator(array('&nbsp;'"<br />\n"));

results in output

<input type="text" name="foo[first]" id="first-0" /><br />
<input type="text" name="foo[second]" id="second-0" /><br />
<input type="text" name="foo[third]" id="third-0" />

<input type="text" name="foo[first]" id="first-0" />&nbsp;<input type="text" name="foo[second]" id="second-0" /><br />
<input type="text" name="foo[third]" id="third-0" />

The default output for groups is quite simple, containing only elements' HTML and separators. You will need to use render() instead of __toString() to customize the output (the latter uses Default Renderer under the hood, but does not allow output customization). Consult the section on Default Renderer for additional info.

List of built-in Elements, element-specific methods and configuration (Previous) Date and Hierselect (Next)
Last updated: Sat, 16 Feb 2019 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report.
View this page in:
  • English

User Notes:

There are no user contributed notes for this page.