`<foreach>`

<foreach> creates a set of data transformation operations based on the items in a specified list.

Description

During block code expansion, the contents of the <foreach> construct are inserted as data transformation operations using the values in the list specified to the loop variable. The list can be traversed in either direction, and a tally variable can be used to reference the number of the loop iteration.

Syntax

<foreach [VAR]="[LIST_OF_ITEMS]" 
 dir_="[forward|reverse]" tally_="[TALLY_VAR]">
     [CONTENTS]  
</foreach>

Attributes

[VAR]

The attribute's name is arbitrary and specifies the name of the iterated variable. The value assigned to this variable should be a comma-separated list of strings or numbers.

If empty, it is considered a 0-element list. If it contains no commas, it is considered a 1-element list.

dir_

Specifies the direction in which the list is traversed.

Valid values are:

forward: The list is traversed from the first element to the last.
reverse: the list is traversed from last to first element.

The default is forward.

tally_

Accepts the name of a variable whose value corresponds to the number of the iteration. The value of the variable can be used within the contents of the <foreach> loop on each iteration.

The value of the variable is initially set to 1 and is incremented by 1 on each iteration.

Example

In this example, <foreach> is used to create a set of result columns for a tabulation within a block based on a list of column names. The block calculates the average of the values in each of the columns. The <block> declares a variable cols that accepts a comma-separated list of column names. For each column name in cols, a <tcol> is created within the <tabu> using the column name for the source and name parameters.

The <insert> calls the block named quickavg with the column names sales and cost provided for the cols attribute.

<library>
  <block name="quickavg" cols="">
    <if test="{@cols=''}">
      <then>
        <signal msg="quickavg: must specify cols"/>
      </then>
    </if>
    <tabu>
      <foreach col="{@cols}">
        <tcol source="{@col}" name="{@col}" fun="avg"/>
      </foreach>
    </tabu>
  </block>
</library>

<base table="pub.demo.retail.item"/>
<insert block="quickavg" cols="sales,cost"/>

The query after block code expansion is:

<base table="pub.demo.retail.item"/>
<tabu label="Tabulation">
  <tcol fun="avg" name="sales" source="sales"/>
  <tcol fun="avg" name="cost" source="cost"/>
</tabu>