From 2a251ef091bd54831e678266508956a92ac9bf3b Mon Sep 17 00:00:00 2001 From: pete_morgan Date: Mon, 25 Sep 2006 18:39:31 +0000 Subject: [PATCH] Major tidy up, added index property and some examples --- .../language-function-foreach.xml | 335 ++++++++++++++---- 1 file changed, 268 insertions(+), 67 deletions(-) diff --git a/docs/en/designers/language-builtin-functions/language-function-foreach.xml b/docs/en/designers/language-builtin-functions/language-function-foreach.xml index e20d0e27..7f3dfd86 100644 --- a/docs/en/designers/language-builtin-functions/language-function-foreach.xml +++ b/docs/en/designers/language-builtin-functions/language-function-foreach.xml @@ -3,27 +3,18 @@ {foreach},{foreachelse} - {foreach} loops are an alternative to - {section} - loops. {foreach} is used to loop over a - single associative array. The syntax for - {foreach} is much easier than - {section}, but as a tradeoff it - can only be used - for a single array. {foreach} tags must be - paired with {/foreach} tags. Required parameters - are from and item. The - name of the {foreach} loop can be anything you like, made up of - letters, numbers and underscores. {foreach} - loops can be nested, and the nested {foreach} names must be unique - from each other. The from variable (usually an - array of values) determines the number of times - {foreach} will loop. - {foreachelse} is executed when there are no - values in the from variable. - - + {foreach} is used to loop over a + single associative array, + unlike {section} + which is for looping over arrays of data. + The syntax for + {foreach} is much easier than + {section}, + but as a tradeoff it can only be used + for a single array. Every {foreach} tag must be + paired with a closing {/foreach} tag. + + @@ -75,22 +66,81 @@ + + + + Required attributes are from and item. + + + + The name of the {foreach} loop can be anything + you like, made up of letters, numbers and underscores, like + PHP variables. + + + + {foreach} loops can be nested, and the nested + {foreach} names MUST be unique from each other. + + + + The from attribute, usually an array of values, + determines the number of times {foreach} will loop. + + + + {foreachelse} is executed when there are no + values in the from variable. + + + + {foreach} loops also have their own variables that handle properties. + These are accessible as: + + {$smarty.foreach.name.property} with + name being the name attribute. + + + Note + The name attribute is only required when + you want to access a {foreach} property, unlike + {section}. + Accessing a {foreach} property with name + undefined does not throw an error, but leads to unpredictable results instead. + + + + + + {foreach} properties are + index, + iteration, + first, + last, + show, + total. + + + + - {foreach} - item + The <parameter>item</parameter> attribute assign('custid', $arr); +$arr = array(1000, 1001, 1002); +$smarty->assign('myArray', $arr); ?> ]]> + Template to output $myArray in an un-ordered list +
    +{foreach from=$myArray item=foo} +
  • {$foo}
    • {/foreach} +
]]> @@ -98,19 +148,92 @@ $smarty->assign('custid', $arr); -id: 1001
-id: 1002
+
    +
  • 1000
    • +
  • 1001
    • +
  • 1002
    • +
+]]> + + + + + Demonstrates the <parameter>item</parameter> and <parameter>key</parameter> attributes + + 'Tennis', 3 => 'Swimming', 8 => 'Coding'); +$smarty->assign('myArray', $arr); +?> +]]> + + Template to output $myArray as key/val pair, + like PHP's foreach. + + +{foreach from=$myArray key=k item=v} +
  • {$k}: {$v}
    • +{/foreach} + +]]> +     + + The above example will output: + + + +
  • 9: Tennis
    • +
  • 3: Swimming
    • +
  • 8: Coding
    • + +]]> +     +     + + + + {foreach} with associative <parameter>item</parameter> attribute + + array('no' => 2456, 'label' => 'Salad'), + 96 => array('no' => 4889, 'label' => 'Cream') + ); +$smarty->assign('items', $items_list); +?> +]]> + + Template to output $items with + $myId in the url + + +{foreach from=$items key=myId item=i} +
  • {$i.no}: {$i.label}
    • +{/foreach} + +]]> +     + + The above example will output: + + + +
  • 2456: Salad
    • +
  • 4889: Cream
    • + ]]>     - {foreach} - item and key + {foreach} with nested <parameter>item</parameter> and <parameter>key</parameter> + Assign an array to Smarty, the key contains the key for each looped value. assign('contacts', array( array('phone' => '1', @@ -123,6 +246,7 @@ id: 1002
    ?> ]]>     + The template to output $contact.     - {foreach} - database example (eg PEAR or ADODB) + Database example with {foreachelse} + A database (eg PEAR or ADODB) example of a search script, the query results assigned to 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) ); ?> ]]> + The template which display None found + if no results with {foreachelse}. {$con.name} - {$con.nick}
    +{foreach key=cid item=con from=$results} + {$con.name} - {$con.nick}
    +{foreachelse} + No items were found in the search {/foreach} ]]> - - - {foreach} loops also have their own variables that handle {foreach} properties. - These are indicated like so: - {$smarty.foreach.foreachname.varname} - with - foreachname being the name specified as the name - attribute of foreach - - See {section} - for examples of the properties below as they are identical - + + .index + + index contains the current array index, starting with zero. + + + <parameter>index</parameter> example + + + +{foreach from=$items key=myId item=i name=foo} + {if $smarty.foreach.foo.index % 5 == 0} + Title + {/if} + {$i.label} +{/foreach} + +]]> + + + - iteration + .iteration - iteration is used to display the current loop iteration.Iteration always - starts with 1 and is incremented by one on each iteration. + iteration contains the current loop iteration and always + starts at one, unlike index. + It is incremented by one on each iteration. + + <parameter>iteration</parameter> and <parameter>index</parameter> example + + + + + - first + .first - first is set to true if the current foreach iteration is the first - one. + first is &true; if the current {foreach} + iteration is the initial one. + + <parameter>first</parameter> property example + + +{foreach from=$items key=myId item=i name=foo} + + {if $smarty.foreach.foo.first}LATEST{else}{$myId}{/if} + {$i.label} + +{/foreach} + +]]> + + - last + .last - last is set to true if the current foreach iteration is the last - one. + last is set to &true; if the current + {foreach} iteration is the final one. + + <parameter>last</parameter> property example + +{$prod}{if $smarty.foreach.products.last}
    {else},{/if} +{foreachelse} + ... content ... +{/foreach} +]]> +     +     - show + .show - show is used as a parameter to foreach. - show 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. + show is used as a parameter to {foreach}. + show is a boolean value. If + &false;, the {foreach} will not be displayed. + If there is a {foreachelse} present, that will be alternately displayed. - total + .total - total is used to display the number of iterations that this foreach - will loop. This can be used inside or after the foreach. + total contains the number of iterations that this + {foreach} will loop. + This can be used inside or after the {foreach}. + + <parameter>total</parameter> property example + +
    +{if $smarty.foreach.foo.last} +
    {$smarty.foreach.foo.total} items
    +{/if} +{foreachelse} + ... something else ... +{/foreach} +]]> +     +     + See also {section} and $smarty.foreach.