svn: /pear/peardoc/trunk/en/package/html/ html-quickform2/controller-migration.xml html-quickform2/controller-overview.xml html-quickform2/qf-migration.xml html-quickform2/rules.xml html-quickform2.xml

Added: pear/peardoc/trunk/en/package/html/html-quickform2/controller-migration.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/controller-migration.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/controller-migration.xml	2011-10-22 09:27:56 UTC (rev 318315)
@@ -0,0 +1,173 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.html.html-quickform2.controller-migration"
+>
+ <refnamediv>
+  <refname>Migration from HTML_QuickForm_Controller</refname>
+  <refpurpose>Step-by-step guide for porting your scripts to HTML_QuickForm2_Controller</refpurpose>
+ </refnamediv>
+ <refsection xml:id="package.html.html-quickform2.controller-migration.overview">
+  <info>
+   <title>Overview</title>
+  </info>
+  <para>
+   This guide is intended for current users of <link
+    linkend="package.html.html-quickform-controller"><classname>HTML_QuickForm_Controller</classname></link>
+   who want to update their scripts to <classname>HTML_QuickForm2</classname>, which now includes a
+   rewrite of older controller package. It covers major API changes and provides links to further
+   documentation.
+  </para>
+  <para>
+   It should be noted that API of <classname>HTML_QuickForm2_Controller</classname> is more similar
+   to API of <classname>HTML_QuickForm_Controller</classname> than that of
+   <classname>HTML_QuickForm2</classname> and <classname>HTML_QuickForm</classname>. That being
+   said, there are some important differences in method names and behaviour.
+  </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.controller-migration.controller">
+  <info>
+   <title>Controller class and session data</title>
+  </info>
+  <para>
+   Of the methods you are most likely to use in your applications, former <phd:pearapi
+    phd:package="HTML_QuickForm_Controller" phd:linkend="HTML_QuickForm_Controller::addAction"/> is
+   now <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller::addHandler"/> and <phd:pearapi
+    phd:package="HTML_QuickForm_Controller" phd:linkend="HTML_QuickForm_Controller::exportValues"/>
+   is now <phd:pearapi
+    phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Controller::getValue"/>.
+  </para>
+  <para>
+   As is the case with <link
+    linkend="package.html.html-quickform2.qf-migration.defaults"><classname>HTML_QuickForm2</classname>
+    itself</link>, <classname>HTML_QuickForm2_Controller</classname> no longer has
+   <function>setDefaults</function> and <function>setConstants</function> methods. So instead of
+   former call to <phd:pearapi phd:package="HTML_QuickForm_Controller"
+    phd:linkend="HTML_QuickForm_Controller::setDefaults" />
+   <programlisting role="php">
+<![CDATA[
+$controller->setDefaults(array(
+    'foo' => 'default foo value',
+    'bar' => 'default bar value'
+));
+]]>
+   </programlisting>
+   you should use <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller::addDataSource" />:
+   <programlisting role="php">
+<![CDATA[
+$controller->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'foo' => 'default foo value',
+    'bar' => 'default bar value'
+)));
+]]>
+   </programlisting>
+   Like with older defaults and constants, Controller DataSources are stored in session. Note that
+   Controller itself does not have a method for replacing the DataSource array similar to <phd:pearapi
+    phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2::setDataSources" />, use <phd:pearapi
+    phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller_SessionContainer::storeDatasources" />.
+  </para>
+  <para>
+   Instead of the former <phd:pearapi phd:package="HTML_QuickForm_Controller"
+    phd:linkend="HTML_QuickForm_Controller::container" /> method that both returned a reference to a
+   session variable storing Controller data and cleared this variable if requested, there is now
+   <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller::getSessionContainer">getSessionContainer()</phd:pearapi>
+   method that returns an instance of <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller_SessionContainer" /> wrapping around session variable
+   and <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller::destroySessionContainer">destroySessionContainer()</phd:pearapi>
+   method that clears the session variable.
+  </para>
+  <para>
+   You no longer need to directly access the session variable to store some custom values:
+   <programlisting role="php">
+<![CDATA[
+// Note the references
+// on source page:
+$data =& $controller->container();
+$data['_my_stuff'] = $stuff;
+// later on target page:
+$data =& $controller->container();
+$stuff = $data['_my_stuff'];
+]]>
+   </programlisting>
+   you should use instead the <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller_SessionContainer::storeOpaque">storeOpaque()</phd:pearapi>
+   and <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller_SessionContainer::getOpaque">getOpaque()</phd:pearapi>
+   methods of <classname>HTML_QuickForm2_Controller_SessionContainer</classname>:
+   <programlisting role="php">
+<![CDATA[
+// on source page:
+$controller->getSessionContainer()->storeOpaque('my_stuff', $stuff);
+// later on target page:
+$stuff = $controller->getSessionContainer()->getOpaque('my_stuff');
+]]>
+   </programlisting>
+   SessionContainer also has methods for storing and getting Controller DataSources, form values and form
+   validation statuses, these should be used when writing custom action handlers.
+  </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.controller-migration.page">
+  <info>
+   <title>Form page class</title>
+  </info>
+  <para>
+   The main difference between <phd:pearapi phd:package="HTML_QuickForm_Controller"
+    phd:linkend="HTML_QuickForm_Page" /> and <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller_Page" /> is that the latter no longer extends the form
+   class, its constructor accepting an instance of <classname>HTML_QuickForm2</classname>:
+   <programlisting role="php">
+<![CDATA[
+class TutorialPage extends HTML_QuickForm2_Controller_Page
+{
+// ...
+}
+
+$page = new TutorialPage(new HTML_QuickForm2('tutorial'));
+]]>
+   </programlisting>
+   This allows using custom subclasses of <classname>HTML_QuickForm2</classname> with Controller and
+   prevents problems like <link
+    linkend="package.html.html-quickform-dhtmlrulestableless">HTML_QuickForm_DHTMLRulesTableless</link>
+   faced, having to include both <phd:pearapi phd:package="HTML_QuickForm_DHTMLRulesTableless"
+    phd:linkend="HTML_QuickForm_DHTMLRulesTableless" /> and <phd:pearapi phd:package="HTML_QuickForm_DHTMLRulesTableless"
+    phd:linkend="HTML_QuickForm_PageDHTMLRulesTableless" /> the former extending
+   <classname>HTML_QuickForm</classname> and the latter <classname>HTML_QuickForm_Page</classname>.
+  </para>
+  <para>
+   <varname>$controller</varname> is no longer a public property of Page, use <phd:pearapi
+    phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller_Page::getController">getController()</phd:pearapi> to
+   access it. Similarly, use <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller_Page::getForm">getForm()</phd:pearapi> to access the
+   instance of <classname>HTML_QuickForm2</classname>.
+  </para>
+  <para>
+   As with <classname>HTML_QuickForm_Controller</classname>, former <phd:pearapi
+    phd:package="HTML_QuickForm_Controller" phd:linkend="HTML_QuickForm_Page::addAction"/> is
+   now <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller_Page::addHandler"/>, old <phd:pearapi phd:package="HTML_QuickForm_Controller"
+    phd:linkend="HTML_QuickForm_Page::buildForm" /> is renamed to <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Controller_Page::populateForm" />.
+  </para>
+  <para>
+   In new <function>HTML_QuickForm2_Controller_Page::populateForm</function> one no longer has to do
+   something like
+   <programlisting role="php">
+<![CDATA[
+$this->_formBuilt = true;
+]]>
+   </programlisting>
+   as was needed in old <function>HTML_QuickForm_Page::buildForm</function>, the Page itself now
+   makes sure that <function>populateForm</function> is called only once.
+  </para>
+ </refsection>
+</refentry>
\ No newline at end of file

