ForEach tag

Overview

Use the forEach tag to automatically add a row to your report for each data item in a node (table). An example would be to add a row in an invoice for each product ordered. A sample template, Sample1, uses the forEach tag to generate rows in an invoice by looping through a data table. Refer to the Samples section for a detailed explanation of this sample template.

Be sure to insert both the start and end tags! The generic format of a body tag which requires start and end tags is shown in Report Tags: Overview.

Tip: Data tables are the most organized and easiest way to display data.  Using the Tag Builder allows us to easily create these tables.  The Creating Data Tables (aka using the ForEach Tag) Tutorial Video provides step by step instructions for constructing a data table.

When an out tag sends a command to a data source, the out tag is telling the data source to grab one piece of information from one of the data groups. If you want the template to display all the data rather than just the first set, you can use a forEach tag.

The forEach tag tells the template to go to a data group and retrieve each data item in the group. What's key in understanding how a forEach tag works is remembering that the forEach tag isn't a straight command that displays data, like the out tag. Instead, the forEach tag tells the template how to handle other tags in the template.

The forEach tag tells the template that when the report is run, it should look at the next tag after the forEach tag, retrieve the first piece of data for that data group, retrieve the second piece of data for that data group, retrieve the third piece of data for that data group, and continue doing so until it has retrieved each piece of data for that group. This is often referred to as a forEach loop, since the template is looping through the data in a group.

In the example below, there's a forEach tag before the first out tag:

Contacts

First Name

Last Name

City

<forEach tag> <out tag>

<out tag>

<out tag>

<endforEach tag>

When you run the report, the table might look like this:

Contacts

First Name

Last Name

City

Lisa

Harris

Roma

En-Jay

Hsu

New York

Tomas

Ramirez

Sydney

Kamala

Sharma

Delhi

When running the report, the template then goes to the next tag and does the same thing: retrieves each piece of data for that tag's data group. It continues to do so until it knows it's time to stop looping.

The template knows when to stop looping and instead treat an out tag as a regular out tag because of the endForEach tag. The endForEach tag says, "Okay, stop looping through the data groups of any tag that comes after me." In other words, the forEach and endForEach tags act like bookends that say "For every tag between us, retrieve all the data in their data groups, not just one piece of data."

Tags are processed in the same order the English language is read (from left to right and from top to bottom).

Things to remember:

Note: Out tags aren't the only tags that can be found inside a forEach loop. They are the most basic and the easiest to understand, however, and that's why we use them to illustrate how forEach loops work.

forEach row access

A forEach loop can iterate over several rows of data at once. Inside the loop row [0] always exists but the additional rows may not exist in the last iteration of the loop. For example, if the forEach is iterating over 7 rows of data and has step=’3’ then the first two times through the loop all 3 rows exist. During the last time through the loop, only the first row exists.

Note: rows access is 0-based. So the first row is [0] and the second row is [1]. The number inside the [] is the offset from the start and the first row is the start of the rows. You can use [0] but it is redundant.

You can use the var= attribute in the forEach tag (ex: <wr:forEach select=”/root” var=”items”>) to access any given row using the form items[1] where this is the context for row [1] in the forEach loop.

In the case of an SQL query, you must use the form items[1].ColummName to access a column in a row. Items[1] is column 1 in row [0].

Use the forEach tag to iterate through a set of data items in a node (table), for example to automatically add a row to your report for each data item. The Sample Template chapter shows an example that uses the forEach tag to add a row in an invoice for each product ordered.

Be sure to insert both the start and end tags!

Attributes

Learn More

ForEach Tag Tutorials

Inserting Tags within a ForEach tag

About tags

The Tag Editor