svn: /pear/peardoc/trunk/en/package/html/ html-quickform2/qf-migration.xml html-quickform2/tutorial.xml html-quickform2/values-datasources.xml html-quickform2.xml

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml	2011-03-08 19:27:22 UTC (rev 309033)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml	2011-03-08 19:33:52 UTC (rev 309034)
@@ -7,7 +7,7 @@
 >
  <refnamediv>
   <refname>Migration from HTML_QuickForm</refname>
-  <refpurpose>Step-by-step guide for porting your scripts</refpurpose>
+  <refpurpose>Step-by-step guide for porting your scripts to HTML_QuickForm2</refpurpose>
  </refnamediv>
  <refsection xml:id="package.html.html-quickform2.qf-migration.overview">
   <info>
@@ -31,16 +31,16 @@
    <variablelist>
     <varlistentry>
      <term>&type.string; <parameter>$name</parameter></term>
-     <listitem><simpara>Element name</simpara></listitem>
+     <listitem><para>Element name</para></listitem>
     </varlistentry>
     <varlistentry>
      <term>&type.string;|&type.array; <parameter>$attributes</parameter></term>
-     <listitem><simpara>HTML attributes</simpara></listitem>
+     <listitem><para>HTML attributes</para></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>
+     <listitem><para>Additional element-specific data. A <literal>'label'</literal> key in this
+      array is understood by every element and is used for element's label.</para></listitem>
     </varlistentry>
    </variablelist>
    Consequently <phd:pearapi phd:package="HTML_QuickForm2"
@@ -151,10 +151,11 @@
    <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