Added: pear/peardoc/trunk/en/package/html/html-quickform2/controller-overview.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/controller-overview.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/controller-overview.xml	2011-10-22 09:27:56 UTC (rev 318315)
@@ -0,0 +1,321 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.html.html-quickform2.controller-overview"
+>
+ <refnamediv>
+  <refname>Overview of QuickForm2_Controller</refname>
+  <refpurpose>Easy building of multipage forms</refpurpose>
+ </refnamediv>
+ <refsection xml:id="package.html.html-quickform2.controller-overview.what">
+  <info>
+   <title>What is HTML_QuickForm2_Controller?</title>
+  </info>
+  <para>
+   If you are already familiar with MVC frameworks, then you probably know: controller is a
+   component that accepts user input and instructs other components to perform actions based on that
+   input. <package>HTML_QuickForm2_Controller</package> is somewhat smaller in scope than a typical
+   framework controller since it only deals with forms. When using the Controller, an action name is
+   sent in <literal>GET</literal> or <literal>POST</literal> data, usually by clicking a specially
+   named button. This name contains <varname>id</varname> of the form and name of action handler to
+   call (e.g. <literal>'next'</literal> for going forward in a wizard), so Controller has to extract
+   that data and call the requested handler on the requested form.
+  </para>
+  <para>
+   Key features:
+   <itemizedlist>
+    <listitem><simpara>
+     Binds OO action handlers to buttons that submit the form;
+    </simpara></listitem>
+    <listitem><simpara>
+     Includes default action handlers that allow easy building of multipage forms;
+    </simpara></listitem>
+    <listitem><simpara>
+     Even if you only use it for single-page forms, form-related logic is kept in classes rather
+     than in procedural code.
+    </simpara></listitem>
+   </itemizedlist>
+  </para>
+  <para>
+   Key classes and interfaces:
+   <variablelist>
+    <varlistentry>
+     <term><phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Controller"/></term>
+     <listitem><simpara>
+      Extracts the action name from request and calls the appropriate handler. Contains several
+      Pages and a <phd:pearapi phd:package="HTML_QuickForm2"
+       phd:linkend="HTML_QuickForm2_Controller_SessionContainer">wrapper for values stored in
+      session</phd:pearapi>.
+     </simpara></listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Controller_Page"/></term>
+     <listitem><simpara>
+      Class representing a single page of the form. Contains an instance of <phd:pearapi
+       phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2"/>.
+     </simpara></listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Controller_Action"/></term>
+     <listitem><simpara>
+      Action handlers implement this interface.
+     </simpara></listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+  <para>
+   <classname>HTML_QuickForm2_Controller</classname> is a rewrite of PHP4 <link
+    linkend="package.html.html-quickform-controller"><classname>HTML_QuickForm_Controller</classname></link>,
+   so if you are already using the latter you can go to <link
+    linkend="package.html.html-quickform2.controller-migration">migration guide</link>
+   which contains step-by-step instructions for porting your scripts to new package.
+  </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.controller-overview.example">
+  <info>
+   <title>Basic usage example</title>
+  </info>
+  <note>
+   <info>
+    <title>Session initialization</title>
+   </info>
+   <para>
+    This simple example does not use sessions since there is no need to pass data between pages.
+    You&apos;ll need to use sessions when dealing with a real multipage form, though.
+    <classname>HTML_QuickForm2_Controller</classname> <emphasis>does not</emphasis> start a session
+    automatically, you should explicitly call <link xmlns:xlink="http://www.w3.org/1999/xlink"
+     xlink:href="&url.php.lookup;session_start"><function>session_start</function></link> before instantiating
+    the controller class.
+   </para>
+  </note>
+  <para>
+   The same example form that was used in the <link
+    linkend="package.html.html-quickform2.tutorial.example">package&apos;s tutorial</link> will now
+   be rewritten using the Controller:
+   <example>
+    <info>
+     <title>Builds and processes a form with a single input field, using Controller</title>
+    </info>
+    <programlisting role="php">
+<![CDATA[
+// Load the main class
+require_once 'HTML/QuickForm2.php';
+// Load the controller
+require_once 'HTML/QuickForm2/Controller.php';
+// Load the Action interface (we will implement it)
+require_once 'HTML/QuickForm2/Controller/Action.php';
+
+// Class representing a form page
+class TutorialPage extends HTML_QuickForm2_Controller_Page
+{
+    protected function populateForm()
+    {
+        // Add some elements to the form
+        $fieldset = $this->form->addElement('fieldset')->setLabel('QuickForm2_Controller tutorial example');
+        $name = $fieldset->addElement('text', 'name', array('size' => 50, 'maxlength' => 255))
+                         ->setLabel('Enter your name:');
+
+        // We set the name of the submit button so that it binds to default 'submit' handler
+        $fieldset->addElement('submit', $this->getButtonName('submit'),
+                              array('value' => 'Send!'));
+        // The action to call if a user presses Enter rather than clicks on a button
+        $this->setDefaultAction('submit');
+
+        // Define filters and validation rules
+        $name->addFilter('trim');
+        $name->addRule('required', 'Please enter your name');
+    }
+}
+
+// Action to process the form after successful validation
+class TutorialProcess implements HTML_QuickForm2_Controller_Action
+{
+    public function perform(HTML_QuickForm2_Controller_Page $page, $name)
+    {
+        $values = $page->getController()->getValue();
+        echo '<h1>Hello, ' . htmlspecialchars($values['name']) . '!</h1>';
+    }
+}
+
+$page = new TutorialPage(new HTML_QuickForm2('tutorial'));
+// We only add the custom 'process' handler, Controller will care for default ones
+$page->addHandler('process', new TutorialProcess());
+
+$controller = new HTML_QuickForm2_Controller('tutorial');
+// Set defaults for the form elements
+$controller->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'name' => 'Joe User'
+)));
+$controller->addPage($page);
+// Process the request
+$controller->run();
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <para>
+   You may note that the above code is more verbose than the original. While that is definitely
+   true, to make a three page wizard you'll only need to create three subclasses of <phd:pearapi
+    phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Controller_Page"/>, a
+   <literal>'process'</literal> handler and add them to Controller, which already has default
+   handlers for typical <literal>'Back'</literal> and <literal>'Next'</literal> buttons. It will
+   require a non-trivial amount of programming without the Controller infrastructure.
+  </para>
+
+  <refsection xml:id="package.html.html-quickform2.controller-overview.example.pages">
+   <info>
+    <title>Creating form pages</title>
+   </info>
+   <para>
+    To define pages for your controller you need to subclass <phd:pearapi
+     phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Controller_Page" /> implementing
+    its abstract <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2_Controller_Page::populateForm">populateForm()</phd:pearapi>
+    method. Note that this method will be called on demand (i.e. only when the user sees the form in
+    question), so it is better performance-wise to keep all form-building code in it than to pass a
+    pre-populated instance of <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2"/> to page's constructor.
+   </para>
+   <para>
+    Most of the code in the method just repeats what was done in the original tutorial, however some
+    of it requires explanation:
+    <programlisting role="php">
+<![CDATA[
+// We set the name of the submit button so that it binds to default 'submit' handler
+$fieldset->addElement('submit', $this->getButtonName('submit'),
+                      array('value' => 'Send!'));
+// The action to call if a user presses Enter rather than clicks on a button
+$this->setDefaultAction('submit');
+]]>
+    </programlisting>
+    The first line uses <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2_Controller_Page::getButtonName">getButtonName()</phd:pearapi> to
+    set a special name for form's submit button and thus trigger a <literal>'submit'</literal>
+    action on a <literal>'tutorial'</literal> form when that button is clicked (default handler for
+    such action is implemented in <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2_Controller_Action_Submit" />). The second one sets an action to
+    trigger when no submit button is clicked (e.g. user presses <literal>Enter</literal> instead of
+    clicking). Under the hood this is done by adding an instance of <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2_Controller_DefaultAction" /> to the form.
+   </para>
+  </refsection>
+
+  <refsection xml:id="package.html.html-quickform2.controller-overview.example.actions">
+   <info>
+    <title>Creating custom action handlers</title>
+   </info>
+   <para>
+    You'll usually need custom handlers for only two actions:
+    <variablelist>
+     <varlistentry>
+      <term><literal>'process'</literal></term>
+      <listitem><simpara>
+       Called when the form is submitted and passes validation. In case of multipage forms that
+       means that all the pages are valid.
+      </simpara></listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>'display'</term>
+      <listitem><simpara>
+       Called when a form page needs to be displayed. It does have a default handler, but usually
+       you'll want to tweak the output.
+      </simpara></listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+   <para>
+    <literal>'process'</literal> handler is, obviously, completely application-specific and will
+    usually deal with storing the form values somewhere. When creating a custom
+    <literal>'display'</literal> handler it is easiest to subclass <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2_Controller_Action_Display" /> and override its <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2_Controller_Action_Display::renderForm">renderForm()</phd:pearapi>
+    method to use a Renderer or do any other tweaks you like.
+   </para>
+  </refsection>
+
+  <refsection xml:id="package.html.html-quickform2.controller-overview.example.controller">
+   <info>
+    <title>Setting up the controller</title>
+   </info>
+   <para>
+    First we instantiate the custom Page class and add a custom action handler to it
+    <programlisting role="php">
+<![CDATA[
+$page = new TutorialPage(new HTML_QuickForm2('tutorial'));
+// We only add the custom 'process' handler, Controller will care for default ones
+$page->addHandler('process', new TutorialProcess());
+]]>
+    </programlisting>
+    We don't bother with other action handlers as Controller will automatically load and use them.
+   </para>
+   <para>
+    Then we instantiate the controller
+    <programlisting role="php">
+<![CDATA[
+$controller = new HTML_QuickForm2_Controller('tutorial');
+]]>
+    </programlisting>
+    Note that Controller needs an <literal>id</literal> and it should be unique if you have several
+    Controllers in application, as it is used for storing values in session.
+   </para>
+   <para>
+    Then we add a <link
+     linkend="package.html.html-quickform2.values-datasources.datasources-overview">DataSource</link>
+    and the page to the Controller
+    <programlisting role="php">
+<![CDATA[
+// Set defaults for the form elements
+$controller->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'name' => 'Joe User'
+)));
+$controller->addPage($page);
+]]>
+    </programlisting>
+    While it is possible to add DataSource to an instance of <classname>HTML_QuickForm2</classname>
+    within Page instead, the above code allows setting the default values for the whole (possibly
+    multipage) form. Note also that Controller's DataSources, unlike form's, are stored in session.
+   </para>
+   <para>
+    Finally we call the Controller's <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2_Controller::run">run()</phd:pearapi> method
+    <programlisting role="php">
+<![CDATA[
+$controller->run();
+]]>
+    </programlisting>
+    which takes care of finding the name of the current action and calling the necessary handler.
+   </para>
+  </refsection>
+
+ </refsection>
+ <refsection xml:id="package.html.html-quickform2.controller-overview.further">
+  <info>
+   <title>Further usage examples</title>
+  </info>
+  <para>
+   More complex usage examples are installed with the package. Along with the form similar to the
+   above they include two multipage forms:
+   <itemizedlist>
+    <listitem><simpara>
+     Wizard: form pages contain <literal>'Next'</literal> and <literal>'Back'</literal> buttons and
+     you can't go to the next page unless the current page is valid.
+    </simpara></listitem>
+    <listitem><simpara>
+     Tabbed form: form has several pages and corresponding buttons allow going to the desired page
+     whether current one is valid or not. The global <literal>'Submit'</literal> button will not
+     allow form processing, however, unless all pages are valid.
+    </simpara></listitem>
+   </itemizedlist>
+  </para>
+  <para>
+   Controller examples are installed to directory <filename
+    role="dir">HTML_QuickForm2/examples/controller</filename> under PEAR's
+   <parameter>doc_dir</parameter>. If you have trouble finding where <parameter>doc_dir</parameter>
+   is, you can use <link linkend="guide.users.commandline.config">config-show</link> command of PEAR
+   installer.
+  </para>
+ </refsection>
+</refentry>
\ No newline at end of file

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml	2011-10-22 08:03:37 UTC (rev 318314)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml	2011-10-22 09:27:56 UTC (rev 318315)
@@ -299,7 +299,7 @@
    <programlisting role="php">
 <![CDATA[
 $username->addRule('minlength', 'Username should be at least 5 symbols long', 5,
-                   HTML_QuickForm2_Rule::SERVER | HTML_QuickForm2_Rule::CLIENT);
+                   HTML_QuickForm2_Rule::CLIENT_SERVER);
 ]]>
    </programlisting>
   </para>
