Location: PHPKode > projects > Open Power Template > docs/Opt/syntax.instructions.foreach.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="pl">
<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8" />
	<meta name="robots" content="all" />

	<title>opt:foreach - Open Power Template</title>
	
	<link rel="stylesheet" type="text/css" href="design/generic.css" media="all"  />
	<link rel="stylesheet" type="text/css" href="design/print.css" media="print" />
	<!--[if lte IE 6]><link rel="stylesheet" href="design/ie.css" type="text/css" /><![endif]-->	
	<!--[if IE 7]><link rel="stylesheet" href="design/ie7.css" type="text/css" /><![endif]-->
</head>
<body>

<div id="wrap">
	<div id="header">
		<h1>Open Power Template 2.0</h1>
		<h2>opt:foreach</h2>
		<p class="generated">@ 02.09.2010</p>
		<p class="location"><a href="index.html"><strong>User manual</strong></a> &raquo; <a href="syntax.html">Template syntax</a> &raquo; <a href="syntax.instructions.html">Instructions</a> &raquo; <a href="syntax.instructions.foreach.html">opt:foreach</a></p>
	</div>
	
	<div id="content"><dl class="location"><dt><a href="syntax.instructions.html">3.7. Instructions</a><br/>3.7.9. opt:foreach</dt><dd class="prev">3.7.8. opt:for<br/><a href="syntax.instructions.for.html">&laquo; Previous</a></dd><dd class="next">3.7.10. opt:grid<br/><a href="syntax.instructions.grid.html">Next &raquo;</a></dd></dl>	<h1>3.7.9. opt:foreach</h1><blockquote class="warning">
  <p>This chapter contains information about <em>programming constructs</em> that are not recommended to use. If you are only a template author, probably you will not have to use them. In case of questions, contact your programmer.</p>
</blockquote>

<p><code>opt:foreach</code> iterates over the elements of container, PHP array or object. The index and the value of current element are saved to the variables pointed by the programmer, so that he could use them. The elements are returned in the order of the internal PHP data representation. Even if they are enumerated in the ascending order, but have been put in a more random way, the actual results may be different than expected.</p>

<table>
<thead>
<tr>
  <th>Name</th>
  <th>Type</th>
  <th>Required?</th>
  <th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>array</td>
  <td>Expression</td>
  <td>Yes</td>
  <td align="left">A container with the elements. Note that if the container will be a scalar value, we will get an PHP error.</td>
</tr>
<tr>
  <td>value</td>
  <td>ID</td>
  <td>Yes</td>
  <td align="left">The name of the variable to save the element values to.</td>
</tr>
<tr>
  <td>index</td>
  <td>ID</td>
  <td>No</td>
  <td align="left">The name of the variable to save the element indices to.</td>
</tr>
<tr>
  <td>separator</td>
  <td>Expression</td>
  <td>No</td>
  <td align="left">The separator that will be put between every two list elements. <a href="syntax.instructions.separator.html" title="3.7.21. opt:separator">More about separators</a>.</td>
</tr>
</tbody>
</table>

<p>A sample code:</p>

<pre class="xml"><span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>The options:<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;ol<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;opt:foreach</span> <span style="color: #000066;">array</span>=<span style="color: #ff0000;">&quot;$optionList&quot;</span> <span style="color: #000066;">index</span>=<span style="color: #ff0000;">&quot;name&quot;</span> <span style="color: #000066;">value</span>=<span style="color: #ff0000;">&quot;value&quot;</span><span style="color: #000000; font-weight: bold;">&gt;</span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;li<span style="color: #000000; font-weight: bold;">&gt;</span></span><span style="color: #000000; font-weight: bold;">&lt;strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>{@name}:<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>{@value}<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/li<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/opt:foreach<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/ol<span style="color: #000000; font-weight: bold;">&gt;</span></span></span></pre>

<p>The result:</p>

<pre class="xml"><span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>The options:<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;ol<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;li<span style="color: #000000; font-weight: bold;">&gt;</span></span><span style="color: #000000; font-weight: bold;">&lt;strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>Option 1:<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span> Option value 1<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/li<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;li<span style="color: #000000; font-weight: bold;">&gt;</span></span><span style="color: #000000; font-weight: bold;">&lt;strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>Option 2:<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span> Option value 2<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/li<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;li<span style="color: #000000; font-weight: bold;">&gt;</span></span><span style="color: #000000; font-weight: bold;">&lt;strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>Option 3:<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span> Option value 3<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/li<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/ol<span style="color: #000000; font-weight: bold;">&gt;</span></span></span></pre>

