ez.no / exponential / documentation / reference / template functions / program flow / section
{section [name=string]
[var=string]
[loop=array]
[show=boolean]
[sequence=array]
[max=integer]
[offset=integer]
[last-value=boolean] }
[{section-exclude match=value8}]
[{section-include match=value9}]
... tpl code
[{delimiter}... tpl code {/delimiter}]
[{section-else}]
{/section}
| Name | Type | Description | Required |
|---|---|---|---|
| name | mixed | Namespace for all generated template variables | no |
| var | mixed | Name of variable containg interator | no |
| loop | mixed | The data that the section should loop over | no |
| show | mixed | Determines whether the section block should be shown or not | no |
| sequence | array | Defines a sequence which is iterated as the normal loop parameter | no |
| max | integer or array | Determines the maximum number of iterations | no |
| offset | integer or array | Determines the start of the loop array for the iterations | no |
| match | mixed | yes | |
| last-value | boolean | Set to true to remember the last item of the loop in the attribute last. | no |
name
Defines the namespace for all generated template variables, see loop and sequence for a list of generated variables. The namespaces can get quite confusing, especially if you use nested sections. It is therefore recommended to use var instead when possible.
var
Defines a variablename for the iterator. It is preferred to use var instead of name
var is only supported in Exponential 3.3 and later
loop
Defines the data that the section should loop over, each the time the section loops it sets a template variable and appends the result of all its children to the output. The data can either be an array, in which case each item in the array is traversed, or a number that determines the number of iterations (a negative number makes the iteration go backwards).
It's possible to constrain the number of elements that is iterated as well as single elements, see parameters max and offset and sub-children section-exclude and section-include.
Each time the section iterates it sets four template variables in the new namespace. The variables are index, number, key and item.
show
This parameter determines whether the section block should be shown or not. If the parameter is not present or is true (either a boolean true, non-empty array or non-zero value) the section block is shown, otherwise the section-else block is shown. This is quite useful for conditional inclusion of template code depending on a variable. When the section-else block is used no looping is done.
sequence
Defines a sequence which is iterated as the normal loop parameter, the difference is that the sequence will wrap and only supports arrays. The current item will be set in the sequence template variable. This parameter is for instance useful if you want to create alternating colors in lists.
max
Determines the maximum number of iterations, the value must be an integer or an array, if it's an array the count of the array is used.
offset
Determines the start of the loop array for the iterations, the value must be an integer or an array, if it's an array the count of the array is used.
section-exclude and section-include
Adds a new filter rule for excluding or including a loop item, the rules will be run after one-another as they are found. The rule will read the match parameter and change the current accept/reject state for the current item, the default is to accept all items. The order of filter rules are important. Later filter rules will override older ones.
The match parameter can match any template variable available including loop iterators, keys and items, but not the loop sequence. Neither can you match on the index as it will not be incremented if the loop item is excluded.
Sequences, index and iteration counts will not be advanced if the loop item is discarded.
delimiter
Determines a block of template elements which should be placed in between two iterations.
section-else
Please look at the comments for show
Example
Looping a simple array
{let elements=array('element1', 'element2', 'element3')} {section loop=$elements} {$item}<br/> {/section} {/let}
Example
looping a simple array, using namespace
{let elements=array('element1', 'element2', 'element3')} {section name=mynamespace loop=$elements} Element value : {$mynamespace:item}<br/> index : {$mynamespace:index}<br/> number : {$mynamespace:number}<br/> key : {$mynamespace:key}<br/> {/section} {/let}
Example
Looping a simple array, using var
{let elements=array('element1', 'element2', 'element3')} {section var=myvar loop=$elements} item : {$item}<br/> Element value : {$myvar.item}<br/> Element value (short version): {$myvar}<br/> index : {$myvar.index}<br/> number : {$myvar.number}<br/> key : {$myvar.key}<br/> {/section} {/let}
Example
Showing the use of show. This illustrates how to create a if-else statement:
{let showThis='yes'} {section show=$showThis|eq('yes') } showThis equals 'yes' {section-else} showThis was NOT 'yes' {/section} {/let}
Example
Show the usage of sequence. Here
{$myvar.sequence} will change between 'blue' and 'darkblue' for each iteration
{let elements=array('element1', 'element2', 'element3', 'element4', 'element5')} {section var=myvar loop=$elements sequence=array('blue', 'darkblue') } Element value : {$myvar.item}<br/> index : {$myvar.index}<br/> number : {$myvar.number}<br/> key : {$myvar.key}<br/> sequence : {$myvar.sequence}<br/> {/section} {/let}
Example
In this example we show the usage of max and offset. This example will loop 3 times, for 'element2', 'element3' and 'element4'
{let elements=array('element1', 'element2', 'element3', 'element4', 'element5')} {section var=myvar loop=$elements sequence=array('blue', 'darkblue') max=3 offset=1} Element value : {$myvar.item}<br/> index : {$myvar.index}<br/> number : {$myvar.number}<br/> key : {$myvar.key}<br/> sequence : {$myvar.sequence}<br/> {/section} {/let}
Example
Using section-exclude to skip one loop item. 'element2' will not be printed
{let elements=array('element1', 'element2', 'element3', 'element4', 'element5')} {section var=myvar loop=$elements sequence=array('blue', 'darkblue')} {section-exclude match=$myvar.key|eq(1)} Element value : {$myvar.item}<br/> index : {$myvar.index}<br/> number : {$myvar.number}<br/> key : {$myvar.key}<br/> sequence : {$myvar.sequence}<br/> {/section} {/let}
Example
Usage of section-include. Here, only 'element2' will be printed. You'll also notice the importance of the filter order. This will not work if you put the filters the other way around
{let elements=array('element1', 'element2', 'element3', 'element4', 'element5')} {section var=myvar loop=$elements sequence=array('blue', 'darkblue')} {section-exclude match=true()} {section-include match=$myvar.key|eq(1)} Element value : {$myvar.item}<br/> index : {$myvar.index}<br/> number : {$myvar.number}<br/> key : {$myvar.key}<br/> sequence : {$myvar.sequence}<br/> {/section} {/let}
Example
This illustrate the use of delimiter
{section name=Loop loop=5} {$Loop:item} {delimiter}.{/delimiter} {/section}
Without the delimiter block you will get a whitespace between the elements:
{section name=Loop loop=5} {$Loop:item} . {/section}
More examples, more or less advanced
Example
Looping an array of numbers
{section name=Num loop=$numbers offset=2 max=2} {$Num:index}:{$Num:number}:{$Num:key} Number: {$Num:item}<br/> {/section}
Example
Looping an associative array
{section name=Num loop=$assoc} {$Num:index}:{$Num:number}:{$Num:key} Text: {$Num:item}<br/> {/section}
Example
Iterating 5 times
{section name=Num loop=5 sequence=array(red,blue)} {section-exclude match=$Num:item|gt(3)} {section-exclude match=$Num:item|lt(3)} {section-include match=$Num:item|lt(2)} {$Num:sequence}-{$Num:index}: {$Num:number}:{$Num:key} Number: {$Num:item}<br/> {/section}
Example
Iterating 5 times, backwards
{section name=Num loop=-5} {$Num:index}:{$Num:number}:{$Num:key} Number: {$Num:item}<br/> {/section}
Example
Looping over a multi-dim array and with a sequence
<table> <th>URI</th><th>Name</th> {section name=Loop loop=$menu:items sequence=array(odd,even)} <tr> <td>{$Loop:sequence} - {$Loop:item.uri}</td> <td class={$Loop:sequence}>{$Loop:item.name}</td> </tr> {/section} </table>
Example
This section is controlled by the show parameter,
if true the section is used (in this case false)
Show list={$show_list|choose('off','on')} {section name=Loop loop=$menu:items show=$show_list} {$Loop:item.uri} : {$Loop:item.name}<br /> {/section}
Example
This section will only show the {section-else}
part since the show item is false
{section name=Loop show=0} abc {$Loop:item} def {section-else} Shown for zero or empty vars {/section}
Example
Loop 5 times negative
{section name=Loop loop=-5} {$Loop:key} {delimiter}::{/delimiter} {/section}
Log in or create a user account to comment.
Comments