Display groups are a way to create virtual groupings of elements for display purposes. All elements remain accessible by name in the form, but when iterating over the form or rendering, any elements in a display group are rendered together. The most common use case for this is for grouping elements in fieldsets.
The base class for display groups is
Zend_Form_DisplayGroup. While it can be instantiated
directly, it is usually best to use Zend_Form's
addDisplayGroup() method to do so. This method takes an
array of element names as its first argument, and a name for the display
group as its second argument. You may optionally pass in an array of
options or a Zend_Config object as the third argument.
Assuming that the elements 'username' and 'password' are already set in the form, the following code would group these elements in a 'login' display group:
<?php
$form->addDisplayGroup(array('username', 'password'), 'login');
You can access display groups using the
getDisplayGroup() method, or via overloading using the
display group's name:
<?php
// Using getDisplayGroup():
$login = $form->getDisplayGroup('login');
// Using overloading:
$login = $form->login;
Default Decorators Do Not Need to Be Loaded
By default, the default decorators are loaded during object initialization. You can disable this by passing the 'disableLoadDefaultDecorators' option when creating a display group:
<?php
$form->addDisplayGroup(
array('foo', 'bar'),
'foobar',
array('disableLoadDefaultDecorators' => true)
);
This option may be mixed with any other options you pass,
both as array options or in a Zend_Config object.
Just as with elements, there are some operations which might affect all display groups; these include setting decorators and setting the plugin path in which to look for decorators.
Example 433. Setting Decorator Prefix Path for All Display Groups
By default, display groups inherit whichever decorator paths
the form uses; however, if they should look in alternate
locations, you can use the
addDisplayGroupPrefixPath() method.
<?php
$form->addDisplayGroupPrefixPath('My_Foo_Decorator', 'My/Foo/Decorator');
Example 434. Setting Decorators for All Display Groups
You can set decorators for all display groups.
setDisplayGroupDecorators() accepts an array of
decorators, just like setDecorators(), and will
overwrite any previously set decorators in each display
group. In this example, we set the decorators to simply a
fieldset (the FormElements decorator is necessary to ensure
that the elements are iterated):
<?php
$form->setDisplayGroupDecorators(array(
'FormElements',
'Fieldset'
));
By default, Zend_Form uses the
Zend_Form_DisplayGroup class for display groups.
You may find you need to extend this class in order to provided
custom functionality. addDisplayGroup() does not
allow passing in a concrete instance, but does allow specifying
the class to use as one of its options, using the
'displayGroupClass' key:
<?php
// Use the 'My_DisplayGroup' class
$form->addDisplayGroup(
array('username', 'password'),
'user',
array('displayGroupClass' => 'My_DisplayGroup')
);
If the class has not yet been loaded, Zend_Form
will attempt to do so using Zend_Loader.
You can also specify a default display group class to use with the form such that all display groups created with the form object will use that class:
<?php
// Use the 'My_DisplayGroup' class for all display groups:
$form->setDefaultDisplayGroupClass('My_DisplayGroup');
This setting may be specified in configurations as 'defaultDisplayGroupClass', and will be loaded early to ensure all display groups use that class.
The following methods may be used to interact with display groups:
addDisplayGroup(array $elements, $name, $options = null)addDisplayGroups(array $groups)setDisplayGroups(array $groups)getDisplayGroup($name)getDisplayGroups()removeDisplayGroup($name)clearDisplayGroups()setDisplayGroupDecorators(array $decorators)addDisplayGroupPrefixPath($prefix, $path)setDefaultDisplayGroupClass($class)getDefaultDisplayGroupClass($class)
Zend_Form_DisplayGroup has the following methods,
grouped by type:
-
Configuration:
setOptions(array $options)setConfig(Zend_Config $config)
-
Metadata:
setAttrib($key, $value)addAttribs(array $attribs)setAttribs(array $attribs)getAttrib($key)getAttribs()removeAttrib($key)clearAttribs()setName($name)getName()setDescription($value)getDescription()setLegend($legend)getLegend()setOrder($order)getOrder()
-
Elements:
createElement($type, $name, array $options = array())addElement($typeOrElement, $name, array $options = array())addElements(array $elements)setElements(array $elements)getElement($name)getElements()removeElement($name)clearElements()
-
Plugin loaders:
setPluginLoader(Zend_Loader_PluginLoader $loader)getPluginLoader()addPrefixPath($prefix, $path)addPrefixPaths(array $spec)
-
Decorators:
addDecorator($decorator, $options = null)addDecorators(array $decorators)setDecorators(array $decorators)getDecorator($name)getDecorators()removeDecorator($name)clearDecorators()
-
Rendering:
setView(Zend_View_Interface $view = null)getView()render(Zend_View_Interface $view = null)
-
I18n:
setTranslator(Zend_Translate_Adapter $translator = null)getTranslator()setDisableTranslator($flag)translatorIsDisabled()