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:
-
If you have a forEach tag, you must have a corresponding endforEach tag.
-
You can have multiple forEach loops in templates.
-
If you do not want a blank row as the last row make sure your endforEach tag is place outside the last row of the table.
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
-
select – required. The data items (fields) to walk through, one per iteration.
-
var – optional. Identifies the node being stepped through. Can be used in other tags using ${name}. Each implementation may also contain ${name.item} where item is a way of describing data returned by this node.
-
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. For example, if begin="3" then the first value of index will be 3.
-
${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().
-
begin – optional. Element to start with. 0-based. (default: 0) The valid range is 0 - 4,294,967,295. The first element in the node is the 0th, the next is the 1st (and so on), such that 4 items would be numbered 0, 1, 2, and 3. Select begin and enter the data item to start with. The valid range is 0 - 4,294,967,295.
-
step – optional. Process every step element. (default: 1) The valid range is 0 - 4,294,967,295. For example, to skip every other item, step by 2. The valid range is 1 - 4,294,967,295.
-
end – optional. Element to end with (processes this element). Set this attribute to the data item to end with. This is the last element processed. The default is the number of elements in the node. The valid range is 0 - 4,294,967,295.
