Turboflash’s Blog

In Part 1, we are able to split the content into parts and apply decorators on them separately. This can be achieved by using the following classes. I guess the render method of each class pretty much sums up what they do so I will not explain further.

<?php

/**
 * @see Zend_Form_Decorator_Abstract
 */
require_once 'Zend/Form/Decorator/Abstract.php';

/**
 * This class will store the content into this instance during rendering. You
 * can retrieve the stored content using the complementing class
 * App_Form_Decorator_Retrieve. When adding several instances of this decorator,
 * you will have to alias it. The alias given will be used as the name option of
 * the App_Form_Decorator_Retrieve decorator.
 *
 * Accepts the following option:
 * - clear: whether to clear the passed in content by returning an empty content.
 *
 * Add the following line to the init() function of the Zend_Form-extended class
 * and use 'Store' to instantiate this decorator class.
 *
 * $this->addPrefixPath('App_Form_Decorator', 'App/Form/Decorator', Zend_Form::DECORATOR);
 *
 * @category   App
 * @package    App_Form_Decorator
 */
class App_Form_Decorator_Store extends Zend_Form_Decorator_Abstract
{
    /**
     * @access protected
     * @var boolean
     */
    protected $_clear = null;
    /**
     * @access protected
     * @var string
     */
    protected $_content = null;

    /**
     * Specifies whether to clear the passed in content after it is stored in
     * this instance.
     *
     * @param  boolean  $clear  True if to clear the passed in content.
     * @return  App_Form_Decorator_Store  For method chaining.
     * @throws  App_Form_Decorator_Exception  If parameter is not valid.
     */
    public function setClear($clear)
    {
        if (!is_bool($clear))
        {
            require_once 'App/Form/Decorator/Exception.php';
            throw new App_Form_Decorator_Exception('Clear option is not defined');
        }

        $this->_clear = $clear;

        return $this;
    }

    /**
     * Returns whether to clear the passed in content after it is stored in
     * this instance.
     *
     * @return  boolean  True if to clear the passed in content.
     * @throws  App_Form_Decorator_Exception  If 'clear' option is not valid.
     */
    public function getClear()
    {
        if (is_null($this->_clear))
        {
            if (!is_null($clear = $this->getOption('clear')))
            {
                $this->setClear($clear);
                $this->removeOption('clear');
            }
            else
                $this->setClear(true);
        }

        return $this->_clear;
    }

    /**
     * Clears content stored in this instance.
     *
     * @return  App_Form_Decorator_Store  For method chaining.
     */
    public function clearContent()
    {
        $this->_content = null;

        return $this;
    }

    /**
     * Returns content stored in this instance.
     *
     * @param  boolean  $clear  True if to clear stored content in this instance.
     * @return  string  Stored content.
     */
    public function getContent($clear = false)
    {
        $content = $this->_content;

        if (is_null($content))
            $content = '';
        elseif ($clear)
            $this->clearContent();

        return $content;
    }

    /**
     * Store the passed in content for retrieval.
     *
     * @param  string  $content  Passed in content to store.
     * @return  string  Depending on the clear option, it is either empty content or as is.
     */
    public function render($content)
    {
        // Store the passed in content to this instance.
        $this->_content = $content;

        // Clear or return content.
        return ($this->getClear()) ? '' : $content;
    }
}

<?php

/**
 * @see Zend_Form_Decorator_Abstract
 */
require_once 'Zend/Form/Decorator/Abstract.php';

/**
 * This class will retrieve the stored content from complementing class
 * App_Form_Decorator_Store. When adding several instances of this decorator,
 * you will have to alias it. The alias is purely used to ensure the instances
 * will not overwrite each other. To retrieve the stored content, you will need
 * to pass the alias used in instantiating the App_Form_Decorator_Store
 * decorator to the 'name' option.
 *
 * Accepts the following options:
 * - name: The alias used when creating the App_Form_Decorator_Store instance.
 * - remove: Boolean value determining whether to remove the stored content
 *           after retrieval.
 * - separator: string with which to separate passed in content and retrieved
 *              content.
 * - placement: whether to append, prepend or replace with the retrieved
 *              content.
 *
 * Add the following line to the init() function of the Zend_Form-extended class
 * and use 'Retrieve' to instantiate this decorator class.
 *
 * $this->addPrefixPath('App_Form_Decorator', 'App/Form/Decorator', Zend_Form::DECORATOR);
 *
 * @category   App
 * @package    App_Form_Decorator
 */
