diff options
Diffstat (limited to 'vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-foreach.md')
| -rw-r--r-- | vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-foreach.md | 474 |
1 files changed, 228 insertions, 246 deletions
diff --git a/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-foreach.md b/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-foreach.md index fdd740148..645d6c52c 100644 --- a/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-foreach.md +++ b/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-foreach.md @@ -1,15 +1,30 @@ -{foreach},{foreachelse} {#language.function.foreach} -======================= +# {foreach},{foreachelse} `{foreach}` is used for looping over arrays of data. `{foreach}` has a simpler and cleaner syntax than the -[`{section}`](#language.function.section) loop, and can also loop over +[`{section}`](./language-function-section.md) loop, and can also loop over associative arrays. -`{foreach $arrayvar as $itemvar}` +## Option Flags -`{foreach $arrayvar as $keyvar=>$itemvar}` +| Name | Description | +|---------|------------------------------------------| +| nocache | Disables caching of the `{foreach}` loop | + +## Examples + +```smarty + +{foreach $arrayvar as $itemvar} + {$itemvar|escape} +{/foreach} + +{foreach $arrayvar as $keyvar=>$itemvar} + {$keyvar}: {$itemvar|escape} +{/foreach} + +``` > **Note** > > This foreach syntax does not accept any named attributes. This syntax @@ -26,15 +41,15 @@ associative arrays. - `{foreachelse}` is executed when there are no values in the `array` variable. -- `{foreach}` properties are [`@index`](#foreach.property.index), - [`@iteration`](#foreach.property.iteration), - [`@first`](#foreach.property.first), - [`@last`](#foreach.property.last), - [`@show`](#foreach.property.show), - [`@total`](#foreach.property.total). +- `{foreach}` properties are [`@index`](#index), + [`@iteration`](#iteration), + [`@first`](#first), + [`@last`](#last), + [`@show`](#show), + [`@total`](#total). -- `{foreach}` constructs are [`{break}`](#foreach.construct.break), - [`{continue}`](#foreach.construct.continue). +- `{foreach}` constructs are [`{break}`](#break), + [`{continue}`](#continue). - Instead of specifying the `key` variable you can access the current key of the loop item by `{$item@key}` (see examples below). @@ -51,161 +66,139 @@ associative arrays. > `{foreach $myArray as $myKey => $myValue}`, the key is always > available as `$myValue@key` within the foreach loop. -**Option Flags:** - - Name Description - --------- ------------------------------------------ - nocache Disables caching of the `{foreach}` loop - - - <?php - $arr = array('red', 'green', 'blue'); - $smarty->assign('myColors', $arr); - ?> - - - +```php +<?php +$arr = array('red', 'green', 'blue'); +$smarty->assign('myColors', $arr); +``` + Template to output `$myColors` in an un-ordered list - - <ul> +```smarty +<ul> {foreach $myColors as $color} <li>{$color}</li> {/foreach} - </ul> - +</ul> +``` - The above example will output: +```html +<ul> + <li>red</li> + <li>green</li> + <li>blue</li> +</ul> +``` - <ul> - <li>red</li> - <li>green</li> - <li>blue</li> - </ul> - - - - - <?php - $people = array('fname' => 'John', 'lname' => 'Doe', 'email' => 'j.doe@example.com'); - $smarty->assign('myPeople', $people); - ?> - - +```php +<?php +$people = array('fname' => 'John', 'lname' => 'Doe', 'email' => 'j.doe@example.com'); +$smarty->assign('myPeople', $people); +``` Template to output `$myArray` as key/value pairs. - - <ul> +```smarty +<ul> {foreach $myPeople as $value} <li>{$value@key}: {$value}</li> {/foreach} - </ul> - - - +</ul> +``` + The above example will output: - - <ul> - <li>fname: John</li> - <li>lname: Doe</li> - <li>email: j.doe@example.com</li> - </ul> - +```html +<ul> + <li>fname: John</li> + <li>lname: Doe</li> + <li>email: j.doe@example.com</li> +</ul> +``` - Assign an array to Smarty, the key contains the key for each looped value. - - <?php - $smarty->assign('contacts', array( - array('phone' => '555-555-1234', - 'fax' => '555-555-5678', - 'cell' => '555-555-0357'), - array('phone' => '800-555-4444', - 'fax' => '800-555-3333', - 'cell' => '800-555-2222') - )); - ?> - - +```php +<?php + $smarty->assign( + 'contacts', + [ + ['phone' => '555-555-1234', 'fax' => '555-555-5678', 'cell' => '555-555-0357'], + ['phone' => '800-555-4444', 'fax' => '800-555-3333', 'cell' => '800-555-2222'], + ] + ); +``` The template to output `$contact`. - - {* key always available as a property *} - {foreach $contacts as $contact} - {foreach $contact as $value} - {$value@key}: {$value} - {/foreach} - {/foreach} - - {* accessing key the PHP syntax alternate *} - {foreach $contacts as $contact} - {foreach $contact as $key => $value} - {$key}: {$value} - {/foreach} - {/foreach} - +```smarty +{* key always available as a property *} +{foreach $contacts as $contact} + {foreach $contact as $value} + {$value@key}: {$value} + {/foreach} +{/foreach} + +{* accessing key the PHP syntax alternate *} +{foreach $contacts as $contact} + {foreach $contact as $key => $value} + {$key}: {$value} + {/foreach} +{/foreach} +``` - Either of the above examples will output: - - phone: 555-555-1234 - fax: 555-555-5678 - cell: 555-555-0357 - phone: 800-555-4444 - fax: 800-555-3333 - cell: 800-555-2222 - +``` + phone: 555-555-1234 + fax: 555-555-5678 + cell: 555-555-0357 + phone: 800-555-4444 + fax: 800-555-3333 + cell: 800-555-2222 +``` - A database (PDO) example of looping over search results. This example is looping over a PHP iterator instead of an array(). +```php +<?php + include('Smarty.class.php'); - <?php - include('Smarty.class.php'); - - $smarty = new Smarty; - - $dsn = 'mysql:host=localhost;dbname=test'; - $login = 'test'; - $passwd = 'test'; - - // setting PDO to use buffered queries in mysql is - // important if you plan on using multiple result cursors - // in the template. + $smarty = new Smarty; - $db = new PDO($dsn, $login, $passwd, array( - PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true)); + $dsn = 'mysql:host=localhost;dbname=test'; + $login = 'test'; + $passwd = 'test'; - $res = $db->prepare("select * from users"); - $res->execute(); - $res->setFetchMode(PDO::FETCH_LAZY); + // setting PDO to use buffered queries in mysql is + // important if you plan on using multiple result cursors + // in the template. - // assign to smarty - $smarty->assign('res',$res); + $db = new PDO($dsn, $login, $passwd, array( + PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true)); - $smarty->display('index.tpl');?> - ?> + $res = $db->prepare("select * from users"); + $res->execute(); + $res->setFetchMode(PDO::FETCH_LAZY); - + // assign to smarty + $smarty->assign('res',$res); + $smarty->display('index.tpl');?> +``` - {foreach $res as $r} - {$r.id} - {$r.name} - {foreachelse} - .. no results .. - {/foreach} - - +```smarty +{foreach $res as $r} + {$r.id} + {$r.name} +{foreachelse} + .. no results .. +{/foreach} +``` The above is assuming the results contain the columns named `id` and `name`. @@ -216,14 +209,13 @@ looped. With an iterator, each result is loaded/released within the loop. This saves processing time and memory, especially for very large result sets. -\@index {#foreach.property.index} -------- +## @index `index` contains the current array index, starting with zero. - - {* output empty row on the 4th iteration (when index is 3) *} - <table> +```smarty +{* output empty row on the 4th iteration (when index is 3) *} +<table> {foreach $items as $i} {if $i@index eq 3} {* put empty table row *} @@ -231,72 +223,69 @@ result sets. {/if} <tr><td>{$i.label}</td></tr> {/foreach} - </table> - +</table> +``` -\@iteration {#foreach.property.iteration} ------------ +## @iteration `iteration` contains the current loop iteration and always starts at -one, unlike [`index`](#foreach.property.index). It is incremented by one +one, unlike [`index`](#index). It is incremented by one on each iteration. -The *\"is div by\"* operator can be used to detect a specific iteration. +The *"is div by"* operator can be used to detect a specific iteration. Here we bold-face the name every 4th iteration. +```smarty +{foreach $myNames as $name} + {if $name@iteration is div by 4} + <b>{$name}</b> + {/if} + {$name} +{/foreach} +``` - {foreach $myNames as $name} - {if $name@iteration is div by 4} - <b>{$name}</b> - {/if} - {$name} - {/foreach} - -The *\"is even by\"* and *\"is odd by\"* operators can be used to +The *"is even by"* and *"is odd by"* operators can be used to alternate something every so many iterations. Choosing between even or odd rotates which one starts. Here we switch the font color every 3rd iteration. - - {foreach $myNames as $name} - {if $name@iteration is even by 3} - <span style="color: #000">{$name}</span> - {else} - <span style="color: #eee">{$name}</span> - {/if} - {/foreach} - - +```smarty + {foreach $myNames as $name} + {if $name@iteration is even by 3} + <span style="color: #000">{$name}</span> + {else} + <span style="color: #eee">{$name}</span> + {/if} + {/foreach} +``` This will output something similar to this: - - <span style="color: #000">...</span> - <span style="color: #000">...</span> - <span style="color: #000">...</span> - <span style="color: #eee">...</span> - <span style="color: #eee">...</span> - <span style="color: #eee">...</span> - <span style="color: #000">...</span> - <span style="color: #000">...</span> - <span style="color: #000">...</span> - <span style="color: #eee">...</span> - <span style="color: #eee">...</span> - <span style="color: #eee">...</span> - ... - +```html +<span style="color: #000">...</span> +<span style="color: #000">...</span> +<span style="color: #000">...</span> +<span style="color: #eee">...</span> +<span style="color: #eee">...</span> +<span style="color: #eee">...</span> +<span style="color: #000">...</span> +<span style="color: #000">...</span> +<span style="color: #000">...</span> +<span style="color: #eee">...</span> +<span style="color: #eee">...</span> +<span style="color: #eee">...</span> +... +``` - -\@first {#foreach.property.first} -------- +## @first `first` is TRUE if the current `{foreach}` iteration is the initial one. Here we display a table header row on the first iteration. - - {* show table header at first iteration *} - <table> +```smarty +{* show table header at first iteration *} +<table> {foreach $items as $i} {if $i@first} <tr> @@ -309,99 +298,92 @@ Here we display a table header row on the first iteration. <td>{$i.name}</td> </tr> {/foreach} - </table> - +</table> +``` - -\@last {#foreach.property.last} ------- +## @last `last` is set to TRUE if the current `{foreach}` iteration is the final one. Here we display a horizontal rule on the last iteration. - - {* Add horizontal rule at end of list *} - {foreach $items as $item} - <a href="#{$item.id}">{$item.name}</a>{if $item@last}<hr>{else},{/if} - {foreachelse} - ... no items to loop ... - {/foreach} - +```smarty +{* Add horizontal rule at end of list *} +{foreach $items as $item} + <a href="#{$item.id}">{$item.name}</a>{if $item@last}<hr>{else},{/if} +{foreachelse} + ... no items to loop ... +{/foreach} +``` - -\@show {#foreach.property.show} ------- +## @show The show `show` property can be used after the execution of a `{foreach}` loop to detect if data has been displayed or not. `show` is a boolean value. - - <ul> +```smarty +<ul> {foreach $myArray as $name} <li>{$name}</li> {/foreach} - </ul> - {if $name@show} do something here if the array contained data {/if} +</ul> +{if $name@show} do something here if the array contained data {/if} +``` -\@total {#foreach.property.total} -------- +## @total `total` contains the number of iterations that this `{foreach}` will loop. This can be used inside or after the `{foreach}`. +```smarty +{* show number of rows at end *} +{foreach $items as $item} + {$item.name}<hr/> + {if $item@last} + <div id="total">{$item@total} items</div> + {/if} +{foreachelse} + ... no items to loop ... +{/foreach} +``` - {* show number of rows at end *} - {foreach $items as $item} - {$item.name}<hr/> - {if $item@last} - <div id="total">{$item@total} items</div> - {/if} - {foreachelse} - ... no items to loop ... - {/foreach} - -See also [`{section}`](#language.function.section), -[`{for}`](#language.function.for) and -[`{while}`](#language.function.while) +See also [`{section}`](./language-function-section.md), +[`{for}`](./language-function-for.md) and +[`{while}`](./language-function-while.md) -{break} {#foreach.construct.break} -------- +## {break} `{break}` aborts the iteration of the array - - {$data = [1,2,3,4,5]} - {foreach $data as $value} - {if $value == 3} - {* abort iterating the array *} - {break} - {/if} - {$value} - {/foreach} - {* - prints: 1 2 - *} - +```smarty + {$data = [1,2,3,4,5]} + {foreach $data as $value} + {if $value == 3} + {* abort iterating the array *} + {break} + {/if} + {$value} + {/foreach} + {* + prints: 1 2 + *} +``` - -{continue} {#foreach.construct.continue} ----------- +## {continue} `{continue}` leaves the current iteration and begins with the next iteration. - - {$data = [1,2,3,4,5]} - {foreach $data as $value} - {if $value == 3} - {* skip this iteration *} - {continue} - {/if} - {$value} - {/foreach} - {* - prints: 1 2 4 5 - *} - - +```smarty + {$data = [1,2,3,4,5]} + {foreach $data as $value} + {if $value == 3} + {* skip this iteration *} + {continue} + {/if} + {$value} + {/foreach} + {* + prints: 1 2 4 5 + *} +``` |