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

Added: pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml	2011-03-06 19:30:28 UTC (rev 308978)
@@ -0,0 +1,226 @@
+<?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.tutorial"
+>
+ <refnamediv>
+  <refname>QuickForm2 Tutorial</refname>
+  <refpurpose>Description of basic package features</refpurpose>
+ </refnamediv>
+ <refsection xml:id="package.html.html-quickform2.tutorial.overview">
+  <info>
+   <title>Overview</title>
+  </info>
+  <para>
+   The purpose of this tutorial is to give users unfamiliar with
+   <classname>HTML_QuickForm2</classname> a basic understanding of package features. It describes
+   the most common functionality and points to the parts of documentation that describe the package
+   features in more depth.
+  </para>
+  <para>
+   If you are already familiar with PHP4 version of <link
+    linkend="package.html.html-quickform"><classname>HTML_QuickForm</classname></link>, you can go
+   directly to <link linkend="package.html.html-quickform2.qf-migration">migration guide</link>
+   which contains step-by-step instructions for porting your scripts to
+   <classname>HTML_QuickForm2</classname>.
+  </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.tutorial.example">
+  <info>
+   <title>Your first QuickForm2-based form</title>
+  </info>
+  <example>
+   <info>
+    <title>Builds and processes a form with a single input field</title>
+   </info>
+   <programlisting role="php">
+<![CDATA[
+// Load the main class
+require_once 'HTML/QuickForm2.php';
+
+// Instantiate the HTML_QuickForm object
+$form = new HTML_QuickForm2('tutorial');
+
+// Set defaults for the form elements
+$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'name' => 'Joe User'
+)));
+
+// Add some elements to the form
+$fieldset = $form->addElement('fieldset')->setLabel('QuickForm2 tutorial example');
+$name = $fieldset->addElement('text', 'name', array('size' => 50, 'maxlength' => 255))
+                 ->setLabel('Enter your name:');
+$fieldset->addElement('submit', null, array('value' => 'Send!'));
+
+// Define filters and validation rules
+$name->addFilter('trim');
+$name->addRule('required', 'Please enter your name');
+
+// Try to validate a form
+if ($form->validate()) {
+    echo '<h1>Hello, ' . htmlspecialchars($name->getValue()) . '!</h1>';
+    exit;
+}
+
+// Output the form
+echo $form;
+]]>
+   </programlisting>
+  </example>
+  <para>
+    Lets review the above example step by step.
+  </para>
+
+
+  <refsection xml:id="package.html.html-quickform2.tutorial.example.building">
+   <info>
+    <title>Building the form</title>
+   </info>
+   <para>
+    The line
+    <programlisting role="php">
+<![CDATA[
+$form = new HTML_QuickForm2('tutorial');
+]]>
+    </programlisting>
+    creates an instance of <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2"
+     /> that will contain objects representing form elements and other necessary information.
+    We only pass the form's id to the <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2::__construct">constructor</phd:pearapi>, which means that default
+    values will be used for other parameters. In particular, the form's method will default to
+    <literal>POST</literal> and the form's action to the current file. When using QuickForm2, it is
+    easier to keep all the form related logic in one file.
+   </para>
+   <para>
+    Next we add a DataSource
+    <programlisting role="php">
+<![CDATA[
+$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'name' => 'Joe User'
+)));
+]]>
+    </programlisting>
+    containing the default value <literal>'Joe User'</literal> for <literal>name</literal> element.
+    DataSources are objects that provide elements' incoming values, they are searched in the order
+    they were added to the form. When constructor of <classname>HTML_QuickForm2</classname>
+    considers the form submitted, it will automatically add a DataSource with submit values, so
+    search will not reach the DataSource added above. However, when submit DataSource is not there,
+    default value will be taken from the above DataSource.
+   </para>
+   <para>
+    To improve the presentation, we are adding a fieldset element to the form first:
+    <programlisting role="php">
+<![CDATA[
+$fieldset = $form->addElement('fieldset')->setLabel('QuickForm2 tutorial example');
+]]>
+    </programlisting>
+    and set its label (it will be output as <literal>&lt;legend&gt;</literal>, actually).
+   </para>
+   <para>
+    We then add a text input box and a submit button to the fieldset:
+    <programlisting role="php">
+<![CDATA[
+$name = $fieldset->addElement('text', 'name', array('size' => 50, 'maxlength' => 255))
+                 ->setLabel('Enter your name:');
+$fieldset->addElement('submit', null, array('value' => 'Send!'));
+]]>
+    </programlisting>
+    Note that most of the methods are returning <parameter>$this</parameter>, so it is possible to
+    chain method calls. Note also that we can arbitrarily nest fieldsets and other containers (you
+    can't nest another <classname>HTML_QuickForm2</classname> instance, however).
+   </para>
+  </refsection>
+
+
+  <refsection xml:id="package.html.html-quickform2.tutorial.example.checking">
+   <info>
+    <title>Checking input</title>
+   </info>
+   <para>
+    The line
+    <programlisting role="php">
+<![CDATA[
+$name->addFilter('trim');
+]]>
+    </programlisting>
+    adds a filter for the element's value - the function that will be applied to it when
+    <phd:pearapi phd:package="HTML_QuickForm2"
+     phd:linkend="HTML_QuickForm2_Node::getValue">getValue()</phd:pearapi> is called.
+    In this case it is a builtin <link xmlns:xlink="http://www.w3.org/1999/xlink"
+     xlink:href="&url.php.lookup;trim"><function>trim</function></link> function,
+    but can be any valid <link xmlns:xlink="http://www.w3.org/1999/xlink"
+     xlink:href="&url.php.callback;"><type>callback</type></link>. Thus we will strip
+    all leading and trailing whitespace from the name, as we do not need it and as we want to be
+    sure that a name was entered, not just some spaces.
+   </para>
+   <para>
+    Next we define a rule for the field:
+    <programlisting role="php">
+<![CDATA[
+$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.
+   </para>
+  </refsection>
+
+
+  <refsection xml:id="package.html.html-quickform2.tutorial.example.processing">
+   <info>
+    <title>Validating and processing</title>
+   </info>
+   <para>
+    We now have the form built and rules defined and need to decide whether to process it or display:
+    <programlisting role="php">
+<![CDATA[
+if ($form->validate()) {
+    // Do some stuff
+}
+]]>
+    </programlisting>
+    <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2::validate" /> method
+    will consider the form valid (i.e. return &true;) if some data was actually submitted and all
+    the rules defined for the form were satisfied. In our case this means that
+    <literal>'name'</literal> element was not left empty.
+   </para>
+   <para>
+    If the form is validated we need to process the values
+    <programlisting role="php">
+<![CDATA[
+echo '<h1>Hello, ' . htmlspecialchars($name->getValue()) . '!</h1>';
+exit;
+]]>
+    </programlisting>
+    This is an example, in your scripts you'll usually want to store the values somewhere and to
+    redirect to some other page to prevent a duplicate submit.
+   </para>
+   <para>
+    The last line is pretty easy:
+    <programlisting role="php">
+<![CDATA[
+echo $form;
+]]>
+    </programlisting>
+    If the form is not valid, which means that it either was not yet submitted or that there were errors, it
+    will be displayed. Error messages (if any) will be displayed near the corresponding elements.
+   </para>
+  </refsection>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.tutorial.further">
+  <info>
+   <title>Further usage examples</title>
+  </info>
+  <para>
+   More complex usage examples are installed with the package, they show built-in elements, rules,
+   means to customize form output. Examples are installed to directory <filename
+    role="dir">HTML_QuickForm2/examples</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>

Modified: pear/peardoc/trunk/en/package/html/html-quickform2.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2.xml	2011-03-06 15:22:11 UTC (rev 308977)
+++ pear/peardoc/trunk/en/package/html/html-quickform2.xml	2011-03-06 19:30:28 UTC (rev 308978)
@@ -37,6 +37,7 @@
   </abstract>
  </info>
  <chapter>
+  &package.html.html-quickform2.tutorial;
   &package.html.html-quickform2.qf-migration;
  </chapter>
 </book>