@@ -320,10 +320,10 @@
    <programlisting role="php">
 <![CDATA[
 $phoneNo->addRule('required', 'Please fill all phone fields', 3,
-                  HTML_QuickForm2_Rule::SERVER | HTML_QuickForm2_Rule::CLIENT);
+                  HTML_QuickForm2_Rule::CLIENT_SERVER);
 $phoneNo->addRule('each', 'Values must be numeric',
                   $phoneNo->createRule('regex', '', '/^\\d+$/'),
-                  HTML_QuickForm2_Rule::SERVER | HTML_QuickForm2_Rule::CLIENT);
+                  HTML_QuickForm2_Rule::CLIENT_SERVER);
 ]]>
    </programlisting>
   </para>

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml	2011-10-22 08:03:37 UTC (rev 318314)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml	2011-10-22 09:27:56 UTC (rev 318315)
@@ -464,7 +464,7 @@
                    HTML_QuickForm2_Rule::SERVER | HTML_QuickForm2_Rule::CLIENT);
 // if first parameter to addRule() is a Rule instance:
 $username->addRule($username->createRule('required', 'Username is required'),
-                   HTML_QuickForm2_Rule::SERVER | HTML_QuickForm2_Rule::CLIENT);
+                   HTML_QuickForm2_Rule::CLIENT_SERVER); // using a shorthand for above constants
 ]]>
    </programlisting>
    If more rules were chained to the added one with <function>and_</function> and

Modified: pear/peardoc/trunk/en/package/html/html-quickform2.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2.xml	2011-10-22 08:03:37 UTC (rev 318314)
+++ pear/peardoc/trunk/en/package/html/html-quickform2.xml	2011-10-22 09:27:56 UTC (rev 318315)
@@ -41,6 +41,8 @@
   &package.html.html-quickform2.qf-migration;
   &package.html.html-quickform2.values-datasources;
   &package.html.html-quickform2.rules;
+  &package.html.html-quickform2.controller-overview;
+  &package.html.html-quickform2.controller-migration;
  </chapter>
 </book>