svn: /pear/peardoc/trunk/en/package/html/html-quickform2/ javascript.xml qf-migration.xml

avb                                      Tue, 01 May 2012 09:41:04 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=325487

Log:
Mention quickform-repeat.js in a list of JS files, improve migration guide a bit (e.g. form rules seem a common question)

Changed paths:
    U   pear/peardoc/trunk/en/package/html/html-quickform2/javascript.xml
    U   pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml

---

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/javascript.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/javascript.xml 2012-05-01 09:06:31 UTC (rev 325486)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/javascript.xml 2012-05-01 09:41:04 UTC (rev 325487)
@@ -124,7 +124,7 @@
    <title>Including JS library files</title>
   </info>
   <para>
-   There are currently two library files installed with the package:
+   There are currently three library files installed with the package:
    <variablelist>
     <varlistentry>
      <term><filename>quickform.js</filename></term>
@@ -135,10 +135,17 @@
     <varlistentry>
      <term><filename>quickform-hierselect.js</filename></term>
      <listitem><simpara>
-      Support functions for <phd:pearapi phd:package="HTML_QuickForm2"
-       phd:linkend="HTML_QuickForm2_Element_Hierselect">hierselect elements</phd:pearapi>.
+      Support functions for <link
+       linkend="package.html.html-quickform2.elements.custom.hierselect">hierselect elements</link>.
      </simpara></listitem>
     </varlistentry>
+    <varlistentry>
+     <term><filename>quickform-repeat.js</filename></term>
+     <listitem><simpara>
+      Support functions for <link linkend="package.html.html-quickform2.elements.repeat">repeat
+       elements</link>.
+     </simpara></listitem>
+    </varlistentry>
    </variablelist>
    Human-readable versions of these files are installed into <filename
     class="directory">HTML_QuickForm2/js</filename> directory under PEAR's

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml 2012-05-01 09:06:31 UTC (rev 325486)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml 2012-05-01 09:41:04 UTC (rev 325487)
@@ -80,9 +80,9 @@
   <para>
    Unlike HTML_QuickForm, where nesting of form elements was limited (elements could be added either
    directly to the form or to a group added directly to the form) HTML_QuickForm2 supports unlimited
-   nesting. Elements that can contain other elements are subclasses of <phd:pearapi
-    phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Container" /> which implements
-   DOM-like API: <phd:pearapi phd:package="HTML_QuickForm2"
+   nesting. Elements that can contain other elements are subclasses of <link
+    linkend="package.html.html-quickform2.elements.container"><classname>HTML_QuickForm2_Container</classname></link>
+   which implements DOM-like API: <phd:pearapi phd:package="HTML_QuickForm2"
     phd:linkend="HTML_QuickForm2_Container::appendChild">appendChild()</phd:pearapi>, <phd:pearapi
     phd:package="HTML_QuickForm2"
     phd:linkend="HTML_QuickForm2_Container::insertBefore">insertBefore()</phd:pearapi>, <phd:pearapi
@@ -316,16 +316,37 @@
    </programlisting>
   </para>
   <para>
-   There is no longer a special <phd:pearapi phd:package="HTML_QuickForm"
-    phd:linkend="HTML_QuickForm::addFormRule" /> method. You can achieve similar behaviour by
-   creating a subclass of <phd:pearapi phd:package="HTML_QuickForm2"
-    phd:linkend="HTML_QuickForm2_Rule" />, implementing its
+   There is no longer a special <link
+    linkend="package.html.html-quickform.html-quickform.addformrule"><function>addFormRule</function></link>
+   method. You can achieve similar behaviour by creating a subclass of <phd:pearapi
+    phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Rule" />, implementing its
    <phd:pearapi phd:package="HTML_QuickForm2"
     phd:linkend="HTML_QuickForm2_Rule::validateOwner">validateOwner()</phd:pearapi> and
    <phd:pearapi phd:package="HTML_QuickForm2"
     phd:linkend="HTML_QuickForm2_Rule::setOwnerError">setOwnerError()</phd:pearapi> methods and
