Understanding and Using Zend Form Decorators. Layering Decorators

Translations of this material:

into Russian: 6.3 Понимание и использование Zend Form Decorators. Слои декораторов. 0% translated in draft.
Submitted for translation by antdmi 20.02.2011

Text

If you were following closely in the previous section, you may have noticed that a decorator's render() method takes a single argument, $content. This is expected to be a string. render() will then take this string and decide to either replace it, append to it, or prepend it. This allows you to have a chain of decorators -- which allows you to create decorators that render only a subset of the element's metadata, and then layer these decorators to build the full markup for the element.

Let's look at how this works in practice.

For most form element types, the following decorators are used:

    • ViewHelper (render the form input using one of the standard form view helpers).

    • Errors (render validation errors via an unordered list).

    • Description (render any description attached to the element; often used for tooltips).

    • HtmlTag (wrap all of the above in a <dd> tag.

    • Label (render the label preceding the above, wrapped in a <dt> tag.

You'll notice that each of these decorators does just one thing, and operates on one specific piece of metadata stored in the form element: the Errors decorator pulls validation errors and renders them; the Label decorator pulls just the label and renders it. This allows the individual decorators to be very succinct, repeatable, and, more importantly, testable.

It's also where that $content argument comes into play: each decorator's render() method is designed to accept content, and then either replace it (usually by wrapping it), prepend to it, or append to it.

So, it's best to think of the process of decoration as one of building an onion from the inside out.

To simplify the process, we'll take a look at the example from the previous section. Recall:

  01. class My_Decorator_SimpleInput extends Zend_Form_Decorator_Abstract

  02. {

  03.     protected $_format = '<label for="%s">%s</label>'

  04.                      . '<input id="%s" name="%s" type="text" value="%s"/>';

  05. 

  06.     public function render($content)

  07.     {

  08.         $element = $this->getElement();

  09.         $name    = htmlentities($element->getFullyQualifiedName());

  10.         $label = htmlentities($element->getLabel());

  11.         $id     = htmlentities($element->getId());

  12.         $value = htmlentities($element->getValue());

  13. 

  14.         $markup = sprintf($this->_format, $id, $label, $id, $name, $value);

  15.         return $markup;

  16.     }

  17. }

Let's now remove the label functionality, and build a separate decorator for that.

  01. class My_Decorator_SimpleInput extends Zend_Form_Decorator_Abstract

  02. {

  03.     protected $_format = '<input id="%s" name="%s" type="text" value="%s"/>';

  04. 

  05.     public function render($content)

  06.     {

  07.         $element = $this->getElement();

  08.         $name    = htmlentities($element->getFullyQualifiedName());

  09.         $id     = htmlentities($element->getId());

  10.         $value = htmlentities($element->getValue());

  11. 

  12.         $markup = sprintf($this->_format, $id, $name, $value);

  13.         return $markup;

  14.     }

  15. }

  16. 

  17. class My_Decorator_SimpleLabel extends Zend_Form_Decorator_Abstract

  18. {

  19.     protected $_format = '<label for="%s">%s</label>';

  20. 

  21.     public function render($content)

  22.     {

  23.         $element = $this->getElement();

  24.         $id     = htmlentities($element->getId());

  25.         $label = htmlentities($element->getLabel());

  26. 

  27.         $markup = sprintf($this->_format, $id, $label);

  28.         return $markup;

  29.     }

  30. }

Now, this may look all well and good, but here's the problem: as written currently, the last decorator to run wins, and overwrites everything. You'll end up with just the input, or just the label, depending on which you register last.

To overcome this, simply concatenate the passed in $content with the markup somehow:

  01. return $content . $markup;

The problem with the above approach comes when you want to programmatically choose whether the original content should precede or append the new markup. Fortunately, there's a standard mechanism for this already; Zend_Form_Decorator_Abstract has a concept of placement and defines some constants for matching it. Additionally, it allows specifying a separator to place between the two. Let's make use of those:

  01. class My_Decorator_SimpleInput extends Zend_Form_Decorator_Abstract

  02. {

  03.     protected $_format = '<input id="%s" name="%s" type="text" value="%s"/>';

  04. 

  05.     public function render($content)

  06.     {

  07.         $element = $this->getElement();

  08.         $name    = htmlentities($element->getFullyQualifiedName());

  09.         $id     = htmlentities($element->getId());

  10.         $value = htmlentities($element->getValue());

  11. 

  12.         $markup = sprintf($this->_format, $id, $name, $value);

  13. 

  14.         $placement = $this->getPlacement();

  15.         $separator = $this->getSeparator();

  16.         switch ($placement) {

  17.             case self::PREPEND:

  18.                 return $markup . $separator . $content;

  19.             case self::APPEND:

  20.             default:

  21.                 return $content . $separator . $markup;

  22.         }

  23.     }

  24. }

  25. 

  26. class My_Decorator_SimpleLabel extends Zend_Form_Decorator_Abstract

  27. {

  28.     protected $_format = '<label for="%s">%s</label>';

  29. 

  30.     public function render($content)

  31.     {

  32.         $element = $this->getElement();

  33.         $id     = htmlentities($element->getId());

  34.         $label = htmlentities($element->getLabel());

  35. 

  36.         $markup = sprint($this->_format, $id, $label);

Pages: ← previous Ctrl next
1 2