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

Added: pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml	2011-03-06 15:22:11 UTC (rev 308977)
@@ -0,0 +1,420 @@
+<?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.qf-migration"
+>
+ <refnamediv>
+  <refname>Migration from HTML_QuickForm</refname>
+  <refpurpose>Step-by-step guide for porting your scripts</refpurpose>
+ </refnamediv>
+ <refsection xml:id="package.html.html-quickform2.qf-migration.overview">
+  <info>
+   <title>Overview</title>
+  </info>
+  <para>
+   This guide is intended for users of <link
+    linkend="package.html.html-quickform"><classname>HTML_QuickForm</classname></link> who want to
+   update their scripts to use a new and improved major version of the package. It covers major API
+   changes and provides links to further documentation.
+  </para>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.qf-migration.creating">
+  <info>
+   <title>Creating elements</title>
+  </info>
+  <para>
+   Constructors of all the elements now have the same list of parameters:
+   <variablelist>
+    <varlistentry>
+     <term>&type.string; <parameter>$name</parameter></term>
+     <listitem><simpara>Element name</simpara></listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>&type.string;|&type.array; <parameter>$attributes</parameter></term>
+     <listitem><simpara>HTML attributes</simpara></listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>&type.array; <parameter>$data</parameter></term>
+     <listitem><simpara>Additional element-specific data. A <literal>'label'</literal> key in this
+      array is understood by every element and is used for element's label.</simpara></listitem>
+    </varlistentry>
+   </variablelist>
+   Consequently <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Factory::createElement" /> and <phd:pearapi
+    phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Container::addElement" /> that pass
+   their arguments to the element's constructor have fixed signatures, too.
+  </para>
+  <para>
+   For example, the following HTML_QuickForm code which adds a radio button and a select element to
+   the form
+   <programlisting role="php">
+<![CDATA[
+$form->addElement('radio', 'iradTest', 'Test Radio Buttons:', 'Check the radio button #1', 1,
+                  array('class' => 'fancyRadio'));
+$form->addElement('select', 'iselTest', 'Test Select:', array('A'=>'A', 'B'=>'B', 'C'=>'C', 'D'=>'D'),
+                  array('size' => 3, 'multiple' => 'multiple'));
+]]>
+   </programlisting>
+   in HTML_QuickForm2 will be transformed to
+   <programlisting role="php">
+<![CDATA[
+$form->addElement('radio', 'iradTest', array('class' => 'fancyRadio', 'value' => 1),
+                  array('label' => 'Test Radio Buttons:', 'content' => 'Check the radio button #1'));
+$form->addElement('select', 'iselTest', array('size' => 3, 'multiple' => 'multiple'),
+                  array('label' => 'Test Select:', 'options' => array('A'=>'A', 'B'=>'B', 'C'=>'C', 'D'=>'D'));
+]]>
+   </programlisting>
+   Another possibility is using fluent interfaces
+   <programlisting role="php">
+<![CDATA[
+$form->addElement('radio', 'iradTest', array('value' => 1))
+     ->addClass('fancyRadio')
+     ->setLabel('Test Radio Buttons:')
+     ->setContent('Check the radio button #1');
+$form->addElement('select', 'iselTest', array('size' => 3, 'multiple' => 'multiple'))
+     ->setLabel('Test Select:')
+     ->loadOptions(array('A'=>'A', 'B'=>'B', 'C'=>'C', 'D'=>'D'));
+]]>
+   </programlisting>
+   which has the benefits of improved readability and code completion in IDEs.
+  </para>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.qf-migration.building">
+  <info>
+   <title>Adding elements to the form</title>
+  </info>
+  <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"
+    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
+    phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container::removeChild">removeChild()</phd:pearapi>, <phd:pearapi
+    phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container::getElementById">getElementById()</phd:pearapi>, <phd:pearapi
+    phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container::getElementsByName">getElementsByName()</phd:pearapi>.
+   Convenience method <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container::addElement">addElement()</phd:pearapi> that creates an
+   element of the given type and adds it to the Container is still available, too. Thanks to
+   method overloading you can also perform <function>addEltype</function> calls where
+   <literal>'eltype'</literal> is an element type known to <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Factory" />:
+   <programlisting role="php">
+<![CDATA[
+$form->addText('testTextBox', array('style' => 'width: 20ex;'));
+]]>
+   </programlisting>
+  </para>
+  <para>
+   Note that HTML_QuickForm2 does not use HTML tables for rendering the form, so there is no
+   equivalent to <phd:pearapi phd:package="HTML_QuickForm"
+    phd:linkend="HTML_QuickForm_header">'header' element of
+   HTML_QuickForm</phd:pearapi>, fieldsets should be used to group form elements. Also there is no
+   special <phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm::addGroup" />,
+   groups are treated as any other element (<function>addGroup</function> <emphasis>will</emphasis>
+   work, though, thanks to abovementioned method overloading). Thus code from HTML_QuickForm
+   <programlisting role="php">
+<![CDATA[
+$form->addElement('header', 'personal', 'Personal Information');
+$form->addGroup(array(
+    HTML_QuickForm::createElement('text', 'first', 'First', 'size=10'),
+    HTML_QuickForm::createElement('text', 'last', 'Last', 'size=10')
+), 'name', 'Name:', ',&nbsp;');
+]]>
+   </programlisting>
+   can be changed to the following in HTML_QuickForm2
+   <programlisting role="php">
+<![CDATA[
+$fieldset = $form->addFieldset('personal')->setLabel('Personal Information');
+$group    = $fieldset->addGroup('name')->setLabel('Name:')->setSeparator(',&nbsp;');
+$group->addText('first', 'size=10', array('label' => 'First'));
+$group->addText('last', 'size=10', array('label' => 'Last'));
+]]>
+   </programlisting>
+  </para>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.qf-migration.defaults">
+  <info>
+   <title>Setting default values</title>
+  </info>
+  <para>
+   Incoming elements' values in HTML_QuickForm2 are kept in an array of DataSources, which are
+   searched for a value in the order they were added to the form. A DataSource containing submit
+   values will be added automatically to that list if the form was submitted. The equivalent to
+   <phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm::setDefaults" /> call
+   <programlisting role="php">
+<![CDATA[
+$form->setDefaults(array(
+    'foo' => 'default foo value',
+    'bar' => 'default bar value'
+));
+]]>
+   </programlisting>
+   is the following call to <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2::addDataSource" />:
+   <programlisting role="php">
+<![CDATA[
+$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'foo' => 'default foo value',
+    'bar' => 'default bar value'
+)));
+]]>
+   </programlisting>
+  </para>
+  <para>
+   It is possible to replace the whole array of form's DataSources using <phd:pearapi
+    phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2::setDataSources" />, so you can
+   change <phd:pearapi phd:package="HTML_QuickForm"
+    phd:linkend="HTML_QuickForm::setConstants" /> call
+   <programlisting role="php">
+<![CDATA[
+$form->setConstants(array(
+    'const' => 'this will override submitted value'
+));
+]]>
+   </programlisting>
+   to
+   <programlisting role="php">
+<![CDATA[
+$datasources = $form->getDataSources();
+array_unshift($datasources, new HTML_QuickForm2_DataSource_Array(array(
+    'const' => 'this will override submitted value'
+)));
+$form->setDataSources($datasources);
+]]>
+   </programlisting>
+   Here we use the fact that new DataSource will be searched before one containing submitted values,
+   so its values will override submitted ones.
+  </para>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.qf-migration.values">
+  <info>
+   <title>Getting the elements's values</title>
+  </info>
+  <para>
+   While HTML_QuickForm contained several methods for getting form's and elements'
+   values, HTML_QuickForm2 only has <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Node::getValue">getValue()</phd:pearapi> and
+   <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Node::getRawValue">getRawValue()</phd:pearapi>, the difference
+   being that the former applies filters to the value and the latter does not. There is no longer a
+   special &quot;submit value&quot; stored separately from form element and returned by
+   <phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm::getSubmitValue" /> /
+   <phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm::getSubmitValues" />.
+  </para>
+  <para>
+   Calling <function>getValue</function> on an element returns the element's submit value or &null;
+   for elements that do not currently have a submit value or can not have such a value at all. The
+   value also passes &quot;intrinsic validation&quot; to make sure that it could possibly originate
+   from that element (e.g. select will only return values for options that <emphasis>were</emphasis>
+   added to select). This behaviour is closest to that of old <phd:pearapi phd:package="HTML_QuickForm"
+    phd:linkend="HTML_QuickForm::exportValue" />.
+  </para>
+  <para>
+   Calling <function>getValue</function> on a <classname>HTML_QuickForm2</classname> object is
+   equivalent to old <phd:pearapi phd:package="HTML_QuickForm"
+    phd:linkend="HTML_QuickForm::exportValues" />.
+  </para>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.qf-migration.filters">
+  <info>
+   <title>Filters</title>
+  </info>
+  <para>
+   Main differences to filters in HTML_QuickForm:
+   <itemizedlist>
+    <listitem><simpara>Filters are added to the element rather than to the form and applied to the
+     element's value rather than a separate &quot;submit value&quot;.</simpara></listitem>
+    <listitem><simpara>Additional arguments can be passed to filter callbacks.</simpara></listitem>
+    <listitem><simpara>There are separate <phd:pearapi phd:package="HTML_QuickForm2"
+      phd:linkend="HTML_QuickForm2_Node::addFilter" /> and <phd:pearapi phd:package="HTML_QuickForm2"
+      phd:linkend="HTML_QuickForm2_Node::addRecursiveFilter" /> methods. The former will be
+     applied directly to element's value on <phd:pearapi phd:package="HTML_QuickForm2"
+      phd:linkend="HTML_QuickForm2_Node::getValue">getValue()</phd:pearapi> call and the latter will
+     be propagated to contained elements if the element is a Container or applied recursively to the
+     value if the element's value is an array.
+    </simpara></listitem>
+   </itemizedlist>
+  </para>
+  <para>
+   The following <phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm::applyFilter"
+    /> calls in HTML_QuickForm
+   <programlisting role="php">
+<![CDATA[
+$form->applyFilter('__ALL__', 'trim');
+$form->applyFilter('amount', 'intval');
+]]>
+   </programlisting>
+   can be converted to the following in HTML_QuickForm2
+   <programlisting role="php">
+<![CDATA[
+$form->addRecursiveFilter('trim');
+$amount->addFilter('intval');
+]]>
+   </programlisting>
+  </para>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.qf-migration.rules">
+  <info>
+   <title>Rules and validation</title>
+  </info>
+  <para>
+   Main differences to HTML_QuickForm:
+   <itemizedlist>
+    <listitem><simpara>Rules are added to the element rather than to the form and applied to the
+     element's value rather than a separate &quot;submit value&quot;.</simpara></listitem>
+    <listitem><simpara>Rules can be chained with <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2_Rule::and_">and_()</phd:pearapi> and <phd:pearapi phd:package="HTML_QuickForm2"
+      phd:linkend="HTML_QuickForm2_Rule::or_">or_()</phd:pearapi> methods allowing for very complex
+     validation scenarios even with builtin Rules.</simpara></listitem>
+   </itemizedlist>
+   Simple <function>addRule</function> call in HTML_QuickForm
+   <programlisting role="php">
+<![CDATA[
+$form->addRule('username', 'Username should be at least 5 symbols long', 'minlength', 5, 'client');
+]]>
+   </programlisting>
+   can be changed to the following in HTML_QuickForm2
+   <programlisting role="php">
+<![CDATA[
+$username->addRule('minlength', 'Username should be at least 5 symbols long', 5,
+                   HTML_QuickForm2_Rule::SERVER | HTML_QuickForm2_Rule::CLIENT);
+]]>
+   </programlisting>
+  </para>
+  <para>
+   There is no longer a special <phd:pearapi phd:package="HTML_QuickForm"
+    phd:linkend="HTML_QuickForm::addGroupRule" /> method. <literal>'nonempty'</literal> /
+   <literal>'required'</literal> Rule can directly validate a group or other Container making sure
+   that it contains a given number of nonempty elements, there is also a special
+   <literal>'each'</literal> Rule that applies a given template Rule to each element in a Container.
+   Thus the following <function>addGroupRule</function> calls
+   <programlisting role="php">
+<![CDATA[
+$form->addGroupRule('phoneNo', 'Please fill all phone fields', 'required', null, 3, 'client');
+$form->addGroupRule('phoneNo', 'Values must be numeric', 'regex', '/^\\d+$/', 3, 'client');
+]]>
+   </programlisting>
+   can be changed to
+   <programlisting role="php">
+<![CDATA[
+$phoneNo->addRule('required', 'Please fill all phone fields', 3,
+                  HTML_QuickForm2_Rule::SERVER | HTML_QuickForm2_Rule::CLIENT);
+$phoneNo->addRule('each', 'Values must be numeric',
+                  $phoneNo->createRule('regex', '', '/^\\d+$/'),
+                  HTML_QuickForm2_Rule::SERVER | HTML_QuickForm2_Rule::CLIENT);
+]]>
+   </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
+   <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.
+  </para>
+  <para>
+   <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Element_InputFile">File
+   elements</phd:pearapi> no longer require special <literal>'uploadedfile'</literal> and
+   <literal>'filename'</literal> rules, standard <literal>'required'</literal> and
+   <literal>'regex'</literal> can be used (client-side as well).
+  </para>
+  <para>
+   There is now a javascript library provided with the package which contains code necessary for
+   client-side validation to run. This library should be included in the page if you intend to use
+   client-side validation.
+  </para>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.qf-migration.outputting">
+  <info>
+   <title>Outputting the form</title>
+  </info>
+  <para>
+   It is quite easy to output the form in HTML_QuickForm2 thanks to a magic
+   <function>__toString</function> method:
+   <programlisting role="php">
+<![CDATA[
+echo $form;
+]]>
+   </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.
+  </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
+     linkend="package.html.html-quickform-renderer-tableless"><classname>HTML_QuickForm_Renderer_Tableless</classname></link>.
+     There is a default CSS file to properly style its output.
+    </simpara></listitem>
+    <listitem><simpara>Template syntax in Default renderer is a bit less verbose.</simpara></listitem>
+    <listitem><simpara>Rules for finding an appropriate template for an element are more
+     complex.</simpara></listitem>
+   </itemizedlist>
+   Consider reviewing the examples 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
+   <programlisting role="php">
+<![CDATA[
+foreach ($form as $element) {
+    echo '<label for="' . $element->getId() . '">' . $element->getLabel()
+         . '</label> ' . $element->__toString() . '<br />';
+}
+]]>
+   </programlisting>
+   but bear in mind that client-side validation rules are built when rendering the form and that
+   Default renderer allows easy output customization.
+  </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. The
+   easiest (but not the most efficient) way to ensure that:
+   <programlisting role="php">
+<![CDATA[
+require_once 'HTML/QuickForm2/Renderer.php';
+
+$renderer = HTML_QuickForm2_Renderer::factory('default');
+// You can customize element templates here
+// $renderer->setTemplateFor...
+$form->render($renderer);
+// This will inline the necessary libraries
+echo $renderer->getJavascriptBuilder()->getLibraries(true, true);
+echo $renderer;
+]]>
+   </programlisting>
+  </para>
+ </refsection>
+</refentry>

