cvs: smarty /docs/en/designers/language-builtin-functions language-function-foreach.xml

http://cvs.php.net/viewvc.cgi/smarty/docs/en/designers/language-builtin-functions/language-function-foreach.xml?r1=1.8&r2=1.9&diff_format=u
Index: smarty/docs/en/designers/language-builtin-functions/language-function-foreach.xml
diff -u smarty/docs/en/designers/language-builtin-functions/language-function-foreach.xml:1.8 smarty/docs/en/designers/language-builtin-functions/language-function-foreach.xml:1.9
--- smarty/docs/en/designers/language-builtin-functions/language-function-foreach.xml:1.8	Tue Sep 13 18:41:44 2005
+++ smarty/docs/en/designers/language-builtin-functions/language-function-foreach.xml	Mon Sep 25 18:39:31 2006
@@ -1,29 +1,20 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <sect1 id="language.function.foreach">
  <title>{foreach},{foreachelse}</title>
   <para>
-   <emphasis>{foreach}</emphasis> loops are an alternative to
-   <link
-    linkend="language.function.section"><emphasis>{section}</emphasis></link>
-   loops. <emphasis>{foreach}</emphasis> is used to loop over a
-   <emphasis role="bold">single associative array</emphasis>. The syntax for
-   <emphasis>{foreach}</emphasis> is much easier than
-   <emphasis>{section}</emphasis>, but as a tradeoff it
-   <emphasis role="bold">can only be used
-   for a single array</emphasis>. <emphasis>{foreach}</emphasis> tags must be
-   paired with <emphasis>{/foreach}</emphasis> tags. Required parameters
-   are <emphasis>from</emphasis> and <emphasis>item</emphasis>. The
-   name of the {foreach} loop can be anything you like, made up of
-   letters, numbers and underscores. <emphasis>{foreach}</emphasis>
-   loops can be nested, and the nested {foreach} names must be unique
-   from each other. The <emphasis>from</emphasis> variable (usually an
-   array of values) determines the number of times
-   <emphasis>{foreach}</emphasis> will loop.
-   <emphasis>{foreachelse}</emphasis> is executed when there are no
-   values in the <emphasis>from</emphasis> variable.
- </para>
- 
+  <varname>{foreach}</varname> is used to loop over a
+   <emphasis role="bold">single associative array</emphasis>,
+   unlike <link linkend="language.function.section"><varname>{section}</varname></link>
+  which is for looping over <emphasis role="bold">arrays of data</emphasis>.
+  The syntax for
+   <varname>{foreach}</varname> is much easier than
+   <link linkend="language.function.section"><varname>{section}</varname></link>,
+   but as a tradeoff it <emphasis role="bold">can only be used
+   for a single array</emphasis>. Every <varname>{foreach}</varname> tag must be
+   paired with a closing <varname>{/foreach}</varname> tag.
+   </para>
+
  <informaltable frame="all">
   <tgroup cols="5">
    <colspec colname="param" align="center" />
@@ -75,22 +66,116 @@
   </tgroup>
  </informaltable>
 
