Para configurar un decorador, pase un array de opciones o un objeto Zend_Config a este constructor, a un array setOptions() , o a un objeto Zend_Config setConfig() .

Opciones estándar incluyen:

La interface del decorador especifica los métodos para interactuar con las opciones. Esto incluye:

Decoradores son diseñados para interactuar con varios tipos de clases Zend_Form : Zend_Form , Zend_Form_Element , Zend_Form_DisplayGroup , y todas las clases derivan de ellas. El método setElement() permite determinar el objeto del decorador que esta actualmente trabajando con, y getElement() es usado para recuperarlo.

Cada método decorador render() acepta una cadena $content . Cuando el primer decorador es llamado, esta cadena esta tipicamente vacía, mientras las subsecuentes llamadas serán puestas. Basados en el tipo de decorador y en las opciones pasadas, el decorador ya sea reemplazará la cadena, antenpodrá la cadena o adjuntará la cadena; una separador opcional será usado en las dos últimas situaciones.

Zend_Form entrega muchos decoradores estándar; ver el capítulo Decoradores estándar para detalles.

Si encuentra que sus necesidades son complejas o necesita una enorme personalización, debería considerar crear un decorador personalizado.

Los decoradores necesitan implementar sólo Zend_Form_Decorator_Interface . La interface especifica lo siguiente:

interface Zend_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);
}

Para hacerlo mas simple, simplemente puede extender Zend_Form_Decorator_Abstract , el cual implementa todos los métodos excepto render() .

Como ejemplo, digamos que quiere reducir el número de decoradores que utiliza, y construir un decorador compuesto que se encargó de renderizar la etiqueta generadora, el elemento, cualquier mensaje de error, y descripción en un div HTML. Puede construir como un decorador compuesto como sigue:

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;
        }
    }
}

Puede entonces ubicarlo en el directorio del decorador:

// para un elemento:
$element->addPrefixPath('My_Decorator',
                        'My/Decorator/',
                        'decorator');

// para todos los elementos:
$form->addElementPrefixPath('My_Decorator',
                            'My/Decorator/',
                            'decorator');

Puede especificar este decorador como compuesto (composite) y adjuntarlo a un elemento:

// Sobreescribe los decoradores existentes con este otro:
$element->setDecorators(array('Composite'));

Mientras este ejemplo mostró cómo crear un decorador que genera salidas complejas de muchas propiedades de elementos, puede también crear decoradores que manejen un solo aspecto de un elemento; los decoradores 'Decorator' y 'Label' son excelentes ejemplos para esta práctica. Hacerlo le permite mezclar y combinar decoradores para llegar a complejas salidas -- y también anular aspectos de decoración para personalizar sus necesidades.

Por ejemplo, si quiere simplemente desplegar que un error ha ocurrido cuando validábamos un elemento, pero no desplegar individualmente cada uno de los mensajes de error, usted podría crear su propio decorador 'Errores':

class My_Decorator_Errors
{
    public function render($content = '')
    {
        $output = '<div class="errors">El valor que proporcionó no es válido;
            please try again</div>';

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

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

En este ejemplo particular, debido al segmento del decorador final, 'Errors', se combina como Zend_Form_Decorator_Errors , será generado en lugar de el decorador -- significa que no necesitará cambiar ningún decorador para modificar la salida. Nombrando sus decoradores después de los decoradores existentes estándar, usted puede modificar decoradores sin necesitad de modificar sus elementos decoradores.

Desde que los decoradores pueden capturar distintos metadatos del elemento o formulario que ellos decoran, es a menudo útil generar un decorador individual. Afortunadamente, esta caracteristica es posible inicializando el método en cada tipo de clase form (forms, sub form, display group, element).

Para hacer eso, simplemente render[DecoratorName]() , cuando "[DecoratorName]" es el "nombre corto" de su decorador; opcionalmente, puede pasar en el contenido lo que usted quiera. Por ejemplo:

// genera el elemento decorador label:
echo $element->renderLabel();

// genera sólo el campo display group, con algún contenido:
echo $group->renderFieldset('fieldset content');

// genera sólo el formulario HTML, con algún contenido:
echo $form->renderHtmlTag('wrap this content');

Si el decorador no existe, una excepción es inicializada.

Esto puede ser útil particularmente cuando se genera un formulario con el decorador ViewScript; cada elemento puede usar sus decoradores adjuntos para generar contenido, pero con un control minucioso.