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

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml	2011-11-04 14:34:53 UTC (rev 318779)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml	2011-11-04 17:07:16 UTC (rev 318780)
@@ -228,8 +228,12 @@
     phd:linkend="HTML_QuickForm2_Container::getElementById">getElementById()</phd:pearapi>, <phd:pearapi
     phd:package="HTML_QuickForm2"
     phd:linkend="HTML_QuickForm2_Container::getElementsByName">getElementsByName()</phd:pearapi>.
-   Their behaviour should not be too difficult to guess, the code
-   <programlisting role="php">
+   Those who have worked with Javascript or PHP's DOM extension should find these familiar.
+  </para>
+  <example>
+   <title>DOM-like API for Container</title>
+   <para>
+    <programlisting role="php">
 <![CDATA[
 $fieldset = new HTML_QuickForm2_Container_Fieldset();

@@ -250,17 +254,18 @@
     echo $radio . "\n";
 }
 ]]>
-   </programlisting>
-   will output
-   <screen>
+    </programlisting>
+    will output
+    <screen>
 <![CDATA[
 <input type="radio" value="on" id="radioOne" name="aRadio" />

 <input type="radio" value="on" id="radioTwo" name="aRadio" />
 <input type="radio" value="on" id="radioThree" name="aRadio" />
 ]]>
-   </screen>
-  </para>
+    </screen>
+   </para>
+  </example>
   <para>
    A few convenience methods are also available: <phd:pearapi phd:package="HTML_QuickForm2"
     phd:linkend="HTML_QuickForm2_Container::getElements">getElements()</phd:pearapi> returns an
@@ -282,8 +287,12 @@
     phd:linkend="HTML_QuickForm2_Container::getRecursiveIterator">getRecursiveIterator()</phd:pearapi>
    method which returns an instance of <phd:pearapi phd:package="HTML_QuickForm2"
     phd:linkend="HTML_QuickForm2_ContainerIterator"/> for recursive iteration over
-   <emphasis>all</emphasis> child elements:
-   <programlisting role="php">
+   <emphasis>all</emphasis> child elements.
+  </para>
+  <example>
+   <title>SPL interfaces support</title>
+   <para>
+    <programlisting role="php">
 <![CDATA[
 $outer = new HTML_QuickForm2_Container_Fieldset();
 $inner = $outer->addElement('fieldset')->setId('inner');
@@ -298,9 +307,9 @@
     echo $child->getId() . "\n";
 }
 ]]>
-   </programlisting>
-   The above code will output
-   <screen>
+    </programlisting>
+    The above code will output
+    <screen>
 <![CDATA[
 1
 inner
@@ -308,8 +317,9 @@
 inner
 textId
 ]]>
-   </screen>
-  </para>
+    </screen>
+   </para>
+  </example>
  </refsection>

  <refsection xml:id="package.html.html-quickform2.elements.list">
@@ -336,6 +346,26 @@
 ]]>
    </programlisting>
   </para>
+  <para>
+   New element types can be registered by <phd:pearapi
+    phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Factory::registerElement" />,
+   <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Factory::isElementRegistered" /> checks whether an element is known
+   to <classname>Factory</classname>.
+   <programlisting role="php">
+<![CDATA[
+HTML_QuickForm2_Factory::registerElement(
+    'dualselect', 'HTML_QuickForm2_Element_DualSelect'
+);
+
+// ...
+
+if (HTML_QuickForm2_Factory::isElementRegistered('dualselect')) {
+    $form->addElement('dualselect', 'dualselectDemo', $attributes, $config);
+}
+]]>
+   </programlisting>
+  </para>
   <table>
    <title>Standard HTML form elements</title>
    <tgroup cols="3">

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml	2011-11-04 14:34:53 UTC (rev 318779)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml	2011-11-04 17:07:16 UTC (rev 318780)
@@ -479,11 +479,69 @@
    If more rules were chained to the added one with <function>and_</function> and
    <function>or_</function>, Javascript will be generated for the whole chain.
   </para>
