Pour configurer un décorateur, passez un tableau d'options ou un objet Zend_Config à son constructeur. Aussi, un tableau peut être passé à setOptions(), ou un objet Zend_Config à setConfig().

Options de base:

L'interface des décorateurs spécifie les méthodes pour agir sur les options. Les voici :

Les décorateurs sont destinés à agir avec tous les objets du formulaire, Zend_Form, Zend_Form_Element, Zend_Form_DisplayGroup, et toute classe en dérivant. La méthode setElement() vous permet de passer l'objet au décorateur sur lequel il travaille. getElement() vous permet de récupérer cet objet depuis le décorateur.

Chaque méthode render() des décorateurs accepte en paramètre une chaîne $content. Lorsque le premier décorateur est appelé, cette chaîne est en toute logique vide, alors que tous les appels successifs travailleront sur le contenu précédent. Selon le type de décorateur et ses options, la chaîne sera alors remplacée, précédée ou suivie du nouveau contenu décoré. Dans ces deux derniers cas, un séparateur optionnel peut être utilisé.

Zend_Form est fourni avec quelques décorateurs de base, voyez le chapitre sur les décorateurs standards pour plus de détails.

Si vos rendus HTML sont complexes, ou si vous avez besoin de beaucoup de personnalisation, vous pouvez alors créer vos propres décorateurs.

Les décorateurs ont juste besoin d'implémenter l'interface Zend_Form_Decorator_Interface. Celle-ci spécifie les méthodes suivantes :

interface Zend_Form_Decorator_Interface
{
    public function __construct($options = null);
    public function setElement($element);
    public function getElement();
    public function setOptions(array $options);
    public function setConfig(Zend_Config $config);
    public function setOption($key, $value);
    public function getOption($key);
    public function getOptions();
    public function removeOption($key);
    public function clearOptions();
    public function render($content);
}

Pour vous simplifier la tâche, vous pourriez considérer le fait d'étendre Zend_Form_Decorator_Abstract, qui implémente toutes les méthodes de l'interface sauf render().

Par exemple, imaginons que vous ne souhaitiez pas vous encombrer avec un nombre important de décorateurs, et que vous vouliez afficher les principale caractéristiques d'un élément grâce à un seul décorateur (label, élément, messages d'erreur et description), le tout dans une div. Voici comment vous pourriez procéder :

class My_Decorator_Composite extends Zend_Form_Decorator_Abstract
{
    public function buildLabel()
    {
        $element = $this->getElement();
        $label = $element->getLabel();
        if ($translator = $element->getTranslator()) {
            $label = $translator->translate($label);
        }
        if ($element->isRequired()) {
            $label .= '*';
        }
        $label .= ':';
        return $element->getView()
                       ->formLabel($element->getName(), $label);
    }

    public function buildInput()
    {
        $element = $this->getElement();
        $helper  = $element->helper;
        return $element->getView()->$helper(
            $element->getName(),
            $element->getValue(),
            $element->getAttribs(),
            $element->options
        );
    }

    public function buildErrors()
    {
        $element  = $this->getElement();
        $messages = $element->getMessages();
        if (empty($messages)) {
            return '';
        }
        return '<div class="errors">' .
               $element->getView()->formErrors($messages) . '</div>';
    }

    public function buildDescription()
    {
        $element = $this->getElement();
        $desc    = $element->getDescription();
        if (empty($desc)) {
            return '';
        }
        return '<div class="description">' . $desc . '</div>';
    }

    public function render($content)
    {
        $element = $this->getElement();
        if (!$element instanceof Zend_Form_Element) {
            return $content;
        }
        if (null === $element->getView()) {
            return $content;
        }

        $separator = $this->getSeparator();
        $placement = $this->getPlacement();
        $label     = $this->buildLabel();
        $input     = $this->buildInput();
        $errors    = $this->buildErrors();
        $desc      = $this->buildDescription();

        $output = '<div class="form element">'
                . $label
                . $input
                . $errors
                . $desc
                . '</div>'

        switch ($placement) {
            case (self::PREPEND):
                return $output . $separator . $content;
            case (self::APPEND):
            default:
                return $content . $separator . $output;
        }
    }
}

Vous pouvez maintenant placer ce décorateur dans les chemins des décorateurs :

// pour un élément:
$element->addPrefixPath('My_Decorator',
                        'My/Decorator/',
                        'decorator');

// pour tous les éléments:
$form->addElementPrefixPath('My_Decorator',
                            'My/Decorator/',
                            'decorator');

Dès à présent, vous pouvez indiquer que vous voulez utiliser le décorateur 'Composite', (c'est son nom de classe sans le préfixe) et l'attacher à un élément :

// Ecrase les éventuels décorateurs de cet élément avec le notre:
$element->setDecorators(array('Composite'));

Cet exemple vous montre comment rendre un contenu HTML complexe à partir de propriétés d'un élément, en une seule passe. Il existe des décorateurs qui ne s'occupent que d'une propriété de l'élément auquel ils sont rattachés, 'Errors' et 'Label' en sont d'excellents exemples qui permettent un placement fin.

Par exemple, si vous souhaitez simplement informer l'utilisateur d'une erreur, mais sans lui montrer les messages d'erreurs, vous pouvez créer votre propre décorateur 'Errors' :

class My_Decorator_Errors
{
    public function render($content = '')
    {
        $output = '<div class="errors">La valeur est invalide, rééssayez</div>';

        $placement = $this->getPlacement();
        $separator = $this->getSeparator();

        switch ($placement) {
            case 'PREPEND':
                return $output . $separator . $content;
            case 'APPEND':
            default:
                return $content . $separator . $output;
        }
    }
}

Dans cet exemple particulier, comme le segment final du nom de la classe, 'Errors', respecte la syntaxe de Zend_Form_Decorator_Errors, il sera alors utilisé à la place du décorateur par défaut -- ceci signifie que vous n'avez pas besoin de l'injecter dans un élément particulier. En nommant vos fins de classes de décorateurs comme celles des décorateurs standards, vous pouvez changer la décoration sans agir sur les éléments en question.

Comme les décorateurs agissent souvent sur une propriété d'un élément, et en fonction de la décoration précédente, il peut être utile d'afficher juste le rendu d'un décorateur particulier, sur un élément. Ceci est possible par la surcharge des méthodes dans les classes principales de Zend_Form (formulaires, sous-formulaires, groupes d'affichage, éléments).

Pour effectuer ceci, appelez simplement render[nom-du-décorateur](), où "[nom-du-décorateur]" est le nom court de votre décorateur (sans son préfixe de classe). Il est aussi possible de lui passer optionnellement du contenu, par exemple :

// rend juste le décorateur Label de cet élément:
echo $element->renderLabel();

// Rend juste le décorateur Fieldset, en lui passant du contenu:
echo $group->renderFieldset('fieldset content');

// rend juste le tag HTML du formulaire, avec du contenu:
echo $form->renderHtmlTag('wrap this content');

Si le décorateur n'existe pas, une exception sera levée.

Ceci peut être particulièrement utile lors du rendu d'un formulaire avec le décorateur ViewScript ; là où chaque élément utilise ses décorateurs pour rendre du contenu, mais de manière très fine.