class App_Form_Decorator_Retrieve extends Zend_Form_Decorator_Abstract
{
    /**
     * @access protected
     * @var string
     */
    protected $_name = null;
    /**
     * @access protected
     * @var boolean
     */
    protected $_remove = null;

    /**
     * Returns stored content from the App_Form_Decorator_Store instance.
     *
     * @param  boolean  $clear  True if to clear stored content after retrieval.
     * @return  string  Stored content.
     * @throws  App_Form_Decorator_Exception  If wrong decorator instance is retrieved.
     */
    protected function _getContent($clear)
    {
        $store = $this->getElement()->getDecorator($this->getName());

        if (!$store instanceof App_Form_Decorator_Store)
        {
            require_once 'App/Form/Decorator/Exception.php';
            throw new App_Form_Decorator_Exception('"' . $this->getName() . '" is not a App_Form_Decorator_Store decorator');
        }

        return $store->getContent($clear);
    }

    /**
     * Specifies the name/alias of the element decorator to retrieve.
     *
     * @param  string  $name  Name/alias of the element decorator to retrieve.
     * @return  App_Form_Decorator_Retrieve  For method chaining.
     * @throws  App_Form_Decorator_Exception  If parameter is not valid.
     */
    public function setName($name)
    {
        if (!is_string($name))
        {
            require_once 'App/Form/Decorator/Exception.php';
            throw new App_Form_Decorator_Exception('Element decorator name is not defined');
        }

        if (is_numeric($name))
        {
            require_once 'App/Form/Decorator/Exception.php';
            throw new App_Form_Decorator_Exception('Element decorator name must be alphanumeric');
        }

        $this->_name = $name;

        return $this;
    }

    /**
     * Returns name/alias of the element decorator to retrieve.
     *
     * @return  string  Name/alias of the element decorator to retrieve.
     * @throws  App_Form_Decorator_Exception  If 'name' option is not valid.
     */
    public function getName()
    {
        if (is_null($this->_name))
        {
            if (is_null($name = $this->getOption('name')))
            {
                require_once 'App/Form/Decorator/Exception.php';
                throw new App_Form_Decorator_Exception('Element decorator name is not defined in the options');
            }

            $this->setName($name);
            $this->removeOption('name');
        }

        return $this->_name;
    }

    /**
     * Specifies whether to remove the stored content in
     * App_Form_Decorator_Store instance after retrieval.
     *
     * @param  boolean  $remove  True if remove the stored content after retrieval.
     * @return  App_Form_Decorator_Store  For method chaining.
     * @throws  App_Form_Decorator_Exception  If parameter is not valid.
     */
    public function setRemove($remove)
    {
        if (!is_bool($remove))
        {
            require_once 'App/Form/Decorator/Exception.php';
            throw new App_Form_Decorator_Exception('Remove option is not defined');
        }

        $this->_remove = $remove;

        return $this;
    }

    /**
     * Returns whether to remove the stored content in
     * App_Form_Decorator_Store instance after retrieval.
     *
     * @return  boolean  True if remove the stored content after retrieval.
     * @throws  App_Form_Decorator_Exception  If 'remove' option is not valid.
     */
    public function getRemove()
    {
        if (is_null($this->_remove))
        {
            if (!is_null($remove = $this->getOption('remove')))
            {
                $this->setRemove($remove);
                $this->removeOption('remove');
            }
            else
                $this->setRemove(true);
        }

        return $this->_remove;
    }

    /**
     * Retrieves the stored content.
     *
     * @param  string  $content  Passed in content.
     * @return  string  Rendered content.
     */
    public function render($content)
    {
        switch ($this->getPlacement())
        {
            case self::APPEND:
                return $content . $this->getSeparator() . $this->_getContent($this->getRemove());

            case self::PREPEND:
                return $this->_getContent($this->getRemove()) . $this->getSeparator() . $content;

            default:
                return $this->_getContent($this->getRemove());
        }
    }
}

And finally, the App_Form_Decorator_Exception class for completeness.

<?php

/**
 * @see Zend_Exception
 */
require_once 'Zend/Exception.php';

/**
 * @category   App
 * @package    App_Form_Decorator
 */