Added: pear/peardoc/trunk/en/package/html/html-quickform2.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-quickform2.xml	2011-03-06 15:22:11 UTC (rev 308977)
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<book
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.html.html-quickform2"
+ >
+ <info>
+  <title>HTML_QuickForm2</title>
+  <abstract>
+   <para>
+    <classname>HTML_QuickForm2</classname> is a PHP5 rewrite of <link
+     linkend="package.html.html-quickform"><classname>HTML_QuickForm</classname></link> and <link
+      linkend="package.html.html-quickform-controller"><classname>HTML_QuickForm_Controller</classname></link>
+    packages. It provides methods to create, validate and render HTML forms.
+    <itemizedlist>
+     <listitem><simpara>Supports all form elements defined by HTML standard, provides several
+      custom elements.</simpara></listitem>
+     <listitem><simpara>Server-side and client-side validation, several common rules
+      provided.</simpara></listitem>
+     <listitem><simpara>Multipage forms (tabbed forms and wizards)</simpara></listitem>
+     <listitem><simpara>Pluggable elements, rules, renderers and renderer plugins</simpara></listitem>
+    </itemizedlist>
+   </para>
+   <para>
+    Major advantages over PHP4 versions:
+    <itemizedlist>
+     <listitem><simpara>DOM-like API for building the form structure, new streamlined API for
+      elements' values handling.</simpara></listitem>
+     <listitem><simpara>Default rendering without tables (inspired by <link
+      linkend="package.html.html-quickform-renderer-tableless"><classname>HTML_QuickForm_Renderer_Tableless</classname></link>).
+     </simpara></listitem>
+     <listitem><simpara>Renderer plugins for elements with complex rendering needs.</simpara></listitem>
+     <listitem><simpara>Ability to chain validation rules with 'and' and 'or'</simpara></listitem>
+    </itemizedlist>
+   </para>
+  </abstract>
+ </info>
+ <chapter>
+  &package.html.html-quickform2.qf-migration;
+ </chapter>
+</book>
+

Modified: pear/peardoc/trunk/en/package/html-entities.xml
===================================================================
--- pear/peardoc/trunk/en/package/html-entities.xml	2011-03-06 14:11:42 UTC (rev 308976)
+++ pear/peardoc/trunk/en/package/html-entities.xml	2011-03-06 15:22:11 UTC (rev 308977)
@@ -11,6 +11,7 @@
 &package.html.html-quickform-renderer-tableless;
 &package.html.html-quickform-dhtmlrulestableless;
 &package.html.html-quickform-advmultiselect;
+&package.html.html-quickform2;
 &package.html.html-table;
 &package.html.html-tagcloud;
 &package.html.html-template-flexy;