<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="learning.form.decorators.composite">
    <title>Creating and Rendering Composite Elements</title>

    <para>
        In <link linkend="learning.form.decorators.individual">the last section</link>, we had an
        example showing a "date of birth element":
    </para>

    <programlisting language="php"><![CDATA[
<div class="element">
    <?php echo $form->dateOfBirth->renderLabel() ?>
    <?php echo $this->formText('dateOfBirth[day]', '', array(
        'size' => 2, 'maxlength' => 2)) ?>
    /
    <?php echo $this->formText('dateOfBirth[month]', '', array(
        'size' => 2, 'maxlength' => 2)) ?>
    /
    <?php echo $this->formText('dateOfBirth[year]', '', array(
        'size' => 4, 'maxlength' => 4)) ?>
</div>
]]></programlisting>

    <para>
        How might you represent this element as a <classname>Zend_Form_Element</classname>?
        How might you write a decorator to render it?
    </para>

    <sect2 id="learning.form.decorators.composite.element">
        <title>The Element</title>

        <para>
            The questions about how the element would work include:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    How would you set and retrieve the value?
                </para>
            </listitem>

            <listitem>
                <para>
                    How would you validate the value?
                </para>
            </listitem>

            <listitem>
                <para>
                    Regardless, how would you then allow for discrete form inputs for the three
                    segments (day, month, year)?
                </para>
            </listitem>
        </itemizedlist>

        <para>
            The first two questions center around the form element itself: how would
            <methodname>setValue()</methodname> and <methodname>getValue()</methodname> work?
            There's actually another question implied by the question about the decorator: how would
            you retrieve the discrete date segments from the element and/or set them?
        </para>

        <para>
            The solution is to override the <methodname>setValue()</methodname> method of your
            element to provide some custom logic. In this particular case, our element should have
            three discrete behaviors:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    If an integer timestamp is provided, it should be used to determine and store
                    the day, month, and year.
                </para>
            </listitem>

            <listitem>
                <para>
                    If a textual string is provided, it should be cast to a timestamp, and then that
                    value used to determine and store the day, month, and year.
                </para>
            </listitem>

            <listitem>
                <para>
                    If an array containing keys for date, month, and year is provided, those values
                    should be stored.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Internally, the day, month, and year will be stored discretely. When the value of the
            element is retrieved, it will be done so in a normalized string format. We'll override
            <methodname>getValue()</methodname> as well to assemble the discrete date segments into
            a final string.
        </para>

        <para>
            Here's what the class would look like:
        </para>

        <programlisting language="php"><![CDATA[
class My_Form_Element_Date extends Zend_Form_Element_Xhtml
{
    protected $_dateFormat = '%year%-%month%-%day%';
    protected $_day;
    protected $_month;
    protected $_year;

    public function setDay($value)
    {
        $this->_day = (int) $value;
        return $this;
    }

    public function getDay()
    {
        return $this->_day;
    }

    public function setMonth($value)
    {
        $this->_month = (int) $value;
        return $this;
    }

    public function getMonth()
    {
        return $this->_month;
    }

    public function setYear($value)
    {
        $this->_year = (int) $value;
        return $this;
    }

    public function getYear()
    {
        return $this->_year;
    }

    public function setValue($value)
    {
        if (is_int($value)) {
            $this->setDay(date('d', $value))
                 ->setMonth(date('m', $value))
                 ->setYear(date('Y', $value));
        } elseif (is_string($value)) {
            $date = strtotime($value);
            $this->setDay(date('d', $date))
                 ->setMonth(date('m', $date))
                 ->setYear(date('Y', $date));
        } elseif (is_array($value)
                  && (isset($value['day'])
                      && isset($value['month'])
                      && isset($value['year'])
                  )
        ) {
            $this->setDay($value['day'])
                 ->setMonth($value['month'])
                 ->setYear($value['year']);
        } else {
            throw new Exception('Invalid date value provided');
        }

        return $this;
    }

    public function getValue()
    {
        return str_replace(
            array('%year%', '%month%', '%day%'),
            array($this->getYear(), $this->getMonth(), $this->getDay()),
            $this->_dateFormat
        );
    }
}
]]></programlisting>

        <para>
            This class gives some nice flexibility -- we can set default values from our database,
            and be certain that the value will be stored and represented correctly. Additionally,
            we can allow for the value to be set from an array passed via form input. Finally, we
            have discrete accessors for each date segment, which we can now use in a decorator to
            create a composite element.
        </para>
    </sect2>

    <sect2 id="learning.form.decorators.composite.decorator">
        <title>The Decorator</title>

        <para>
            Revisiting the example from the last section, let's assume that we want users to input
            each of the year, month, and day separately. <acronym>PHP</acronym> fortunately allows
            us to use array notation when creating elements, so it's still possible to capture these
            three entities into a single value -- and we've now created a
            <classname>Zend_Form</classname> element that can handle such an array value.
        </para>

        <para>
            The decorator is relatively simple: it will grab the day, month, and year from the
            element, and pass each to a discrete view helper to render individual form inputs; these
            will then be aggregated to form the final markup.
        </para>

        <programlisting language="php"><![CDATA[
class My_Form_Decorator_Date extends Zend_Form_Decorator_Abstract
{
    public function render($content)
    {
        $element = $this->getElement();
        if (!$element instanceof My_Form_Element_Date) {
            // only want to render Date elements
            return $content;
        }

        $view = $element->getView();
        if (!$view instanceof Zend_View_Interface) {
            // using view helpers, so do nothing if no view present
            return $content;
        }

        $day   = $element->getDay();
        $month = $element->getMonth();
        $year  = $element->getYear();
        $name  = $element->getFullyQualifiedName();

        $params = array(
            'size'      => 2,
            'maxlength' => 2,
        );
        $yearParams = array(
            'size'      => 4,
            'maxlength' => 4,
        );

        $markup = $view->formText($name . '[day]', $day, $params)
                . ' / ' . $view->formText($name . '[month]', $month, $params)
                . ' / ' . $view->formText($name . '[year]', $year, $yearParams);

        switch ($this->getPlacement()) {
            case self::PREPEND:
                return $markup . $this->getSeparator() . $content;
            case self::APPEND:
            default:
                return $content . $this->getSeparator() . $markup;
        }
    }
}
]]></programlisting>

    <para>
        We now have to do a minor tweak to our form element, and tell it that we want to use the
        above decorator as a default. That takes two steps. First, we need to inform the element of
        the decorator path. We can do that in the constructor:
    </para>

    <programlisting language="php"><![CDATA[
class My_Form_Element_Date extends Zend_Form_Element_Xhtml
{
    // ...

    public function __construct($spec, $options = null)
    {
        $this->addPrefixPath(
            'My_Form_Decorator',
            'My/Form/Decorator',
            'decorator'
        );
        parent::__construct($spec, $options);
    }

    // ...
}
]]></programlisting>

    <para>
        Note that this is being done in the constructor and not in <methodname>init()</methodname>.
        This is for two reasons. First, it allows extending the element later to add logic in
        <methodname>init</methodname> without needing to worry about calling
        <methodname>parent::init()</methodname>. Second, it allows passing additional plugin paths
        via configuration or within an <methodname>init</methodname> method that will then allow
        overriding the default <classname>Date</classname> decorator with my own replacement.
    </para>

    <para>
        Next, we need to override the <methodname>loadDefaultDecorators()</methodname> method to use
        our new <classname>Date</classname> decorator:
    </para>

    <programlisting language="php"><![CDATA[
class My_Form_Element_Date extends Zend_Form_Element_Xhtml
{
    // ...

    public function loadDefaultDecorators()
    {
        if ($this->loadDefaultDecoratorsIsDisabled()) {
            return;
        }

        $decorators = $this->getDecorators();
        if (empty($decorators)) {
            $this->addDecorator('Date')
                 ->addDecorator('Errors')
                 ->addDecorator('Description', array(
                     'tag'   => 'p',
                     'class' => 'description'
                 ))
                 ->addDecorator('HtmlTag', array(
                     'tag' => 'dd',
                     'id'  => $this->getName() . '-element'
                 ))
                 ->addDecorator('Label', array('tag' => 'dt'));
        }
    }

    // ...
}
]]></programlisting>

    <para>
        What does the final output look like? Let's consider the following element:
    </para>

    <programlisting language="php"><![CDATA[
$d = new My_Form_Element_Date('dateOfBirth');
$d->setLabel('Date of Birth: ')
  ->setView(new Zend_View());

// These are equivalent:
$d->setValue('20 April 2009');
$d->setValue(array('year' => '2009', 'month' => '04', 'day' => '20'));
]]></programlisting>

    <para>
        If you then echo this element, you get the following markup (with some slight whitespace
        modifications for readability):
    </para>

    <programlisting language="html"><![CDATA[
<dt id="dateOfBirth-label"><label for="dateOfBirth" class="optional">
    Date of Birth:
</label></dt>
<dd id="dateOfBirth-element">
    <input type="text" name="dateOfBirth[day]" id="dateOfBirth-day"
        value="20" size="2" maxlength="2"> /
    <input type="text" name="dateOfBirth[month]" id="dateOfBirth-month"
        value="4" size="2" maxlength="2"> /
    <input type="text" name="dateOfBirth[year]" id="dateOfBirth-year"
        value="2009" size="4" maxlength="4">
</dd>
]]></programlisting>
    </sect2>

    <sect2 id="learning.form.decorators.composite.conclusion">
        <title>Conclusion</title>

        <para>
            We now have an element that can render multiple related form input fields, and then
            handle the aggregated fields as a single entity -- the <varname>dateOfBirth</varname>
            element will be passed as an array to the element, and the element will then, as we
            noted earlier, create the appropriate date segments and return a value we can use for
            most backends.
        </para>

        <para>
            Additionally, we can use different decorators with the element. If we wanted to use a
            <ulink url="http://dojotoolkit.org/">Dojo</ulink> <classname>DateTextBox</classname>
            dijit decorator -- which accepts and returns string values -- we can, with no
            modifications to the element itself.
        </para>

        <para>
            In the end, you get a uniform element <acronym>API</acronym> you can use to describe an
            element representing a composite value.
        </para>
    </sect2>
</sect1>