class App_Form_Decorator_Exception extends Zend_Exception
{
}

To use them, you just need to put these three classes into a folder App/Form/Decorator. You need to add this folder to the include_path similar to what you did for Zend library. Remember to enable autoloading using the Zend_Loader class. Other information can be found in the class remarks.

If there is any optimization or bug, please feel free to point them out so that I can update my copy as well.

Oh… One more thing, you can also used the same concept to create decorator that does formatting, such as indentation, of the rendered content if you haven’t thought of that.

During form rendering, the decorators are executed in the order added and rendering are done on the same content throughout. If you were to open up Zend/Form.php, you will find inside an elegant render method as follows that summarizes what I’ve mentioned earlier.

public function render(Zend_View_Interface $view = null)
{
    if (null !== $view) {
        $this->setView($view);
    }

    $content = '';
    foreach ($this->getDecorators() as $decorator) {
        $decorator->setElement($this);
        $content = $decorator->render($content);
    }
    return $content;
}

Here comes the issue. We cannot apply decorators selectively to a part of the content by breaking it up. You can only prepend, append or wrap the whole, not portion of, content with a new decorator. This poses a challenge if you need to create custom tags around both Label and Text Field in a Zend_Form_Element_Text for example.

If you, like me, have been doing lots of research on Zend Form Decorators and is hitting the wall, I guess the following might be a solution that will give flexibility to the way decorators can be used. I hope this will help someone in a way or another.

Before I start presenting the possible solution, let me go through what we want to achieve, what we can achieve using the closest available method on the Internet and my proposed solution that introduces flexibility to what we want to achieve.

What we want to achieve

As an example, here’s what we want to achieve, a class attribute of value label for the first td tag on line 2. This will allow us to style it with CSS class label.

<tr>
    <td class="label">
        <label for="username" class="optional">Username:</label>
    </td>
    <td class="element">
        <input type="text" name="username" id="username" value="" />
    </td>
</tr>

What we can achieve using the closest available method

Here are the decorators applied to Zend_Form_Element_Text instance. On line 5, we have added an option ‘class’ => ‘label’ to the Label decorator.

$element->setDecorators(array(
    'ViewHelper',
    'Errors',
    array(array('data' => 'HtmlTag'), array('tag' => 'td', 'class' => 'element')),
    array('Label', array('tag' => 'td', 'class' => 'label')),
    array(array('row' => 'HtmlTag'), array('tag' => 'tr')),
));

The following is achieved using the above code. As you can see, class label is applied to label tag on line 3, and not td tag on line 2. This is not what we want.

<tr>
    <td>
        <label for="username" class="label optional">Username:</label>
    </td>
    <td class="element">
        <input type="text" name="username" id="username" value="" />
    </td>
</tr>

Proposed solution

We will create two new decorator class: Store and Retrieve. It will be used as follows.

$username->setDecorators(array(
    // Create element and store it.
    'ViewHelper',
    'Errors',
    array(array('td-element' => 'HtmlTag'), array('tag' => 'td', 'class' => 'element')),
    array(array('store-element' => 'Store'), array('clear' => true)),
    
    // Create label and store it.
    'Label',
    array(array('td-label' => 'HtmlTag'), array('tag' => 'td', 'class' => 'label')),
    array(array('store-label' => 'Store'), array('clear' => true)),
    
    // Retrieve both the label and element.
    array(array('retrieve-label' => 'Retrieve'), array('name' => 'store-label', 'remove' => true)),
    array(array('retrieve-element' => 'Retrieve'), array('name' => 'store-element', 'remove' => true)),
    
    // Wrap the retrieved label and element with tr tag.
    array(array('row' => 'HtmlTag'), array('tag' => 'tr')),
));

The following is achieved using the above code as what we have set out initially. We are now able to work on part of the content at a time.

<tr>
    <td class="label">
        <label for="username" class="optional">Username:</label>
    </td>
    <td class="element">
        <input type="text" name="username" id="username" value="" />
    </td>
</tr>

In Part 2, we will present the two newly derived decorator class.

Excellent References:
http://framework.zend.com/manual/en/zend.form.standardDecorators.html
http://devzone.zend.com/article/3450-Decorators-with-Zend_Form
http://zendguru.wordpress.com/2008/10/23/zend-form-decorators/