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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.dojo.form" xmlns:xi="http://www.w3.org/2001/XInclude">
   4     <title>Dojo Form Elements and Decorators</title>
   5
   6     <para>
   7         Building on the <link linkend="zend.dojo.view.dijit">dijit view
   8         helpers</link>, the <classname>Zend_Dojo_Form</classname> family of classes
   9         provides the ability to utilize Dijits natively within your forms.
  10     </para>
  11
  12     <para>
  13         There are three options for utilizing the Dojo form elements with your
  14         forms:
  15     </para>
  16
  17     <itemizedlist>
  18         <listitem>
  19             <para>
  20                 Use <methodname>Zend_Dojo::enableForm()</methodname>. This will add plugin
  21                 paths for decorators and elements to all attached form items,
  22                 recursively. Additionally, it will dojo-enable the view object.
  23                 Note, however, that any sub forms you attach
  24                 <emphasis>after</emphasis> this call will also need to be
  25                 passed through <methodname>Zend_Dojo::enableForm()</methodname>.
  26             </para>
  27         </listitem>
  28
  29         <listitem>
  30             <para>
  31                 Use the Dojo-specific form and subform implementations,
  32                 <classname>Zend_Dojo_Form</classname> and
  33                 <classname>Zend_Dojo_Form_SubForm</classname> respectively. These can be
  34                 used as drop-in replacements for <classname>Zend_Form</classname> and
  35                 <classname>Zend_Form_SubForm</classname>, contain all the appropriate
  36                 decorator and element paths, set a Dojo-specific default
  37                 DisplayGroup class, and dojo-enable the view.
  38             </para>
  39         </listitem>
  40
  41         <listitem>
  42             <para>
  43                 Last, and most tedious, you can set the appropriate decorator
  44                 and element paths yourself, set the default DisplayGroup class,
  45                 and dojo-enable the view. Since
  46                 <methodname>Zend_Dojo::enableForm()</methodname> does this already, there's
  47                 little reason to go this route.
  48             </para>
  49         </listitem>
  50     </itemizedlist>
  51
  52     <example id="zend.dojo.form.enable">
  53         <title>Enabling Dojo in your existing forms</title>
  54
  55         <para>
  56             "But wait," you say; "I'm already extending <classname>Zend_Form</classname> with my own
  57             custom form class! How can I Dojo-enable it?'"
  58         </para>
  59
  60         <para>
  61             First, and easiest, simply change from extending
  62             <classname>Zend_Form</classname> to extending <classname>Zend_Dojo_Form</classname>,
  63             and update any places where you instantiate
  64             <classname>Zend_Form_SubForm</classname> to instantiate
  65             <classname>Zend_Dojo_Form_SubForm</classname>.
  66         </para>
  67
  68         <para>
  69             A second approach is to call <methodname>Zend_Dojo::enableForm()</methodname>
  70             within your custom form's <methodname>init()</methodname> method; when the form
  71             definition is complete, loop through all SubForms to dojo-enable
  72             them:
  73         </para>
  74
  75         <programlisting language="php"><![CDATA[
  76 class My_Form_Custom extends Zend_Form
  77 {
  78     public function init()
  79     {
  80         // Dojo-enable the form:
  81         Zend_Dojo::enableForm($this);
  82
  83         // ... continue form definition from here
  84
  85         // Dojo-enable all sub forms:
  86         foreach ($this->getSubForms() as $subForm) {
  87             Zend_Dojo::enableForm($subForm);
  88         }
  89     }
  90 }
  91 ]]></programlisting>
  92     </example>
  93
  94     <para>
  95         Usage of the dijit-specific form decorators and elements is just like
  96         using any other form decorator or element.
  97     </para>
  98
  99     <xi:include href="Zend_Dojo-Form-Decorators.xml" />
 100     <xi:include href="Zend_Dojo-Form-Elements.xml" />
 101     <xi:include href="Zend_Dojo-Form-Examples.xml" />
 102 </sect1>
 103 <!--
 104 vim:se ts=4 sw=4 et:
 105 -->