Decorators with Zend_Form

Zend_Form
has been lauded by many as a welcome addition to Zend Framework, and a
flexible solution to the problem of forms. That said, one point of
flexibility it offers has proved to be a pain point for many developers:
decorators. This tutorial aims to shed some light on decorators, as well as
provide strategies for creating your own decorators and combining them in
creative ways to customize the output your forms generate.

Background

When designing Zend_Form, a primary goal was that it should
generate the markup necessary to display each element and the form itself.
The rationale was that injecting values and metadata into the element markup
and reporting errors is often a tedious, repetitive task. Any form solution
needed to address this and make these actions trivial.

Of course, the problem with generating form markup is that there is no
standard way to do it. The approaches vary greatly from developer to
developer and project to project. So, any solution for this had to be
flexible enough to accomodate a variety of approaches.

Another objective was that Zend_Form not be tied to Zend_View.
While it’s true that the default decorators actually do utilize
Zend_View, the solution needed to be flexible enough that
should a developer choose not to utilize Zend_View, they could.

With all these goals in mind, the solution finally presented itself: use the
principles of the Decorator
Pattern
. A decorator traditionally is used as a way to extend the
functionality of a class by wrapping it. This allows the developer the
ability to add or modify existing behavior while making calls to the same
API. Decorators may wrap other decorators, allowing for a layered approach
to extension. The decorator itselfis used in place of the original object,
as it follows the same API; it simply provides new or additional
functionality to the original.

As an example, consider a Window class. You might then create a
WindowDecorator that displays the window, and additional decorators for
showing the scrollbars, window title, etc; each decorator is responsible for
a single aspect of the final display. Instantiation might look like this:

To render the final window:

This would execute the WindowScrollbarDecorator::render()
method, which would in turn call the
WindowTitleDecorator::render() method, which would then call
WindowDecorator::render(), which would finally either call on
the Window::render() method or simply use object state from it.
The final result is a window with a title and scrollbars.

Decorators present an ideal solution for Zend_Form, in that a
developer may want to selectively determine what to display in their final
output. The final solution settled on is a modified decorator; instead of
decorating the object, we decorate the content generated, but we do so using
metadata from the element or form object. Whereas a traditional decorator
operates from the outside in, Zend_Form‘s operates from the
inside out, layering content outward.

Basics of Operation

When decorating, you have the ability to either prepend, append, or replace
(which could include wrapping) the content passed in. The initial content is
an empty string, and then each decorator works on the content from the
previously executed decorator.

Let’s look at how the default decorators for most elements work. The default
decorators are ViewHelper, Errors,
HtmlTag, and finally Label. By default, the
ViewHelper decorator replaces any content provided; the Errors decorator
appends the content provided; the HtmlTag decorator wraps content provided
and the Label decorator prepends content provided. (In all cases except the
ViewHelper, the placement — to append, prepend, or wrap — is
configurable.) To visualize execution, the final execution call looks
something like this:

Step by step, let’s look at how the content is built:

As you can see, each decorator does one thing, and the final result is an
aggregation of the content produced by each decorator.

Customizing Output Using Standard Decorators

To get an idea of how to customize output, first you need to know the
baseline: what the standard, registered decorators are for each object type.
The standard decorators, in the order they are registered, for most elements
are:

  • ViewHelper
  • Errors
  • HtmlTag (<dd>)
  • Label (with wrapping <dt> tag)

For the form object, the standard decorators are:

  • FormElements (iterates through all elements, display groups, and sub
    forms, rendering each)
  • HtmlTag (<dl>)
  • Form

Display groups and sub forms share the following decorators by default:

  • FormElements
  • Fieldset
  • DtDdWrapper (wraps fieldset in a <dd>, and prepends with an empty
    <dt>)

One easy way to customize output is to either add or modify options on a
decorator. For instance, if you decide you want your label to
follow your element, instead of precede it, you could change the
placement option:

There are a variety of options available for most decorators; you will need
to read the manual and/or API documentation to get the full details.

Another easy way to customize output is to remove a decorator. If
you don’t want to display a label, for instance, remove that decorator:

Unfortunately, there are not currently methods for inserting decorators at
specific locations in the decorator stack, so if you find you need to insert
a new decorator in the middle of the stack, the best way is to simply reset
the stack. For example, if you wanted to add a Description following the
element (perhaps a paragraph detailing the purpose of the element), you
could do the following:

While addDecorator() and addDecorators() methods
exist, typically you will be using setDecorators() unless you
start out with very minimal decorators to begin with.

When adding a decorator, you have the option to alias it. What this
does is allow you to store the decorator using a different name — which
allows you to retrieve it from the stack by that name. This is primarily
useful when you need to add two or more of the same type of decorator; in
fact, in such a situation, if you do not alias, the last registered
decorator of that type will overwrite all other instances! You accomplish
aliasing by passing an array as the decorator type, with a single key/value
pair with the alias as the key, and the decorator type as the value. For
instance, if you needed to use two different HTML tags in your stack, you
could do something like the following:

In the above example, the element content is wrapped in an HTML div, which
is then in turn wrapped in a table data cel. The two are aliased as
‘elementDiv’ and ‘td’, respectively.

Standard Decorators

Now that we know how to manipulate the decorator stack and the individual
decorators, what standard decorators are available?

  • Callback: execute a specified PHP callback to return content
  • Description: render the item’s description property
  • DtDdWrapper: wrap content in a <dd> and prepend with an
    empty <dt>
  • Errors: render an unordered list of the item’s errors, if
    any
  • Fieldset: render the content provided in a fieldset, using the
    item’s legend property for a legend if available
  • FormElements: iterate through a form, sub form, or display group,
    rendering each item (which could be an element, display group, or sub
    form)
  • Form: wrap content in a <form> tag, using the form object’s
    metadata as attributes
  • HtmlTag: wrap content in an HTML tag, or prepend or append the
    content with a given tag (and optionally use either just the open or
    close tag)
  • Image: render a form image based on the current element
  • Label: render an element’s label (prepends by default)
  • ViewHelper: render an element by utilizing a view helper. the
    view helper used is pulled from the element’s ‘helper’ property, if
    available, but can also be specified explicitly by passing a ‘helper’
    option to the decorator. Replaces content by default.
  • ViewScript: render an element by rendering a specified view
    script. Replaces content by default.

Each of the above appends the content provided by default, unless otherwise
specified.

Example: Table Layout

One common request is to be able to render a form as an HTML table. How can
this be accomplished?

For purposes of this example, we will assume that there should be one row
per element. Standard elements will use two columns per row, one for the
label and one for the element and any reported errors; buttons will be
displayed in the second column with no label.

For standard elements, you would set decorators like the following:

For button and image elements, we’d use the following:

The form itself would look like this:

The following output might then be generated:

Note: this does not accomodate for display groups and sub forms;
hopefully, it gives enough of an idea that you can figure out how to do so.

“That’s nice,” you say, “but I don’t really want to have to set those
decorators for each and every form element.” Well, you don’t have to, as
there are a variety of methods to accomodate this.

First, there’s the setElementDecorators() method of the form
object. This method will set all decorators for all currently
registered form elements (not elements registered after calling
it):

You could do this once, and then loop through the form, looking for submit,
reset, button, and image elements to set their decorators.

Another easy option is subclassing the form object, and defining these as
arrays which are passed to the elements:

The above method is especially nice as it prevents the default decorators
loading by providing decorators at instantiation time. It also has the
advantage that you can modify your decorators in a single place. Should you
choose to make the properties elementDecorators or
buttonDecorators static, you could even inject the default
decorators you want for the form prior to instantiating it, allowing for
re-use with different decorator stacks.

Finally, you could also create your own element subclasses that override the
loadDefaultDecorators() methods — allowing you to have
different elements based on the type of output you plan to generate.

Example: Full Customization Using the ViewScript Decorator

What if you want to have arbitrary content mixed in with your form elements,
or you have a complex markup you want to use? Decorators may be fine for the
individual form elements, but for the form as a whole, they make little
sense. Enter the ViewScript decorator.

The ViewScript decorator will render a given view script as a partial,
passing the form as the $form view variable. This allows you to
pull out the metadata and/or elements you need and render them directly.
When using one with a form object, it will also typically obviate the need
for Display Groups, as you can do those manually.

As an example, consider the following view script:

If the above form was in the view script “demogForm.phtml”, you could then
attach it to your form as follows:

As you can see, this method of rendering a form can be more verbose, but it
also allows you to tweak the form almost infinitely while still gaining the
advantages of error reporting, labeling, etc that decorators provide (by
using the decorators associated with the elements).

Creating a Custom Decorator

Make no mistake about it: there will come a time when the standard
decorators simply will not do the job. You may have markup that’s too
complex to generate with a chain of decorators, you may want to cut down
function calls to optimize your application, you may want to combine
multiple discrete HTML elements as a single Zend_Form element, etc. At this
time, you should start investigating custom decorators.

Anatomy of a Decorator

All decorators in Zend_Form implement
Zend_Form_Decorator_Interface, which simply looks like this:

For your convenience, most of these methods are stubbed in
Zend_Form_Decorator_Abstract, meaning that all you need to do
with your decorators is provide a render() method:

A decorator stores an instance of the current object as the ‘element’.
However, the element is not restricted to Zend_Form_Element
objects, but can also be forms, display groups, or sub forms. As a result,
you can have decorators that target aspects of any of these object types and
their metadata. Retrieve the current ‘element’ using
getElement().

If your decorator should be view aware, you can attempt to pull the view
object from the element:

If the returned value is null, you do not have a view.

Two properties are also always set: the separator and placement. Your
render method should make use of these when returning content.
When extending Zend_Form_Decorator_Abstract, you can retrieve
these using getSeparator() and getPlacement(),
respectively; otherwise, check for them using getOption(), as
they are passed as options typically. As an example:

