PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

Display Groups

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.

Global Operations

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 446. 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 447. 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'
));

Using Custom Display Group Classes

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.

Methods for Interacting With Display Groups

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 Methods

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()

Zend Framework