svn: /pear/peardoc/trunk/en/package/html/ html-quickform2/elements/list.xml html-quickform2/elements/repeat.xml html-quickform2/examples.xml html-quickform2.xml

avb                                      Wed, 18 Apr 2012 18:02:03 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=325316

Log:
Initial docs for repeat elements

Changed paths:
    U   pear/peardoc/trunk/en/package/html/html-quickform2/elements/list.xml
    A   pear/peardoc/trunk/en/package/html/html-quickform2/elements/repeat.xml
    U   pear/peardoc/trunk/en/package/html/html-quickform2/examples.xml
    U   pear/peardoc/trunk/en/package/html/html-quickform2.xml

---

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/elements/list.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/elements/list.xml 2012-04-18 17:19:45 UTC (rev 325315)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/elements/list.xml 2012-04-18 18:02:03 UTC (rev 325316)
@@ -220,6 +220,13 @@
         section.</link></entry>
      </row>
      <row valign="top">
+      <entry><literal>'repeat'</literal></entry>
+      <entry><phd:pearapi phd:package="HTML_QuickForm2"
+       phd:linkend="HTML_QuickForm2_Container_Repeat"/></entry>
+      <entry>Repeats a given 'prototype' Container multiple times. <link
+       linkend="package.html.html-quickform2.elements.repeat">Described in a separate section.</link></entry>
+     </row>
+     <row valign="top">
       <entry><literal>'script'</literal></entry>
       <entry><phd:pearapi phd:package="HTML_QuickForm2"
        phd:linkend="HTML_QuickForm2_Element_Script"/></entry>