-   adding an instance of that Rule directly to the form. Note, though, that it may be easier to use
-   Rule chaining instead in most cases.
+   adding an instance of that Rule directly to the form:
+   <programlisting role="php"><![CDATA[
+class FormRule extends HTML_QuickForm2_Rule
+{
+    protected function validateOwner()
+    {
+        $fooValue = $this->owner->getElementById('foo')->getValue();
+        $barValue = $this->owner->getElementById('bar')->getValue();
+
+        return someComplexCheck($fooValue, $barValue);
+    }
+
+    protected function setOwnerError()
+    {
+        $this->owner->getElementById('foo')->setError('foo error');
+        $this->owner->getElementById('bar')->setError('bar error');
+    }
+}
+
+$form->addRule(new FormRule($form));
+    ]]></programlisting>
+   Note, though, that it may be easier to use <link
+    linkend="package.html.html-quickform2.rules.chaining">Rule chaining</link> instead in most cases.
   </para>
   <para>
    <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Element_InputFile">File
@@ -347,7 +368,7 @@
    <title>Outputting the form</title>
   </info>
   <para>
-   It is quite easy to output the form in HTML_QuickForm2 thanks to a magic
+   Basic form output in <package>HTML_QuickForm2</package> is quite easy thanks to a magic
    <function>__toString</function> method:
    <programlisting role="php">
 <![CDATA[
@@ -355,13 +376,18 @@
 ]]>
    </programlisting>
    Under the hood the package uses Renderer setup similar to that of HTML_QuickForm. Currently
-   HTML_QuickForm2 contains ports of <phd:pearapi phd:package="HTML_QuickForm2"
-    phd:linkend="HTML_QuickForm2_Renderer_Default">Default</phd:pearapi> and <phd:pearapi
-     phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Renderer_Array">Array</phd:pearapi>
-   renderers from HTML_QuickForm, renderers for specific template engines are unlikely to be added
-   to the base package.
+   HTML_QuickForm2 contains ports of <link
+    linkend="package.html.html-quickform2.renderers.default">Default</link> and <link
+    linkend="package.html.html-quickform2.renderers.array">Array</link> renderers from
+   <package>HTML_QuickForm</package>, renderers for specific template engines are unlikely to be
+   added to the base package.
   </para>
   <para>
+   Method that accepts a Renderer instance to output the element is now called <phd:pearapi
+    phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Node::render">render()</phd:pearapi>
+   rather than <function>accept</function> as in <package>HTML_QuickForm</package>.
+  </para>
+  <para>
    Default renderer in HTML_QuickForm2 is different from that in HTML_QuickForm:
    <itemizedlist>
     <listitem><simpara>Form is output without HTML tables, similar to <link
@@ -376,8 +402,9 @@
     examples</link> installed with the package, they contain useful bits on styling the form.
   </para>
   <para>
-   Strictly speaking, it is not necessary to use a Renderer with HTML_QuickForm2 since you can just
-   iterate over the elements and output them
+   It is also quite easy to output the form manually by <link
+    linkend="package.html.html-quickform2.elements.container.spl">iterating over its
+    elements</link>,
    <programlisting role="php">
 <![CDATA[
 foreach ($form as $element) {
@@ -386,13 +413,17 @@
 }
 ]]>
    </programlisting>
-   but bear in mind that client-side validation rules are built when rendering the form and that
-   Default renderer allows easy output customization.
+   but <link linkend="package.html.html-quickform2.rules.clientside">client-side validation
+   rules</link> are built in the course of the <function>render</function> call, so there is a
+   special <link linkend="package.html.html-quickform2.renderers.stub">Stub renderer</link> to
+   assist with manual output.
   </para>
   <para>
-   If you are using client-side validation or javascript-backed elements like hierselect, you should
-   take care that necessary javascript libraries are included in the page before the form. Consult
-   the <link linkend="package.html.html-quickform2.javascript">section on Javascript support</link>.
+   If you are using client-side validation or javascript-backed elements like <link
+    linkend="package.html.html-quickform2.elements.custom.hierselect">hierselect</link> or <link
+    linkend="package.html.html-quickform2.elements.repeat">repeat</link>, you should take care that
+   necessary javascript libraries are included in the page before the form. Consult the <link
+    linkend="package.html.html-quickform2.javascript">section on Javascript support</link>.
   </para>
  </refsection>
 </refentry>

---

--
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php