Skip to main content
Windward

ForEach Tag Reference

Overview:

Use the ForEach Tag to automatically add a row to your document or report for each data item in a node or table from your datasource. This tag repeats through each node in a dataset that you define, just like aforeach statement in programming is used to iterate through an array or object collection. For example, use the ForEach Tag to add a row in a table for an invoice for each product ordered.

 

For a working sample template that demonstrates the ForEach Tag and its many uses, refer to the ‘Sample Templates’ button found in the AutoTag Manager tab.

 

If using the ForEach tag, ensure to include both the start and end ForEach Tags. You will need both for this tag to function properly.

You may also want to reference the generic format of a tag which requires start and end tags. It can be found in the Tag Reference article.

 

Enhanced ForEach Tag:

Click for information on the Enhanced ForEach Tag (beginning in version 10.1).

 

ForEach Row Access:

In programming, a ForEach loop can iterate over several rows of data at once. Row access is 0-based. So the first row is [0], the second row is [1], the third row is [2], and so on.

 

You can use the ‘var=’ attribute in a ForEach Tag (ex: <wr:forEach select=”/root” var=”items”>) to access any specific row. To reference the second row, follow this example: <wr:forEach select=”/root” var=”items[1]”>

 

In the case of a SQL query, you must use the form ‘items[1].ColummName’ to access a specific column in a row.

ForEach Tag Properties:

To edit the attributes of a ForEach Tag, double-click the ForEach Tag, or click the Tag Builder button to launch the Tag Editor.

  • select – required. The data items to step through, one per iteration.

 

Tag Properties:

 

  • var – optional. Identifies the node or row being stepped through. Can be referenced in other tags using the ‘${name}’ format. Each implementation may also contain ‘${name.item}’ where ‘item’ is a way of describing data returned by a specific node or row.
  • varStatus – optional. Returns index, first, last, count for the loop iteration. Can be used in other tags, including <wr:out value=…>, using ‘${name.*}’ as follows:
    • ‘${name.index}’ - the index in the collection of the item returned. This is 0-based and identifies the underlying element regardless of begin and step.
    • ‘${name.count}’ - the number of elements returned so far. This is 1-based and only counts elements actually returned (unlike index which includes all elements including those not returned.)
    • ‘${name.first}’ - returns true() if on the first element to be returned. Otherwise returns false().
    • ‘${name.last}’ - returns true() if on the last element to be returned. Otherwise returns false().
  • order - Default is 'row'. Setting to 'column' will transpose the results so that they expand horizontally. To make column expansion work, the EndForEach tag should be placed in the table, in a new (otherwise empty) row.

 

Advanced Properties:

 

  • begin – optional. Element to start with. 0-based. (default: 0) The valid range is 0 through 4,294,967,295. The first element in the node is [0], the second is [1], etc.
  • step – optional. Process every step element. (default: 1) The valid range is 0 through 4,294,967,295. For example, to skip every other item, step by 2.
  • end – optional. Element to end with (processes this element). This is the last element processed. The default is the number of elements in the node or table. The valid range is 0 through 4,294,967,295.
  • break – optional. Gives the ability to specify when a page break occurs after an iteration and which type of break to make.
    • sheet - will insert a new sheet into a workbook (Excel) after each iteration
    • page -  will insert a section break after each iteration
    • even -  will insert a section break after each even iteration
    • odd -    will insert a section break after each odd iteration

Note: page, even, and odd options create SECTION breaks, not page breaks. This means each section will inherit the header/footer attributes of the previous section, including "different" first page section. This will register the first page of each section as a "first page." To create a page break instead of a section break, set the MS Word paragraph formatting of the ForEach Tag to "page break before."

  • restart - will restart the numbering of a numbered list after each iteration.  Useful when you have a ForEach Tag around a numbered list of items.

 

 

XML Usage:


Below is a long syntax example:

 

<wr:forEach select="./name">

... other text ...

</wr:forEach>

 

The part of the template between the start tag [forEach:] and the end tag [:forEach] repeats once for each row of data returned by the ForEach Tag ‘select=’ statement.

Note:  See the KB article on how to sort data in a forEach without using AutoTag.

 

SQL Usage:

 

Below is a long syntax example:


<wr:forEach select=”select * from ORDER_ITEM where ORDER_ID = ${orderNum}” var=”item”>

This example selects all the rows in the table ORDER_ITEM where the ORDER_ID column has the value of ${orderNum}. In this case, the ${orderNum} comes from a map value. The ForEach Tag will then iterate once for each row.

The var attribute can also be used as:

${var[1]}${var.COLUMN}

${var.columnNames[1]}

 

Multi_row Example:

 

Below is a long syntax example:

 

<wr:forEach select="./name" var=”items” step=”3”>

… template text …

<wr:out select=”${items}/first”/>

<wr:out select=”${items[1]}/first”/>

<wr:out select=”${items[2]}/first”/>

… template text …

</wr:forEach>

 

The above example will repeat once for each 3 rows of data. So if there are 7 rows of data, it will repeat 3 times. In each loop it will list the 3 names from the 3 rows of data in that iteration. In the final loop, the tags for items[1] and items[2] will print nothing, but you will have a blank where there is nothing returned.

Also in the above example, ‘items[3]’ would return an error. You can only use items[0…N] where N is one less than the value for the total number of nodes or rows.

 

Complex XML Example:

 

Below is a long syntax example:

 

<wr:forEach ="./name" var=”items” varStatus=”stat” begin=”2” step=”3” end=”10”>

… template text …

<wr:out select=”${items}/first”/>

<wr:if test=”${stat.first}”>The first person is:</wr:if>

<wr:if test=”${stat.count} == 2”>The second person is:</wr:if>

</wr:forEach>

The above example returns the 2nd, 5th, and 8th nodes that match ./name. The Out Tag will return the node ‘./name/first’. The first If Tag will only display the first time and the second If Tag will only display the second time.