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

--68c97c55daa48d84176abddea1042fd68215e124
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

avb                                      Wed, 02 May 2012 07:42:15 +0000

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

Log:
Added a section on repeat element indexes

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

Modified: pear/peardoc/trunk/en/package/html/html-quickform2/elements/repeat.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/elements/repeat.xml	2012-05-02 05:24:51 UTC (rev 325499)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/elements/repeat.xml	2012-05-02 07:42:15 UTC (rev 325500)
@@ -161,7 +161,7 @@
   <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
+   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>
@@ -208,4 +208,83 @@
    allowing to use one set of radios or checkboxes for all repeated items.
   </para>
  </refsection>
+
+
+ <refsection xml:id="package.html.html-quickform2.elements.repeat.indexes">
+  <info>
+   <title>Indexes of repeated items</title>
+  </info>
+  <para>
+   As was noted in the above example, indexes for repeated items can be automatically discovered
+   from <link linkend="package.html.html-quickform2.values-datasources.datasources-overview">data
+   sources</link>. The field name to use for discovering indexes can be either set explicitly with
+   <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container_Repeat::setIndexField">setIndexField()</phd:pearapi> or
+   left for the Repeat to choose automatically using names of prototype's child elements. When
+   guessing, it will only consider elements that are expected to always have a submit value, so
+   elements like buttons, checkboxes and multiple selects will not be used.
+  </para>
+  <para>
+   Indexes can be also set manually using <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container_Repeat::setIndexes">setIndexes()</phd:pearapi>, the
+   corresponding <phd:pearapi phd:package="HTML_QuickForm2"
+    phd:linkend="HTML_QuickForm2_Container_Repeat::getIndexes">getIndexes()</phd:pearapi> is also
+   available. Duplicate indexes and those not matching
+   <constant>HTML_QuickForm2_Container_Repeat::INDEX_REGEXP</constant> will be ignored by
+   <function>setIndexes</function>.
+  </para>
+  <example>
+   <info>
+    <title>Working with indexes</title>
+   </info>
+   <programlisting role="php"><![CDATA[
+$form = new HTML_QuickForm2('repeatIndexes');
+$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);
+
+// no element to guess indexes present
+var_dump($repeat->getIndexes());
+
+// explicitly set field to discover indexes
+$repeat->setIndexField('title');
+var_dump($repeat->getIndexes());
+
+// explicit setIndexes() with a few errors
+$repeat->setIndexes(array('foo', 'bar', 'baz', 'qu\'ux', 'baz'));
+var_dump($repeat->getIndexes());
+   ]]></programlisting>
+   <simpara>outputs</simpara>
+   <screen><![CDATA[
+array(0) {
+}
+array(3) {
+  [0]=>
+  int(0)
+  [1]=>
+  int(1)
+  [2]=>
+  string(3) "key"
+}
+array(3) {
+  [0]=>
+  string(3) "foo"
+  [1]=>
+  string(3) "bar"
+  [2]=>
+  string(3) "baz"
+}
+   ]]></screen>
+  </example>
+  <tip>
+   <para>
+    Setting indexes for repeat elements works quite similar to setting values for other elements, so
+    <link linkend="package.html.html-quickform2.values-datasources.order">keeping correct
+     order</link> really helps.
+   </para>
+  </tip>
+ </refsection>
 </refentry>

--68c97c55daa48d84176abddea1042fd68215e124--