+  <para>
+   Since release 0.6.0 it is possible to run client-side rules for an element on changing its value
+   or on it losing input focus (<literal>'onchange'</literal> and <literal>'onblur'</literal>
+   events) in addition to form submit (<literal>'onsubmit'</literal> event). This is triggered by
+   passing a <parameter>$runAt</parameter> parameter with
+   <constant>HTML_QuickForm2_Rule::ONBLUR_CLIENT</constant> flag set to
+   <function>addRule</function>. If a rule has chained rules, then validation will be triggered by
+   all elements appearing in a chain.
+   <programlisting role="php">
+<![CDATA[
+// here validation will be run onchange / onblur of both $newPassword and $repPassword fields
+$newPassword->addRule('empty', '', null, HTML_QuickForm2_Rule::ONBLUR_CLIENT_SERVER)
+            ->and_($repPassword->createRule('empty'))
+            ->or_($repPassword->createRule('eq', 'The passwords do not match', $newPassword));
+]]>
+   </programlisting>
+  </para>
+  <para>
+   Another change introduced in 0.6.0 is that validation errors are now output near the elements
+   instead of being shown in Javascript <function>alert</function>. In a nuthshell, client-side
+   validation behaviour in <package>HTML_QuickForm2</package> 0.6.0+ is more similar to that of
+   <link linkend="package.html.html-quickform-dhtmlrulestableless"><package>HTML_QuickForm_DHTMLRulesTableless</package></link>
+   than to that of old <package>HTML_QuickForm</package>.
+  </para>
+  <para>
+   Most of the built-in rules are able to run client-side, the only exceptions are
+   <varname>maxfilesize</varname> and <varname>mimetype</varname> rules specific for file uploads.
+  </para>
+  <para>
+   If you want to run <varname>callback</varname> rule client-side, you will obviously need to
+   implement a callback in Javascript as well as in PHP. If you don't explicitly set
+   <parameter>'js_callback'</parameter> configuration parameter, <varname>callback</varname> rule
+   will try to run Javascript function having the same name as provided PHP
+   <parameter>'callback'</parameter>. This may be especially useful if you use
+   <package>HTML_AJAX</package> to <phd:pearapi phd:package="HTML_AJAX"
+    phd:linkend="HTML_AJAX::registerClass">proxy PHP classes</phd:pearapi> or <phd:pearapi
+    phd:package="HTML_AJAX" phd:linkend="HTML_AJAX::registerPhpCallback">callbacks</phd:pearapi> in
+   Javascript.
+  </para>
+  <para>
+   When running <varname>regex</varname> rules client-side, you should stick to regular expression
+   syntax common in PHP and Javascript:
+   <itemizedlist>
+    <listitem><simpara>
+     Use a slash <literal>/</literal> as a delimiter.
+    </simpara></listitem>
+    <listitem><simpara>
+     Use only <varname>i</varname>, <varname>m</varname>, <varname>u</varname> pattern modifiers. If
+     <varname>u</varname> modifier is used, PHP's Unicode escapes
+     <replaceable>\x{NNNN}</replaceable> are automatically converted to Javascript's Unicode escapes
+     <replaceable>\uNNNN</replaceable> when creating a client-side rule.
+    </simpara></listitem>
+    <listitem><simpara>
+     Do not use regular expession features that are not supported in Javascript (e.g. lookbehind
+     assertions).
+    </simpara></listitem>
+   </itemizedlist>
+  </para>
   <note>
    <para>
     While it is possible to add a client-side only rule
     <programlisting role="php">
-<![CDATA[
+     <![CDATA[
 $username->addRule('minlength', 'Username should be at least 4 characters long', 4,
                    HTML_QuickForm2_Rule::CLIENT);
 ]]>
@@ -491,19 +549,5 @@
     it is not recommended unless you perform the same validation server-side using some other rule.
    </para>
   </note>
-  <para>
-   Most of the built-in rules are able to run client-side, the only exceptions are
-   <varname>maxfilesize</varname> and <varname>mimetype</varname> rules specific for file uploads.
-  </para>
-  <tip>
-   <para>
-    If you want to run <varname>callback</varname> rule client-side, you will obviously need to
-    implement a callback in Javascript as well as in PHP. If you don't explicitly set
-    <parameter>'js_callback'</parameter> configuration parameter, <varname>callback</varname> rule
-    will try to run Javascript function having the same name as provided PHP
-    <parameter>'callback'</parameter>. This may be especially useful if you use
-    <classname>HTML_AJAX</classname> to create proxy classes in Javascript.
-   </para>
-  </tip>
  </refsection>
 </refentry>