repo_zf1/documentation/manual/en/module_specs/Zend_Dojo-Form.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.dojo.form" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Dojo Form Elements and Decorators</title>

    <para>
        Building on the <link linkend="zend.dojo.view.dijit">dijit view
        helpers</link>, the <classname>Zend_Dojo_Form</classname> family of classes
        provides the ability to utilize Dijits natively within your forms.
    </para>

    <para>
        There are three options for utilizing the Dojo form elements with your
        forms:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                Use <methodname>Zend_Dojo::enableForm()</methodname>. This will add plugin
                paths for decorators and elements to all attached form items,
                recursively. Additionally, it will dojo-enable the view object.
                Note, however, that any sub forms you attach
                <emphasis>after</emphasis> this call will also need to be
                passed through <methodname>Zend_Dojo::enableForm()</methodname>.
            </para>
        </listitem>

        <listitem>
            <para>
                Use the Dojo-specific form and subform implementations,
                <classname>Zend_Dojo_Form</classname> and
                <classname>Zend_Dojo_Form_SubForm</classname> respectively. These can be
                used as drop-in replacements for <classname>Zend_Form</classname> and
                <classname>Zend_Form_SubForm</classname>, contain all the appropriate
                decorator and element paths, set a Dojo-specific default
                DisplayGroup class, and dojo-enable the view.
            </para>
        </listitem>

        <listitem>
            <para>
                Last, and most tedious, you can set the appropriate decorator
                and element paths yourself, set the default DisplayGroup class,
                and dojo-enable the view. Since
                <methodname>Zend_Dojo::enableForm()</methodname> does this already, there's
                little reason to go this route.
            </para>
        </listitem>
    </itemizedlist>

    <example id="zend.dojo.form.enable">
        <title>Enabling Dojo in your existing forms</title>

        <para>
            "But wait," you say; "I'm already extending <classname>Zend_Form</classname> with my own
            custom form class! How can I Dojo-enable it?'"
        </para>

        <para>
            First, and easiest, simply change from extending
            <classname>Zend_Form</classname> to extending <classname>Zend_Dojo_Form</classname>,
            and update any places where you instantiate
            <classname>Zend_Form_SubForm</classname> to instantiate
            <classname>Zend_Dojo_Form_SubForm</classname>.
        </para>

        <para>
            A second approach is to call <methodname>Zend_Dojo::enableForm()</methodname>
            within your custom form's <methodname>init()</methodname> method; when the form
            definition is complete, loop through all SubForms to dojo-enable
            them:
        </para>

        <programlisting language="php"><![CDATA[
class My_Form_Custom extends Zend_Form
{
    public function init()
    {
        // Dojo-enable the form:
        Zend_Dojo::enableForm($this);

        // ... continue form definition from here

        // Dojo-enable all sub forms:
        foreach ($this->getSubForms() as $subForm) {
            Zend_Dojo::enableForm($subForm);
        }
    }
}
]]></programlisting>
    </example>

    <para>
        Usage of the dijit-specific form decorators and elements is just like
        using any other form decorator or element.
    </para>

    <xi:include href="Zend_Dojo-Form-Decorators.xml" />
    <xi:include href="Zend_Dojo-Form-Elements.xml" />
    <xi:include href="Zend_Dojo-Form-Examples.xml" />
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->