%META:TOPICINFO{author="TWikiContributor" date="1282983442" format="1.1" version="$Rev$"}%
%META:TOPICPARENT{name="Sandbox.PluginDevelopment"}%
---+!! <nop>%TOPIC%
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/ForEachPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/ForEachPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
%SHORTDESCRIPTION%
<sticky><div style="float:right; background-color:#eeeeee; margin:0 0 20px 20px; padding: 0 10px 0 10px; width:380px">
%TOC{title="Page contents"}%
</div></sticky>

---++ Syntax Rules

| *Tag* | *Description* |
| =%<nop>FOREACH{"_var_" in="_list_"}% _body_ %<nop>NEXT{"_var_"}%= | Loop over =_body_= setting control variable =_var_= to each successive element of =_list_= |
| =%<nop>FOR{"_var_" start="_int_" stop="_int_" step="_int_"}% _body_ %<nop>NEXT{"_var_"}%= | Loop over =_body_= setting control variable =_var_= to each integer in the range =start= to =stop= in steps of =step= |


| *Parameters* | *Description* |
| *FOREACH* ||
| ="..."= | Loop control variable.  Within the body of the text this may be referred to as =$var=.  =%<nop>FOREACH{"var" ...}%= must have a matching =%<nop>NEXT{"var"}%= | 
| =in="..."= | Comma separated list.  May contain TWiki Variables |
| *FOR* ||
| ="..."= | Loop control variable.  Within the body of the text this may be referred to as =$var=.  =%<nop>FOR{"var" ...}%= must have a matching =%<nop>NEXT{"var"}%= | 
| ="start"="..."= | Starting integer |
| ="stop"="..."= | Stop integer |
| ="step"="..."= | Increment/decrement =var= in steps of =step=.  __THIS IS REQUIRED__ |

   * *All parameters are required, and must appear in the specified order.*

---++ =FOREACH= Examples

---+++!! Basic Usage
<verbatim>
%FOREACH{"web" in="Main, Sandbox, TWiki"}%
   * [[$web.WebHome]]
%NEXT{"web"}%
</verbatim>

... gives ...
   * [[Main.WebHome]]
   * [[Sandbox.WebHome]]
   * [[TWiki.WebHome]]

... if installed.
%FOREACH{"web" in="Main, Sandbox, TWiki"}%
   * [[$web.WebHome]]
%NEXT{"web"}%

---+++!! Nested loops are possible:
<verbatim>
%FOREACH{"i" in="1, 2, 3"}% %FOREACH{"j" in="a, b, c"}% $i$j %NEXT{"j"}% %NEXT{"i"}%
</verbatim>
%FOREACH{"i" in="1, 2, 3"}% %FOREACH{"j" in="a, b, c"}% $i$j %NEXT{"j"}% %NEXT{"i"}%

---+++!! Lists may contain TWiki Variables or other plugins.  
   * The body of the loop may need to delay expansion:  use =$percnt= to replace =%= if necessary.
<verbatim>
%FOREACH{"web" in="%WEBLIST{"$name" separator=", "}%"}%
| $web | $percntFORMFIELD{"STATUS" topic="$web.%HOMETOPIC%" default="Formfield STATUS not defined in $web" alttext="Formfield STATUS not found in $web"}$percnt |
%NEXT{"web"}%
</verbatim>
%FOREACH{"web" in="%WEBLIST{"$name" separator=", "}%"}%
| $web | $percntFORMFIELD{"STATUS" topic="$web.%HOMETOPIC%" default="Formfield STATUS not defined in $web" alttext="Formfield STATUS not found in $web"}$percnt |
%NEXT{"web"}%

---++ =FOR= Examples 

---+++!! Count up and down in steps
   * =%<nop>FOR{"counta" start="1" stop="10" step="2"}% $counta %NEXT{"counta"}%=
   * %FOR{"counta" start="1" stop="10" step="2"}% $counta %NEXT{"counta"}%
   * =%<nop>FOR{"countb" start="1" stop="10" step="1"}% $countb %NEXT{"countb"}%=
   * %FOR{"countb" start="1" stop="10" step="1"}% $countb %NEXT{"countb"}%
   * =%<nop>FOR{"countc" start="10" stop="1" step="-1"}% $countc %NEXT{"countc"}%=
   * %FOR{"countc" start="10" stop="1" step="-1"}% $countc %NEXT{"countc"}%

---+++!! Nested loops are possible:
<verbatim>
%FOR{"outer" start="1" stop="3" step="1"}%
%FOR{"inner" start="3" stop="1" step="-1"}%
   * $outer - $inner 
%NEXT{"inner"}%
%NEXT{"outer"}%
</verbatim>
%FOR{"outer" start="1" stop="3" step="1"}%
%FOR{"inner" start="103" stop="100" step="-1"}%
   * $outer - $inner 
%NEXT{"inner"}%
%NEXT{"outer"}%

---+++ Error trapping
   * =%<nop>FOR{"countd" start="10" stop="1" step="1"}% $countd %NEXT{"countd"}%= (invalid step)
   * %FOR{"countd" start="10" stop="1" step="1"}% $countd %NEXT{"countd"}%
   * =%<nop>FOR{"counte" start="a" stop="b" step="c"}% $countd %NEXT{"counte"}%= (non-integers)
   * %FOR{"counte" start="a" stop="b" step="c"}% $countd %NEXT{"counte"}%

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>INTERWIKIPLUGIN_SHORTDESCRIPTION%==

   * One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Loop over successive elements of a list, or a range of numbers

   * Debug plugin: (See output in =data/debug.txt=)
      * Set DEBUG = 0

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running. 

   * Download the ZIP file from the Plugin web (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
     | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
   * Test if the installation was successful:
      * See if above examples work

---++ Plugin Info

|  Plugin Author: | TWiki:Main.MagnusLewisSmith |
|  Copyright: | &copy; 2005, TWiki:Main.MagnusLewisSmith; <br /> &copy; 2005-2010, TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 19384 (2010-08-28) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2010-08-28: | TWikibug:Item6571 - doc improvements; changing TWIKIWEB to SYSTEMWEB |
|  2005-09-28: | Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.024 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  TWiki:Plugins/Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins
