aboutsummaryrefslogtreecommitdiffstats
path: root/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-foreach.md
diff options
context:
space:
mode:
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.md407
1 files changed, 407 insertions, 0 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
new file mode 100644
index 000000000..fdd740148
--- /dev/null
+++ b/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-foreach.md
@@ -0,0 +1,407 @@
+{foreach},{foreachelse} {#language.function.foreach}
+=======================
+
+`{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
+associative arrays.
+
+`{foreach $arrayvar as $itemvar}`
+
+`{foreach $arrayvar as $keyvar=>$itemvar}`
+
+> **Note**
+>
+> This foreach syntax does not accept any named attributes. This syntax
+> is new to Smarty 3, however the Smarty 2.x syntax
+> `{foreach from=$myarray key="mykey" item="myitem"}` is still
+> supported.
+
+- `{foreach}` loops can be nested.
+
+- The `array` variable, usually an array of values, determines the
+ number of times `{foreach}` will loop. You can also pass an integer
+ for arbitrary loops.
+
+- `{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}` constructs are [`{break}`](#foreach.construct.break),
+ [`{continue}`](#foreach.construct.continue).
+
+- Instead of specifying the `key` variable you can access the current
+ key of the loop item by `{$item@key}` (see examples below).
+
+> **Note**
+>
+> The `$var@property` syntax is new to Smarty 3, however when using the
+> Smarty 2 `{foreach from=$myarray key="mykey" item="myitem"}` style
+> syntax, the `$smarty.foreach.name.property` syntax is still supported.
+
+> **Note**
+>
+> Although you can retrieve the array key with the syntax
+> `{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);
+ ?>
+
+
+
+Template to output `$myColors` in an un-ordered list
+
+
+ <ul>
+ {foreach $myColors as $color}
+ <li>{$color}</li>
+ {/foreach}
+ </ul>
+
+
+
+The above example will output:
+
+
+ <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);
+ ?>
+
+
+
+Template to output `$myArray` as key/value pairs.
+
+
+ <ul>
+ {foreach $myPeople as $value}
+ <li>{$value@key}: {$value}</li>
+ {/foreach}
+ </ul>
+
+
+
+The above example will output:
+
+
+ <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')
+ ));
+ ?>
+
+
+
+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}
+
+
+
+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
+
+
+
+A database (PDO) example of looping over search results. This example is
+looping over a PHP iterator instead of an array().
+
+
+ <?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.
+
+ $db = new PDO($dsn, $login, $passwd, array(
+ PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true));
+
+ $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}
+
+
+
+The above is assuming the results contain the columns named `id` and
+`name`.
+
+What is the advantage of an iterator vs. looping over a plain old array?
+With an array, all the results are accumulated into memory before being
+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` contains the current array index, starting with zero.
+
+
+ {* 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 *}
+ <tr><td>nbsp;</td></tr>
+ {/if}
+ <tr><td>{$i.label}</td></tr>
+ {/foreach}
+ </table>
+
+
+
+\@iteration {#foreach.property.iteration}
+-----------
+
+`iteration` contains the current loop iteration and always starts at
+one, unlike [`index`](#foreach.property.index). It is incremented by one
+on each iteration.
+
+The *\"is div by\"* operator can be used to detect a specific iteration.
+Here we bold-face the name every 4th iteration.
+
+
+ {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
+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}
+
+
+
+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>
+ ...
+
+
+
+\@first {#foreach.property.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>
+ {foreach $items as $i}
+ {if $i@first}
+ <tr>
+ <th>key</td>
+ <th>name</td>
+ </tr>
+ {/if}
+ <tr>
+ <td>{$i@key}</td>
+ <td>{$i.name}</td>
+ </tr>
+ {/foreach}
+ </table>
+
+
+
+\@last {#foreach.property.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}
+
+
+
+\@show {#foreach.property.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>
+ {foreach $myArray as $name}
+ <li>{$name}</li>
+ {/foreach}
+ </ul>
+ {if $name@show} do something here if the array contained data {/if}
+
+\@total {#foreach.property.total}
+-------
+
+`total` contains the number of iterations that this `{foreach}` will
+loop. This can be used inside or after the `{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)
+
+{break} {#foreach.construct.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
+ *}
+
+
+
+{continue} {#foreach.construct.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
+ *}
+
+
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-21 05:26:40 +0000