Groups
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:
<?php
$named = $form->addGroup('groupName');
$innerNamed = $named->addText('elementName');
$innerComplex = $named->addText('elementOuter[elementInner]');
$nameless = $form->addGroup();
$innerNameless = $nameless->addText('elementName');
echo $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:
<?php
$namedGroup = $form->addGroup('groupName');
$namelessElement = $namedGroup->addText();
$namelessGroup = $form->addGroup();
$namedElement = $namelessGroup->addText('elementName');
echo $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 uniquevalueattributes). 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:
<?php
$foo = $form->addGroup('foo');
$foo->addText('bar');
$foo->addText('baz[quux]');
$foo->setValue(array(
'bar' => 'bar value',
'baz' => array('quux' => 'baz[quux] value')
));
print_r($foo->getValue());
?>
getValue() will return array having the same structure, output of the above code being
Array
(
[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:
<?php
$group = new HTML_QuickForm2_Container_Group(
'foo', null, array('separator' => "<br />\n")
);
$group->addText('first');
$group->addText('second');
$group->addText('third');
echo $group;
echo "\n\n";
$group->setSeparator(array(' ', "<br />\n"));
echo $group;
?>
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" /> <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.