<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.dojo.form.decorators">
    <title>Dijit-Specific Form Decorators</title>

    <para>
        Most form elements can use the DijitElement decorator, which will grab
        the dijit parameters from the elements, and pass these and other
        metadata to the view helper specified by the element. For decorating
        forms, sub forms, and display groups, however, there are a set of
        decorators corresponding to the various layout dijits.
    </para>

    <para>
        All dijit decorators look for the <property>dijitParams</property> property of
        the given element being decorated, and push them as the
        <varname>$params</varname> array to the dijit view helper being used; these
        are then separated from any other properties so that no duplication of
        information occurs.
    </para>

    <sect3 id="zend.dojo.form.decorators.dijitElement">
        <title>DijitElement Decorator</title>

        <para>
            Just like <link linkend="zend.form.standardDecorators.viewHelper">the
                ViewHelper decorator</link>, DijitElement expects a
            <property>helper</property> property in the element which it will then use
            as the view helper when rendering. Dijit parameters will typically
            be pulled directly from the element, but may also be passed in as
            options via the <property>dijitParams</property> key (the value of that key
            should be an associative array of options).
        </para>

        <para>
            It is important that each element have a unique ID (as fetched from
            the element's <methodname>getId()</methodname> method). If duplicates are
            detected within the <methodname>dojo()</methodname> view helper, the decorator
            will trigger a notice, but then create a unique ID by appending the
            return of <methodname>uniqid()</methodname> to the identifier.
        </para>

        <para>
            Standard usage is to simply associate this decorator as the first
            in your decorator chain, with no additional options.
        </para>

        <example id="zend.dojo.form.decorators.dijitElement.usage">
            <title>DijitElement Decorator Usage</title>

            <programlisting language="php"><![CDATA[
$element->setDecorators(array(
    'DijitElement',
    'Errors',
    'Label',
    'ContentPane',
));
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.decorators.dijitForm">
        <title>DijitForm Decorator</title>

        <para>
            The DijitForm decorator is very similar to the <link
                linkend="zend.form.standardDecorators.form">Form
                decorator</link>; in fact, it can be used basically
            interchangeably with it, as it utilizes the same view helper name
            ('form').
        </para>

        <para>
            Since <command>dijit.form.Form</command> does not require any dijit parameters for
            configuration, the main difference is that the dijit form view
            helper require that a <acronym>DOM</acronym> ID is passed to ensure that programmatic
            dijit creation can work. The decorator ensures this, by passing the
            form name as the identifier.
        </para>
    </sect3>

    <sect3 id="zend.dojo.form.decorators.dijitContainer">
        <title>DijitContainer-based Decorators</title>

        <para>
            The <classname>DijitContainer</classname> decorator is actually an abstract
            class from which a variety of other decorators derive. It offers
            the same functionality of <link
                linkend="zend.dojo.form.decorators.dijitElement">DijitElement</link>,
            with the addition of title support. Many layout dijits require or
            can utilize a title; DijitContainer will utilize the element's
            legend property, if available, and can also utilize either the
            'legend' or 'title' decorator option, if passed. The title will be
            translated if a translation adapter with a corresponding
            translation is present.
        </para>

        <para>
            The following is a list of decorators that inherit from
            <classname>DijitContainer</classname>:
        </para>

        <itemizedlist>
            <listitem><para>AccordionContainer</para></listitem>
            <listitem><para>AccordionPane</para></listitem>
            <listitem><para>BorderContainer</para></listitem>
            <listitem><para>ContentPane</para></listitem>
            <listitem><para>SplitContainer</para></listitem>
            <listitem><para>StackContainer</para></listitem>
            <listitem><para>TabContainer</para></listitem>
        </itemizedlist>

        <example id="zend.dojo.form.decorators.dijitContainer.usage">
            <title>DijitContainer Decorator Usage</title>

            <programlisting language="php"><![CDATA[
// Use a TabContainer for your form:
$form->setDecorators(array(
    'FormElements',
    array('TabContainer', array(
        'id'          => 'tabContainer',
        'style'       => 'width: 600px; height: 500px;',
        'dijitParams' => array(
            'tabPosition' => 'top'
        ),
    )),
    'DijitForm',
));

// Use a ContentPane in your sub form (which can be used with all but
// AccordionContainer):
$subForm->setDecorators(array(
    'FormElements',
    array('HtmlTag', array('tag' => 'dl')),
    'ContentPane',
));
]]></programlisting>
        </example>
    </sect3>
</sect2>