+
+   <itemizedlist>
+   <listitem><para>
+   Required attributes are <parameter>from</parameter> and <parameter>item</parameter>.
+   </para></listitem>
+
+   <listitem><para>
+   The <parameter>name</parameter> of the <varname>{foreach}</varname> loop can be anything
+   you like, made up of letters, numbers and underscores, like
+    <ulink url="&url.php-manual;language.variables">PHP variables</ulink>.
+   </para></listitem>
+
+   <listitem><para>
+   <varname>{foreach}</varname> loops can be nested, and the nested
+   <varname>{foreach}</varname> names MUST be unique from each other.
+   </para></listitem>
+
+   <listitem><para>
+   The <parameter>from</parameter> attribute, usually an array of values,
+   determines the number of times <varname>{foreach}</varname> will loop.
+   </para></listitem>
+
+   <listitem><para>
+   <varname>{foreachelse}</varname> is executed when there are no
+   values in the <parameter>from</parameter> variable.
+   </para></listitem>
+
+  <listitem><para>
+	  <varname>{foreach}</varname> loops also have their own variables that handle properties.
+	  These are accessible as:
+	  <link linkend="language.variables.smarty.loops">
+	  <parameter>{$smarty.foreach.name.property}</parameter></link> with
+	  <quote>name</quote> being the  <parameter>name</parameter> attribute.
+	 </para>
+	 <note>
+	 <title>Note</title>
+	 <para>The <parameter>name</parameter> attribute is only required when
+	 you want to access a <varname>{foreach</varname>} property, unlike
+	 <link linkend="language.function.section"><varname>{section}</varname></link>.
+	 Accessing a <varname>{foreach}</varname> property with <parameter>name</parameter>
+	 undefined does not throw an error, but leads to unpredictable results instead.
+	 </para>
+	 </note>
+  </listitem>
+
+  <listitem><para>
+	<varname>{foreach}</varname> properties are
+	<link linkend="foreach.property.index"><parameter>index</parameter></link>,
+	<link linkend="foreach.property.iteration"><parameter>iteration</parameter></link>,
+	<link linkend="foreach.property.first"><parameter>first</parameter></link>,
+	<link linkend="foreach.property.last"><parameter>last</parameter></link>,
+	<link linkend="foreach.property.show"><parameter>show</parameter></link>,
+	<link linkend="foreach.property.total"><parameter>total</parameter></link>.
+	</para></listitem>
+
+	</itemizedlist>
+
  <example>
-  <title>{foreach} - item</title>
+  <title>The <parameter>item</parameter> attribute</title>
+  <programlisting role="php">
+<![CDATA[
+<?php
+$arr = array(1000, 1001, 1002);
+$smarty->assign('myArray', $arr);
+?>
+]]>
+  </programlisting>
+   <para>Template to output <parameter>$myArray</parameter> in an un-ordered list</para>
+  <programlisting>
+<![CDATA[
+<ul>
+{foreach from=$myArray item=foo}
+    <li>{$foo}</li>
+{/foreach}
+</ul>
+]]>
+  </programlisting>
+  <para>
+   The above example will output:
+  </para>
+  <screen>
+<![CDATA[
+<ul>
+    <li>1000</li>
+    <li>1001</li>
+    <li>1002</li>
+</ul>
+]]>
+  </screen>
+ </example>
+
+<example>
+  <title>Demonstrates the <parameter>item</parameter> and <parameter>key</parameter> attributes</title>
   <programlisting role="php">
 <![CDATA[
 <?php
-$arr = array( 1001,1002,1003);
-$smarty->assign('custid', $arr);
+$arr = array(9 => 'Tennis', 3 => 'Swimming', 8 => 'Coding');
+$smarty->assign('myArray', $arr);
 ?>
 ]]>
   </programlisting>
+   <para>Template to output <parameter>$myArray</parameter> as key/val pair,
+   like PHP's <ulink url="&url.php-manual;foreach">foreach</ulink>.</para>
   <programlisting>
 <![CDATA[
-{* this example will print out all the values of the $custid array *}
-{foreach from=$custid item=curr_id}
-  id: {$curr_id}<br />
+<ul>
+{foreach from=$myArray key=k item=v}
+   <li>{$k}: {$v}</li>
 {/foreach}
+</ul>
 ]]>
   </programlisting>
   <para>
@@ -98,19 +183,57 @@
   </para>
   <screen>
 <![CDATA[
-id: 1000<br />
-id: 1001<br />
-id: 1002<br />
+<ul>
+    <li>9: Tennis</li>
+    <li>3: Swimming</li>
+    <li>8: Coding</li>
+</ul>
 ]]>
   </screen>
  </example>
 
+
  <example>