Now that you have the tools for creating decorators, let’s tell the form
and elements how to find them.

Telling Your Form or Element About Your Decorators

Creating custom decorators is great, but unless you tell your form or
elements where to find them, they’re worthless. You need to tell your
objects where to look for your decorators.

Forms

You can tell a form where to look for its decorators using
addPrefixPath():

The second argument, $path indicates a path to classes
containing the given prefix. If that path is on your
include_path, then you can use a relative path; if not, use a
fully-qualified path to ensure that the plugin loader can find the classes.

The third argument is the type of plugin path for which the path applies; in
this case, we’re only looking at decorators, so we use the string
‘decorator’; however, you can also use addPrefixPath() to set
plugin paths for other plugin types, such as elements, validators, and
filters.

You can also setup decorator paths for the various items Zend_Form
aggregates — display groups, sub forms, and elements. This can be done by
using the following methods:

  • addElementPrefixPath($path, $prefix, 'decorator')
  • addDisplayGroupPrefixPath($path, $prefix)

In each case, the setting will apply to any elements or display groups
currently attached to the form, as well as those created or attached later.
You may also pass an elementPrefixPath option during
configuration; the value will be used for any elements created with the
form. As examples:

Elements

To set a plugin path for an individual element, you can call
addPrefixPath($prefix, $path, 'decorator') on your element
itself, or pass values via the prefixPath configuration key.
This would be primarily useful if you know that only a single or subset of
elements is using custom decorator plugins, or if you need some elements to
use standard decorators and others to use overridden decorators.

The use cases are almost exactly like with Zend_Form:

Example: Grouped Checkboxes

Now that you know how decorators work, how to write your own, and how to
tell your objects where to find them, let’s try it all out.

For our use case, we want to create a group of checkboxes referring to tags.
The checkboxes will be in an array structure two levels deep, with the first
level referring to a category, and the second being the checkbox value/label
pairs. We want to group each category of tags grouped in a fieldset with the
category name as the legend, and listed with the label trailing each
checkbox.

One other thing we want to do is ensure that the labels for each checkbox
are translated.

We’ll call our decorator something descriptive, like ‘CategorizedCheckbox’,
because we’re developers, and we’ll use our own creatively named class
prefix of ‘My_Form_Decorator’.

To start off, we need a registered element if we want to do anything, and
that element should extend Zend_Form_Element_Multi; that way we
know that getValue() will return an array. Additionally, we’re
going to make use of Zend_View view helpers, so we need to
ensure that a view object is registered with the element. Finally, we’ll
grab our translation object for later use.

Now that we have that out of the way, let’s do some work. First, we’ll
initialize the new content we want to create. Then we’ll grab our current
values so we can test to see if a given checkbox is checked later. Also, we
need to get the base name of the element so we can use it with the
individual checkboxes, as well as create our checkbox IDs. Finally, we can
start iterating over our options:

Now we get to the fun part: generating the markup. Since fieldsets wrap
content, we’ll generate a list of checkboxes first, and then wrap them in
the fieldset. We can do this using view helpers. This is also where we will
translate our labels. Checkboxes need names and ids as well, so we’ll build
them here, just prior to passing them to our formCheckbox()
view helper. When all options are complete for a category, we’ll wrap them
in a fieldset, using the translated category as the legend.

Finally, we need to return the content. We’ll assume that if no placement is
specified, we want to replace the content, and otherwise honor the
placement.

And that’s it! We can now set this as a decorator on an element, and we’re
done!

Other Ways to Customize Decorators

Most decorators allow a variety of options; you will need to check
the documentation
to determine what options are available. Many of these
options will allow you to customize the output, so providing values or
modifying them is an easy way to customize your forms.

You have several methods available for setting options:

  • setOption($key, $value) allows you to set a single option
    at a time
  • setOptions(array $options) allows you to set several
    options at once; $options should be an array of key/value
    pairs.
  • Finally, you can also pass an array of options or a
    Zend_Config object when adding a decorator to the element
    or form:

View Helpers

Another way to modify your decorators, and specifically the ViewHelper
decorator, is to override your view helpers. Overriding view helpers with
your own custom view helpers is covered in a previous tutorial, and is a
viable option for customizing your forms as well.

In Conclusion

Decorators are simple classes that deliver complex functionality: generating
complex markup from your elements. Hopefully, with the information provided
in this tutorial, you can now see how to combine decorators and write custom
decorators to achieve custom markup to suit your site and application.

About Matthew Weier O'Phinney

Matthew is a Principal Engineer at Zend Technologies. He is currently project lead for both Zend Framework and Apigility; a Zend Certified Engineer; and a member of the Zend Education Advisory Board, the group responsible for authoring the Zend Certification Exam. He contributes to a number of open source projects, blogs on PHP-related topics, and presents talks and tutorials related to PHP development and the projects to which he contributes. You can read more of his thoughts on his blog, mwop.net/blog.