Added: pear/peardoc/trunk/en/package/html/html-quickform2/elements/repeat.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/elements/repeat.xml                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/elements/repeat.xml 2012-04-18 18:02:03 UTC (rev 325316)
@@ -0,0 +1,211 @@
+<?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.elements.repeat"
+ >
+ <refnamediv>
+  <refname>Repeat element</refname>
+  <refpurpose>Repeating a given Container several times</refpurpose>
+ </refnamediv>
+
+ <refsection xml:id="package.html.html-quickform2.elements.repeat.overview">
+  <info>
+   <title>Overview</title>
+  </info>
+  <note>
+   <para>
+    Repeat requires <filename>quickform.js</filename> and
+    <filename>quickform-repeat.js</filename> files being <link
+     linkend="package.html.html-quickform2.javascript.libraries">included in the page</link> to
+    work.
+   </para>
+  </note>
+  <para>
+   <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Container_Repeat" /> is
+   an element that accepts a 'prototype' <link
+    linkend="package.html.html-quickform2.elements.container">Container</link> (a <phd:pearapi
+    phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container_Fieldset">Fieldset</phd:pearapi> or a <link
+    linkend="package.html.html-quickform2.groups">Group</link>, but not another Repeat) and repeats
+   it several times in the form. Repeated items can be dynamically added / removed via Javascript,
+   server-side part automatically understands these changes. Server-side and client-side validation
+   can be easily leveraged: rules added to prototype Container and its children are repeated as
+   well.
+  </para>
+  <tip>
+   <para>
+    <filename>repeat.php</filename> <link
+     linkend="package.html.html-quickform2.examples">example file installed with the package</link>
+    shows how to use repeat elements with Fieldsets and Groups.
+   </para>
+  </tip>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.elements.repeat.elements">
+  <info>
+   <title>Adding elements to Repeat</title>
+  </info>
+  <para>
+   <classname>HTML_QuickForm2_Container_Repeat</classname> has only one immediate child element: a
+   prototype Container, either set using <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container_Repeat::setPrototype">setPrototype()</phd:pearapi> method
+   or passed as <literal>'prototype'</literal> key of <varname>$data</varname> parameter to
+   <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container_Repeat::__construct">Repeat's constructor</phd:pearapi>.
+  </para>
+  <para>
+   <function>appendChild</function>, <function>insertBefore</function>,
+   <function>removeChild</function> are available for Repeat element as usual, but these are proxies
+   for prototype's methods working with its children and will throw exceptions if prototype was not
+   yet set. An exception will also be thrown if you attempt to add another Repeat element to a
+   prototype.
+  </para>
+  <example>
+   <info>
+    <title>Adding elements to Repeat</title>
+   </info>
+   <programlisting role="php"><![CDATA[
+$fieldset = new HTML_QuickForm2_Container_Fieldset();
+$repeat   = new HTML_QuickForm2_Container_Repeat();
+$repeat->setPrototype($fieldset);
+
+echo "repeat: " . count($repeat) . "; fieldset: " . count($fieldset) . "\n";
+
+$repeat->addText('title');
+
+echo "repeat: " . count($repeat) . "; fieldset: " . count($fieldset) . "\n";
+    ]]></programlisting>
+   <simpara>the above code outputs</simpara>
+   <screen><![CDATA[
+repeat: 1; fieldset: 0
+repeat: 1; fieldset: 1
+    ]]></screen>
+  </example>
+ </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.elements.repeat.names">
+  <info>
+   <title>Names of repeated elements</title>
+  </info>
+  <para>
+   As is the case with groups, repeat element will change names of its children, additionally
+   <varname>id</varname> attributes will be changed. Instead of prepending the repeat's name,
+   however, a special "index template" <literal>'[:idx:]'</literal> will be appended to
+   the name and <literal>_:idx:</literal> to the <varname>id</varname>.
+   <literal>':idx:'</literal> string in these will later be replaced by an actual index of the
+   repeated item to produce unique names / <varname>id</varname>s.
+  </para>
+  <example>
+   <info>
+    <title>Default names for repeated elements</title>
+   </info>
+   <programlisting role="php"><![CDATA[
+$form = new HTML_QuickForm2('repeatFieldset');
+$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'title' => array('foo', 'bar', 'key' => 'baz')
+)));
+
+$fieldset = new HTML_QuickForm2_Container_Fieldset();
+$repeat   = $form->addRepeat()->setPrototype($fieldset);
+
+$repeat->addText('title', array('id' => 'title'));
+
+$renderer = $repeat->render(
+    HTML_QuickForm2_Renderer::factory('array')
+);
+
+$array = $renderer->toArray();
+
+foreach ($array['elements'] as $fsArray) {
+    echo $fsArray['attributes'] . "\n";
+    echo "    " . $fsArray['elements'][0]['html'] . "\n";
+}
+   ]]></programlisting>
+   <simpara>outputs</simpara>
+   <screen><![CDATA[
+ id="qfauto-0_:idx:" class="repeatItem repeatPrototype"
+    <input type="text" id="title_:idx:" name="title[:idx:]" />
+ id="qfauto-0_0" class="repeatItem"
+    <input type="text" id="title_0" name="title[0]" value="foo" />
+ id="qfauto-0_1" class="repeatItem"
+    <input type="text" id="title_1" name="title[1]" value="bar" />
+ id="qfauto-0_key" class="repeatItem"
+    <input type="text" id="title_key" name="title[key]" value="baz" />
+   ]]></screen>
+   <para>
+    There are a few things worth noting in this output:
+    <itemizedlist>
+     <listitem><simpara>
+      Keys for repeated items are discovered automatically from data source using the values for the
+      <literal>'title'</literal> field. Sometimes it is better to explicitly set the field to use
+      for discovering indexes using <phd:pearapi phd:package="HTML_QuickForm2"
+       phd:linkend="HTML_QuickForm2_Container_Repeat::setIndexField">setIndexField()</phd:pearapi>.
+     </simpara></listitem>
+     <listitem><simpara>
+      Keys are not required to be numeric, they should however match the
+      <constant>HTML_QuickForm2_Container_Repeat::INDEX_REGEXP</constant> regular expression:
+      <literal>'/^[a-zA-Z0-9_]+$/'</literal>.
+     </simpara></listitem>
+     <listitem><simpara>
+      The output contains an extra item which still has its index templates intact. It should be
+      hidden thanks to <literal>repeatPrototype</literal> CSS class and will be used by Javascript
+      code to add new visible repeated items.
+     </simpara></listitem>
+    </itemizedlist>
+   </para>
+  </example>
+  <para>
+   If you are using a named group as a repeat prototype, you may want to use another name structure:
+   <literal>group[index][element]</literal> instead of <literal>group[element][index]</literal>. It
+   is possible to do so if you manually put <literal>:idx:</literal> into group's name, Repeat will
+   not mangle names further if this string is already present in them.
+  </para>
+  <example>
+   <info>
+    <title>Custom names for repeated elements</title>
+   </info>
+   <programlisting role="php"><![CDATA[
+$form = new HTML_QuickForm2('repeatGroup');
+$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
+    'tags' => array(
+        array('title' => 'foo'),
+        array('title' => 'bar'),
+        'key' => array('title' => 'baz')
+    )
+)));
+
+$group  = new HTML_QuickForm2_Container_Group('tags[:idx:]');
+$repeat = $form->addRepeat()->setPrototype($group);
+
+// custom id as well
+$group->addText('title', array('id' => 'tags-:idx:-title'));
+
+$renderer = $repeat->render(
+    HTML_QuickForm2_Renderer::factory('array')
+);
+
+$array = $renderer->toArray();
+
+foreach ($array['elements'] as $groupArray) {
+    echo $groupArray['elements'][0]['html'] . "\n";
+}
+   ]]></programlisting>
+   <simpara>outputs</simpara>
+   <screen><![CDATA[
+<input type="text" id="tags-:idx:-title" name="tags[:idx:][title]" />
+<input type="text" id="tags-0-title" name="tags[0][title]" value="foo" />
+<input type="text" id="tags-1-title" name="tags[1][title]" value="bar" />
+<input type="text" id="tags-key-title" name="tags[key][title]" value="baz" />
+   ]]></screen>
+  </example>
+  <para>
+   For radios and checkboxes it is also possible to put <literal>:idx:</literal> into
+   <varname>value</varname> attribute, this way their names will not be changed, essentially
+   allowing to use one set of radios or checkboxes for all repeated items.
+  </para>
+ </refsection>
+</refentry>

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/examples.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/examples.xml 2012-04-18 17:19:45 UTC (rev 325315)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/examples.xml 2012-04-18 18:02:03 UTC (rev 325316)
@@ -59,6 +59,13 @@
     </para></listitem>
    </varlistentry>
    <varlistentry>
