Groups

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:

<?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 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:

<?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('&nbsp;'"<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" />&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.