-  <title>{foreach} - item and key</title>
+  <title>{foreach} with associative <parameter>item</parameter> attribute</title>
+  <programlisting role="php">
+<![CDATA[
+<?php
+$items_list = array(23 => array('no' => 2456, 'label' => 'Salad'),
+			        96 => array('no' => 4889, 'label' => 'Cream')
+			        );
+$smarty->assign('items', $items_list);
+?>
+]]>
+  </programlisting>
+   <para>Template to output <parameter>$items</parameter> with
+   <parameter>$myId</parameter> in the url</para>
+  <programlisting>
+<![CDATA[
+<ul>
+{foreach from=$items key=myId item=i}
+  <li><a href="item.php?id={$myId}">{$i.no}: {$i.label}</li>
+{/foreach}
+</ul>
+]]>
+  </programlisting>
+  <para>
+   The above example will output:
+  </para>
+  <screen>
+<![CDATA[
+<ul>
+  <li><a href="item.php?id=23">2456: Salad</li>
+  <li><a href="item.php?id=96">4889: Cream</li>
+</ul>
+]]>
+  </screen>
+ </example>
+
+ <example>
+  <title>{foreach} with nested <parameter>item</parameter> and <parameter>key</parameter></title>
+  <para>Assign an array to Smarty, the key contains the key for each looped value.</para>
   <programlisting role="php">
 <![CDATA[
-// The key contains the key for each looped value
-// assignment looks like this:
 <?php
  $smarty->assign('contacts', array(
                              array('phone' => '1',
@@ -123,6 +246,7 @@
 ?>
 ]]>
   </programlisting>
+  <para>The template to output <parameter>$contact</parameter>.</para>
   <programlisting>
 <![CDATA[
 {foreach name=outer item=contact from=$contacts}
@@ -151,78 +275,155 @@
  </example>
 
  <example>
-  <title>{foreach} - database example (eg PEAR or ADODB)</title>
+  <title>Database example with {foreachelse}</title>
+  <para>A database (eg PEAR or ADODB) example of a search script, the query results assigned to Smarty</para>
 <programlisting role="php">
 <![CDATA[
 <?php
-  $sql = 'select contact_id, name, nick from contacts order by contact';
-  $smarty->assign("contacts", $db->getAssoc($sql));
+  $search_condition = "where name like '$foo%' ";
+  $sql = 'select contact_id, name, nick from contacts '.$search_condition.' order by name';
+  $smarty->assign('results', $db->getAssoc($sql) );
 ?>
 ]]>
   </programlisting>
+  <para>The template which display <quote>None found</quote>
+  if no results with <varname>{foreachelse}</varname>.</para>
   <programlisting>
 <![CDATA[
-{foreach key=cid item=con from=$contacts}
-  <a href="contact.php?contact_id={$cid}">{$con.name} - {$con.nick}</a><br />
+{foreach key=cid item=con from=$results}
+    <a href="contact.php?contact_id={$cid}">{$con.name} - {$con.nick}</a><br />
+{foreachelse}
+    No items were found in the search
 {/foreach}
 ]]>
   </programlisting>
-
  </example>
 
- <para>
-  {foreach} loops also have their own variables that handle {foreach} properties.
-  These are indicated like so:
-  <link linkend="language.variables.smarty.loops">{$smarty.foreach.foreachname.varname}</link>
-  with
-  foreachname being the name specified as the <emphasis>name</emphasis>
-  attribute of foreach
- </para>
-
- <para>See <link linkend="section.property.index">{section}</link>
- for examples of the properties below as they are identical
- </para>
+
+ <sect2 id="foreach.property.index">
+  <title>.index</title>
+  <para>
+   <parameter>index</parameter> contains the current array index, starting with zero.
+  </para>
+  <example>
+  <title><parameter>index</parameter> example</title>
+
+<programlisting role="php">
+<![CDATA[
+{* The header block is output every five rows *}
+<table>
+{foreach from=$items key=myId item=i name=foo}
+  {if $smarty.foreach.foo.index % 5 == 0}
+     <tr><th>Title</th></tr>
+  {/if}
+  <tr><td>{$i.label}</td></tr>
+{/foreach}
+</table>
+]]>
+  </programlisting>
+  </example>
+  </sect2>
 
  <sect2 id="foreach.property.iteration">
-  <title>iteration</title>
+  <title>.iteration</title>
   <para>
-   iteration is used to display the current loop iteration.Iteration always
-   starts with 1 and is incremented by one on each iteration.
+   <parameter>iteration</parameter> contains the current loop iteration and always
+   starts at one, unlike <link linkend="foreach.property.index"><parameter>index</parameter></link>.
+   It is incremented by one on each iteration.
   </para>
+ <example>
+  <title><parameter>iteration</parameter> and <parameter>index</parameter> example</title>
+<programlisting role="php">
+<![CDATA[
+{* this will output 0|1, 1|2, 2|3, ... etc *}
+{foreach from=$myArray item=i name=foo}
+{$smarty.foreach.foo.index}|{$smarty.foreach.foo.iteration},
+{/foreach}
+]]>
+  </programlisting>
+  </example>
+
  </sect2>
 
  <sect2 id="foreach.property.first">
-  <title>first</title>
+  <title>.first</title>
   <para>
-   <emphasis>first</emphasis> is set to true if the current foreach iteration is the first
-   one.
+   <parameter>first</parameter> is &true; if the current <varname>{foreach}</varname>
+   iteration is the initial one.
   </para>
+  <example>
+  <title><parameter>first</parameter> property example</title>
+<programlisting role="php">
+<![CDATA[
+{* show LATEST on the first item, otherwise the id *}
+<table>
+{foreach from=$items key=myId item=i name=foo}
+<tr>
+  <td>{if $smarty.foreach.foo.first}LATEST{else}{$myId}{/if}</td>
+  <td>{$i.label}</td>
+</tr>
+{/foreach}
+</table>
+]]>
+  </programlisting>
+  </example>
  </sect2>
 
  <sect2 id="foreach.property.last">
-  <title>last</title>
+  <title>.last</title>
   <para>
-   <emphasis>last</emphasis> is set to true if the current foreach iteration is the last
-   one.
+   <parameter>last</parameter> is set to &true; if the current
+   <varname>{foreach}</varname> iteration is the final one.
   </para>
+   <example>
+  <title><parameter>last</parameter> property example</title>
+<programlisting role="php">
+<![CDATA[
+{* Add horizontal rule at end of list *}
+{foreach from=$items key=part_id item=prod name=products}
+  <a href="#{$part_id}">{$prod}</a>{if $smarty.foreach.products.last}<hr>{else},{/if}
+{foreachelse}
+  ... content ...
+{/foreach}
+]]>
+  </programlisting>
+  </example>
  </sect2>
 
  <sect2 id="foreach.property.show">
-  <title>show</title>
+  <title>.show</title>
   <para>
-   <emphasis>show</emphasis> is used as a parameter to foreach.
-   <emphasis>show</emphasis> is a boolean value, true or false. If
-   false, the foreach will not be displayed. If there is a foreachelse
-   present, that will be alternately displayed.
+   <parameter>show</parameter> is used as a parameter to <varname>{foreach}</varname>.
+   <parameter>show</parameter> is a boolean value. If
+   &false;, the <varname>{foreach}</varname> will not be displayed.
+   If there is a <varname>{foreachelse}</varname> present, that will be alternately displayed.
   </para>
 
  </sect2>
  <sect2 id="foreach.property.total">
-  <title>total</title>
+  <title>.total</title>
   <para>
-   <emphasis>total</emphasis> is used to display the number of iterations that this foreach
-   will loop. This can be used inside or after the foreach.
+   <parameter>total</parameter> contains the number of iterations that this
+   <varname>{foreach}</varname>  will loop.
+   This can be used inside or after the <varname>{foreach}</varname>.
   </para>
+     <example>
+  <title><parameter>total</parameter> property example</title>
+<programlisting role="php">
+<![CDATA[
+{* show rows returned at end *}
+{foreach from=$items key=part_id item=prod name=foo}
+{$prod.name><hr/>
+{if $smarty.foreach.foo.last}
+  <div id="total">{$smarty.foreach.foo.total} items</div>
+{/if}
+{foreachelse}
+ ... something else ...
+{/foreach}
+]]>
+  </programlisting>
+  </example>
+
   <para>
    See also <link linkend="language.function.section">{section}</link> and
    <link linkend="language.variables.smarty.loops">$smarty.foreach</link>.