+    <term><filename>repeat.php</filename></term>
+    <listitem><para>
+     Demonstrates the <link linkend="package.html.html-quickform2.elements.repeat.overview">Repeat
+      element</link>.
+    </para></listitem>
+   </varlistentry>
+   <varlistentry>
     <term><filename>controller/simple.php</filename></term>
     <listitem><para>
      Single-page form taking advantage of <classname>HTML_QuickForm2_Controller</classname>

Modified: pear/peardoc/trunk/en/package/html/html-quickform2.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2.xml 2012-04-18 17:19:45 UTC (rev 325315)
+++ pear/peardoc/trunk/en/package/html/html-quickform2.xml 2012-04-18 18:02:03 UTC (rev 325316)
@@ -49,11 +49,12 @@
    <title>Introduction</title>
   </info>
   <para>
-   This section is intended for those completely unfamiliar with
+   This chapter is intended both for those completely unfamiliar with
    <classname>HTML_QuickForm2</classname> and for users of PHP4 version of <link
     linkend="package.html.html-quickform"><package>HTML_QuickForm</package></link> who need either
-   an overview of package features or tips for migrating their scripts. The section also includes an
-   description of longer and more complex examples installed with the package.
+   an overview of package features or tips for migrating their scripts. The chapter also includes
+   a list of examples installed with the package: those are longer and more complex than examples
+   within documentation.
   </para>
   &package.html.html-quickform2.tutorial;
   &package.html.html-quickform2.qf-migration;
@@ -64,12 +65,17 @@
   <info>
    <title>Form elements</title>
   </info>
+  <para>
+   This chapter lists all element classes available in <package>HTML_QuickForm2</package> and
+   describes their base and element-specific API.
+  </para>
   &package.html.html-quickform2.elements.base;
   &package.html.html-quickform2.elements.container;
   &package.html.html-quickform2.elements.form;
   &package.html.html-quickform2.elements.list;
   &package.html.html-quickform2.groups;
   &package.html.html-quickform2.elements.custom;
+  &package.html.html-quickform2.elements.repeat;
   &package.html.html-quickform2.elements.message-provider;
  </chapter>

---

--
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php