<p>In the example, <code>opt:foreach</code> was executed for a 3-element array. For each of them, the content of the loop was executed, and their index and values were available through <code>@name</code> and <code>@value</code> variables.</p>

<p>In OPT this loop has one extra feature: <code>opt:foreachelse</code> placed directly in <code>opt:foreach</code>. It may contain the alternative content to be displayed if the specified container is empty. Below, you can find a modified example:</p>

<pre class="xml"><span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>The options:<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;ol<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;opt:foreach</span> <span style="color: #000066;">array</span>=<span style="color: #ff0000;">&quot;$optionList&quot;</span> <span style="color: #000066;">index</span>=<span style="color: #ff0000;">&quot;name&quot;</span> <span style="color: #000066;">value</span>=<span style="color: #ff0000;">&quot;value&quot;</span><span style="color: #000000; font-weight: bold;">&gt;</span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;li<span style="color: #000000; font-weight: bold;">&gt;</span></span><span style="color: #000000; font-weight: bold;">&lt;strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>{@name}:<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/strong<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>{@value}<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/li<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;opt:foreachelse<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;li<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>We are sorry, there are no options.<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/li<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/opt:foreachelse<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/opt:foreach<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/ol<span style="color: #000000; font-weight: bold;">&gt;</span></span></span></pre>

<blockquote class="information">
  <p>It does not matter where you exactly place <code>opt:foreachelse</code> - before the main content or after it.</p>
</blockquote>

<p>The result for an empty container will look like this:</p>

<pre class="xml"><span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>The options:<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;ol<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
    <span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;li<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>We are sorry, there are no options.<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/li<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>
<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/ol<span style="color: #000000; font-weight: bold;">&gt;</span></span></span></pre>

<p><code>opt:foreach</code> should not be used too often. Open Power Template provides much more powerful instructions, sections. They are more portable and easier to use in the templates. Moreover, they hide the implementation from the user which is very important, when two sections are connected with an one-to-many relationship.</p>

<p><code>opt:for</code> cooperates with separators:</p>

<pre class="xml"><span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;p<span style="color: #000000; font-weight: bold;">&gt;</span></span><span style="color: #000000; font-weight: bold;">&lt;opt:foreach</span> <span style="color: #000066;">array</span>=<span style="color: #ff0000;">&quot;$things&quot;</span> <span style="color: #000066;">value</span>=<span style="color: #ff0000;">&quot;name&quot;</span> <span style="color: #000066;">str:separator</span>=<span style="color: #ff0000;">&quot;, &quot;</span><span style="color: #000000; font-weight: bold;">&gt;</span></span>{@name}<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/opt:foreach<span style="color: #000000; font-weight: bold;">&gt;</span></span><span style="color: #000000; font-weight: bold;">&lt;/p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span></pre>

<p>A sample result:</p>

<pre><code>hammer, saw, screwdriver, vice
</code></pre>

<p>More separator examples can be found in the chapter explaining <a href="syntax.instructions.separator.html" title="3.7.21. opt:separator">separators</a>.</p>
<h4>See also:</h4><ul><li><a href="syntax.instructions.section.html">3.7.19. opt:section</a></li><li><a href="syntax.instructions.for.html">3.7.8. opt:for</a></li><li><a href="syntax.instructions.repeat.html">3.7.17. opt:repeat</a></li><li><a href="syntax.instructions.separator.html">3.7.21. opt:separator</a></li></ul><dl class="location location-bottom"><dt>3.7.9. opt:foreach<br/><a href="syntax.instructions.html">3.7. Instructions</a></dt><dd class="prev"><a href="syntax.instructions.for.html">&laquo; Previous</a><br/>3.7.8. opt:for</dd><dd class="next"><a href="syntax.instructions.grid.html">Next &raquo;</a><br/>3.7.10. opt:grid</dd></dl>		</div>
	
	<div id="footer">
		<p>Copyright &copy; <a href="http://www.invenzzia.org/">Invenzzia Group 2008-2009</a></p>
		<p>Available under the terms of license: <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License 1.2</a></p>
		<p>Generated by <strong>TypeFriendly 0.1.4</strong> by <a href="http://www.invenzzia.org/">Invenzzia</a></p>
	</div>
</div>

</body>
</html>
Return current item: Open Power Template