svn: /pear/peardoc/trunk/en/package/html/html-quickform2/ elements.xml renderers.xml rules.xml

avb                                      Thu, 22 Mar 2012 21:28:22 +0000

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

Log:
Document additions in 2.0.0beta1

Changed paths:
    U   pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml
    U   pear/peardoc/trunk/en/package/html/html-quickform2/renderers.xml
    U   pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml 2012-03-22 21:03:34 UTC (rev 324472)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml 2012-03-22 21:28:22 UTC (rev 324473)
@@ -166,7 +166,10 @@
 <input type="text" id="textBoxId" size="20" name="textBox" />
 ]]>
    </screen>
-   More complex output needs are covered by <function>render</function> method.
+   Complex output needs of form elements (including <classname>HTML_QuickForm2</classname> itself)
+   are covered by <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Node::render">render()</phd:pearapi> method accepting a specialized
+   <link linkend="package.html.html-quickform2.renderers">Renderer</link> object.
   </para>
   <para>
    A helpful feature of <package>HTML_QuickForm2</package> is the ability to "freeze" form

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/renderers.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/renderers.xml 2012-03-22 21:03:34 UTC (rev 324472)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/renderers.xml 2012-03-22 21:28:22 UTC (rev 324473)
@@ -57,6 +57,33 @@
 ]]>
    </programlisting>
   </para>
+  <para>
+   The following renderers are installed with the package:
+   <itemizedlist>
+    <listitem><para>
+     <link linkend="package.html.html-quickform2.renderers.default">Default</link> - supports the
+     possibility to do
+     <programlisting role="php">
+<![CDATA[
+echo $form;
+]]>
+     </programlisting>
+    </para></listitem>
+    <listitem><para>
+     <phd:pearapi phd:package="HTML_QuickForm2"
+      phd:linkend="HTML_QuickForm2_Renderer_Callback">Callback</phd:pearapi> - uses PHP callback
+     functions to output the form.
+    </para></listitem>
+    <listitem><para>
+     <link linkend="package.html.html-quickform2.renderers.array">Array</link> - converts form
+     structure to an array.
+    </para></listitem>
+    <listitem><para>
+     <link linkend="package.html.html-quickform2.renderers.stub">Stub</link> - does minimal form
+     processing when actual output is done manually.
+    </para></listitem>
+   </itemizedlist>
+  </para>
  </refsection>


@@ -132,7 +159,8 @@
   </para>

   <para>
-   All built-in renderers also implement <function>reset</function> method that clears all
+   <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Renderer::reset">reset()</phd:pearapi> method that clears all
    accumulated data. It is called automatically when rendering a
    <classname>HTML_QuickForm2</classname> object, but must be called manually when rendering form
    elements separately.
@@ -158,10 +186,13 @@
   <para>
    The elements are output in the order they were added using an appropriate template, which looks
    similar to the following:
-   <programlisting>
+   <programlisting role="html">
 <![CDATA[
 <div class="row">
- <label for="{id}" class="element"><qf:required><span class="required">* </span></qf:required>{label}</label>
+ <p class="label">
+  <qf:required><span class="required">*</span></qf:required>
+  <qf:label><label for="{id}">{label}</label></qf:label>
+ </p>
  <div class="element<qf:error> error</qf:error>">
   <qf:error><span class="error">{error}<br /></span></qf:error>
   {element}
@@ -469,7 +500,71 @@
   </tip>
  </refsection>

+ <refsection xml:id="package.html.html-quickform2.renderers.stub">
+  <info>
+   <title>Stub Renderer</title>
+  </info>
+  <para>
+   You may often want to output form elements manually, especially if the form has a complex layout:
+   <programlisting role="html">
+<![CDATA[
+<complex html><?= $form->getElementById('someElement'); ?><more complex html>
+]]>
+   </programlisting>
+   or, if using a template engine
+   <programlisting role="html">
+<![CDATA[
+<complex html>{{ form.getElementById('someElement') }}<more complex html>
+]]>
+   </programlisting>
+  </para>
+  <para>
+   Hovewer, you will require a rendering step if your form uses client-side validation or contains
+   Javascript-backed elements like Hierselect. Stub renderer can be used in such circumstances to
+   reduce overhead as the results of a more complex renderer like Default will be discarded.
+  </para>
+  <para>
+   Stub renderer serves as a container for JavascriptBuilder object and does some minimal form
+   processing: it can group errors and hidden elements if <literal>group_errors</literal> and
+   <literal>group_hiddens</literal> parameters are set to true. The accumulated data is available
+   through <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Renderer_Stub::getErrors">getErrors()</phd:pearapi> and
+   <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Renderer_Stub::getHidden">getHidden()</phd:pearapi> methods,
+   respectively. You can also use <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Renderer_Stub::hasRequired">hasRequired()</phd:pearapi> method to
+   check whether form contains required elements.
+  </para>
+  <example xml:id="package.html.html-quickform2.renderers.stub.usage">
+   <info>
+    <title>Using Stub Renderer</title>
+   </info>
+   <programlisting role="php">
+<![CDATA[
+$renderer = $form->render(
+    HTML_QuickForm2_Renderer::factory('stub')
+        ->setOption('group_errors', true);
+);

+// outputting JS libraries
+foreach ($renderer->getJavascriptBuilder()->getLibraries() as $link) {
+    echo $link . "\n";
+}
+// outputting form errors
+foreach ($renderer->getErrors() as $id => $error) {
+    echo "<a href=\"#{$id}\">{$error}</a><br />";
+}
+
+// ...
+// form output code goes here
+// ...
+
+echo $renderer->getJavascriptBuilder()->getFormJavascript();
+]]>
+   </programlisting>
+  </example>
+ </refsection>
+
  <refsection xml:id="package.html.html-quickform2.renderers.creation">
   <info>
    <title>Creating Renderer objects</title>

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml 2012-03-22 21:03:34 UTC (rev 324472)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml 2012-03-22 21:28:22 UTC (rev 324473)
@@ -231,6 +231,14 @@
        client-side validation.</entry>
      </row>
      <row valign="top">
+      <entry><varname>email</varname></entry>
+      <entry><phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Rule_Email" /></entry>
+      <entry>Checks that the field value is a valid email address. Currently the most common address
+       format is recognised, support for additional <link xmlns:xlink="http://www.w3.org/1999/xlink"
+        xlink:href="&url.rfc;5321">RFC 5321</link> features and DNS checks is planned.</entry>
+      <entry/>
+     </row>
+     <row valign="top">
       <entry><varname>callback</varname></entry>
       <entry><phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Rule_Callback" /></entry>
       <entry>Checks the value using a provided callback function (method). It is expected to return


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