+   Elements' incoming values in HTML_QuickForm2 are kept in an array of <link
+    linkend="package.html.html-quickform2.values-datasources.datasources-overview">DataSources</link>,
+   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(
@@ -204,7 +205,7 @@

  <refsection xml:id="package.html.html-quickform2.qf-migration.values">
   <info>
-   <title>Getting the elements's values</title>
+   <title>Getting the elements' values</title>
   </info>
   <para>
    While HTML_QuickForm contained several methods for getting form's and elements'
@@ -218,12 +219,13 @@
    <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" />.
+   Calling <function>getValue</function> on an element returns <link
+    linkend="package.html.html-quickform2.values-datasources.values-overview">the element's submit
+    value</link> 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
@@ -381,8 +383,8 @@
     <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.
+   Consider <link linkend="package.html.html-quickform2.tutorial.further">reviewing the
+    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

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml	2011-03-08 19:27:22 UTC (rev 309033)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml	2011-03-08 19:33:52 UTC (rev 309034)
@@ -41,7 +41,7 @@
 // Load the main class
 require_once 'HTML/QuickForm2.php';

-// Instantiate the HTML_QuickForm object
+// Instantiate the HTML_QuickForm2 object
 $form = new HTML_QuickForm2('tutorial');

 // Set defaults for the form elements
@@ -95,7 +95,8 @@
     easier to keep all the form related logic in one file.
    </para>
    <para>
-    Next we add a DataSource
+    Next we add a <link
+     linkend="package.html.html-quickform2.values-datasources.datasources-overview">DataSource</link>
     <programlisting role="php">
 <![CDATA[
 $form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
@@ -163,8 +164,8 @@
 $name->addRule('required', 'Please enter your name');
 ]]>
     </programlisting>
-    This means that QuickForm will display an error message if the name was not entered. Note also
-    that QuickForm will automatically mark required fields in the form.
+    This means that QuickForm2 will display an error message if the name was not entered. Note also
+    that QuickForm2 will automatically mark required fields in the form.
    </para>
   </refsection>

@@ -188,7 +189,8 @@
     <literal>'name'</literal> element was not left empty.
    </para>
    <para>
-    If the form is validated we need to process the values
+    If the form is validated we need to process <link
+     linkend="package.html.html-quickform2.values-datasources.values-overview">the values</link>
     <programlisting role="php">
 <![CDATA[
 echo '<h1>Hello, ' . htmlspecialchars($name->getValue()) . '!</h1>';

Added: pear/peardoc/trunk/en/package/html/html-quickform2/values-datasources.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/values-datasources.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/values-datasources.xml	2011-03-08 19:33:52 UTC (rev 309034)
@@ -0,0 +1,233 @@
+<?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.values-datasources"
+>
+ <refnamediv>
+  <refname>Element values and Data sources</refname>
+  <refpurpose>Setting and getting values for the whole form and for individual elements</refpurpose>
+ </refnamediv>
+
+ <refsection xml:id="package.html.html-quickform2.values-datasources.values-overview">
+  <info>
+   <title>Individual elements' values</title>
+  </info>
+  <para>
+   Each element in HTML_QuickForm2 implements <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Node::getRawValue">getRawValue()</phd:pearapi> and <phd:pearapi
+    phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Node::getValue">getValue()</phd:pearapi> methods that
+   return its filtered and unfiltered submit value, respectively, and <phd:pearapi
+    phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Node::setValue">setValue()</phd:pearapi> that sets the element's
+   display value. These are not always the same, consider
+   <programlisting role="php">
+<![CDATA[
+$text = new HTML_QuickForm2_Element_InputText(
+    'testText', array('disabled' => 'disabled')
+);
+$text->setValue('a value');
+echo $text . "\n";
+var_dump($text->getValue());
+]]>
+   </programlisting>
+   which produces
+   <screen>
+<![CDATA[
+<input type="text" disabled="disabled" name="testText" id="testText-0" value="a value" />
+NULL
+]]>
+   </screen>
+   as disabled elements cannot have a submit value.
+  </para>
+  <para>
+   If an element can not have a submit value (e.g. reset button, static element) or does not
+   currently have one (e.g. disabled element, unchecked checkbox) then <function>getValue</function>
+   will return &null;. The value also passes &quot;intrinsic validation&quot; which ensures that it
+   could possibly come from that element:
+   <programlisting role="php">
+<![CDATA[
+$select = HTML_QuickForm2_Factory::createElement('select', 'testSelect',
+                                                 array('multiple' => 'multiple'))
+              ->loadOptions(array('a' => 'letter A', 'b' => 'letter B', 'c' => 'letter C'));
+$select->setValue(array('a', 'z'));
+// select will only return values for options that were present in it
+var_dump($select->getValue());
+]]>
+   </programlisting>
+   will output
+   <screen>
+<![CDATA[
+array(1) {
+  [0]=>
+  string(1) "a"
+}
+]]>
+   </screen>
+  </para>
+  <para>
+   On the other hand, some of the elements cannot have a display value (<literal>&lt;input
+   type=&quot;image&quot; /&gt;</literal>, file uploads), <function>setValue</function> will be a
+   no-op for such elements and they will only get their values (click coordinates and file upload
+   data, respectively) from submit data sources.
+  </para>
+  <para>
+   <function>getValue</function> / <function>getRawValue</function> also work for
+   <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container">Containers</phd:pearapi> and return an array with values
+   of contained elements. <function>setValue</function> is only implemented for groups, data sources
+   should be used to set the values for the whole form.
+  </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.values-datasources.datasources-overview">
+  <info>
+   <title>Data sources overview</title>
+  </info>
+  <para>
+   Instance of <classname>HTML_QuickForm2</classname> contains an array of Data sources - objects
+   storing elements' incoming values. These values may either originate from HTTP request data
+   (submit values) or be provided by the programmer (default values). Data sources implement
+   <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_DataSource" /> interface
+   defining a single <function>getValue</function> method, which receives element name and returns
+   either element value or &null; if such value is not present.
+  </para>
+  <para>
+   There is also a <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_DataSource_Submit" /> interface that defines an additional
+   <function>getUpload</function> method that receives file upload name and returns either file
+   upload data from <varname>$_FILES</varname> array or &null; if it doesn't contain this data.
+  </para>
+  <para>
+   A data source containing submit values will be added to the list automatically if <phd:pearapi
+    phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2::__construct">constructor</phd:pearapi> of
+   <classname>HTML_QuickForm2</classname> considers the form submitted. You can add another data
+   source to the list using <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2::addDataSource" /> and completely replace the list using
+   <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2::setDataSources" />.
+  </para>
+  <para>
+   An element will try to update its value from data sources in the following cases:
+   <itemizedlist>
+    <listitem><simpara>It is added to the form;</simpara></listitem>
+    <listitem><simpara>Its name is changed;</simpara></listitem>
+    <listitem><simpara>Form data sources list is changed.</simpara></listitem>
+   </itemizedlist>
+   To perform that update it gets the data sources array from the form and iterates over it calling
+   <function>getValue</function> until a non-&null; value is returned. This value is then used as
+   element's value.
+  </para>
+  <para>
+   Some of the elements (submit buttons, obviously file uploads) will only consider getting their
+   values from instances of <interfacename>HTML_QuickForm2_DataSource_Submit</interfacename>. Some
+   (e.g. checkboxes) will stop iterating over the array as soon as an instance of
+   <interfacename>HTML_QuickForm2_DataSource_Submit</interfacename> is found, even if its
+   <function>getValue</function> method returns &null;. Static elements will only consider a
+   datasource if it is <emphasis>not</emphasis> an instance of
+   <interfacename>HTML_QuickForm2_DataSource_Submit</interfacename>.
+  </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.values-datasources.datasources-implementation">
+  <info>
+   <title>Implementations of <interfacename>HTML_QuickForm2_DataSource</interfacename></title>
+  </info>
+  <para>
+   The package contains several classes implementing the
+   <interfacename>HTML_QuickForm2_DataSource</interfacename> interface, but the only one that should
+   be used directly is <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_DataSource_Array" />, other classes are used internally by the
+   package.
+  </para>
+  <para>
+   An instance of <classname>HTML_QuickForm2_DataSource_Array</classname> wraps around an array
+   with a structure similar to that of superglobal <varname>$_GET</varname> /
+   <varname>$_POST</varname> arrays. This wrapper allows searching for values of elements with
+   complex names:
+   <programlisting role="php">
+<![CDATA[
+$ds = new HTML_QuickForm2_DataSource_Array(array(
+    'foo' => 'foo value',
+    'bar' => array('bar 1', 'bar 2'),
+    'baz' => array('first' => array('second' => 'found a value'))
+));
+echo $ds->getValue('foo') . "\n";
+echo $ds->getValue('bar[1]') . "\n";
+echo $ds->getValue('baz[first][second]');
+]]>
+   </programlisting>
+   outputs
+   <screen>
+<![CDATA[
+foo value
+bar 2
+found a value
+]]>
+   </screen>
+  </para>
+  <para>
+   Instead of loading data from a database unconditionally and passing it to this data source in
+   an array, it may make sense to create your own data source implementation, which will only
+   perform a query when asked for a value. This way you will probably save a query on form submit,
+   as all values will be found in a submit data source.
+  </para>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.values-datasources.order">
+  <info>
+   <title>Maintaining correct order</title>
+  </info>
+  <para>
+   A most popular value-related error happens when a programmer uses an element's
+   <function>setValue</function> method before adding that element to the form:
+   <programlisting role="php">
+<![CDATA[
+$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'testDefault' => 'duh!'
+)));
+$element = HTML_QuickForm2_Factory::createElement('text', 'testDefault')
+               ->setValue('my carefully prepared value');
+$form->appendChild($element);
+echo $element->getValue();
+]]>
+   </programlisting>
+   As described above, the element will immediately try to update its value from form's data sources
+   and overwrite whatever was set on the previous step, so the above results in
+   <screen>
+<![CDATA[
+duh!
+]]>
+   </screen>
+  </para>
+  <para>
+   A less obvious problem is adding data sources after elements:
+   <programlisting role="php">
+<![CDATA[
+// an element updates its value from existing (e.g. submit) data sources
+$form->addElement('text', 'testDefault');
+// it updates its value again
+$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'testDefault' => 'my carefully prepared value'
+)));
+// ...and yet again
+$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'unrelated' => 'a completely unrelated value'
+)));
+]]>
+   </programlisting>
+   That code behaves as expected, but performs lots of unneeded work.
+  </para>
+  <para>
+   To sum it up, a correct order is:
+   <orderedlist>
+    <listitem><simpara>Add all data sources to the form;</simpara></listitem>
+    <listitem><simpara>Add all elements to the form;</simpara></listitem>
+    <listitem><simpara>Call <function>setValue</function> on some elements, if still needed.</simpara></listitem>
+   </orderedlist>
+  </para>
+ </refsection>
+</refentry>

Modified: pear/peardoc/trunk/en/package/html/html-quickform2.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2.xml	2011-03-08 19:27:22 UTC (rev 309033)
+++ pear/peardoc/trunk/en/package/html/html-quickform2.xml	2011-03-08 19:33:52 UTC (rev 309034)
@@ -39,6 +39,7 @@
  <chapter>
   &package.html.html-quickform2.tutorial;
   &package.html.html-quickform2.qf-migration;
+  &package.html.html-quickform2.values-datasources;
  </chapter>
 </book>