Skip to main content
Windward

ForEach and EndForEach Tags

Overview:

This article contains information for the novice and experienced user. The ForEach Tag tells the template to go find all the data in a set from your data source and retrieve each item. Once a ForEach loop has completed one round of looping, it will check back through its assigned data set. This happens until it finds all the items in your set of data; the ForEach tag is looping through your data finding what you ask it to find, until you tell it to stop.

 

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.

 

  ForEach Tag 

  EndForEach Tag 

Video Tutorial

Here is a great video that will show you, step by step, how to construct a data table using ForEach tags. Data tables are the most organized and easiest way to display data associated with ForEach Tags.

 

The Basics

The ForEach Loop

To use the ForEach tag, you must link it to a set of data in your data source by using the Select function or the Tag Builder, each in the AutoTag Ribbon. If you just use one ForEach Tag and then close the tag (EndForEach Tag), it will produce nothing when you Output.  You must insert additional tags between your ForEach and EndForEach tags that tell the ForEach/EndForEach tags what to do with the data you assigned to it.  This is referred to as a ForEach Loop.

 

The ForEach Tag tells your template to go find all the data in the Selected set from your data source and retrieve each item that was requested by your other tags. What is key to understanding the way ForEach Tag works is to remember that the ForEach Tag is not a command that displays data, like the Out Tag. Instead, the ForEach and EndForEach Tags will find all the tags between them and provide those tags with the data items they need.

 

When you Output, and depending on how you have structured your template, the ForEach Tag will automatically add a row to your document or even create a new page for each data item that was requested from your data source. Once a ForEach loop has completed one round of looping, it will check back through its assigned data set. This happens until it finds all the items in your set of data; the ForEach tag is looping through your data finding what you ask it to find, until you tell it to stop. However, if you forget your EndForEach Tag, you will simply get an error message when you try to Output.

ForEach Loop Example 

Let’s produce an example of a table in a template using ForEach Tags. Notice (below) the ForEach Tag in the cell under First Name; it is placed before the first Out Tag:

After connecting it to a data set, and specifying what data you want the Out-Tag to retrieve (see this article for instructions), the table will look something like this when you Output:

 

When you Output, the template goes through the set of data items (in this case, the Out Tags), then retrieves each item for the tag that needs it. It continues to do so until it reaches the end.

 

 

For example:

  • In an invoice, the ForEach Tag will add a row in a table for each product ordered. (...in conjunction with another tag)
  • In a form letter, a ForEach Tag can be used in the name/address and salutation to produce hundreds of letters to different individuals from one template document.(...in conjunction with another tag)
  • You could combine the examples above to generate multiple company-specific invoices at one time from a one-page template.  At Output, each invoice could contain the contact and mailing address in the header, and the unique billable items below.
  • The possibilities are only limited by your imagination, and are not just for invoices or letters.

 

Out Tag vs ForEach Loop with Out Tags

When an Out Tag sends a command to a data source, the Out Tag is telling the data source to grab only one piece of information and display it. This could be one table, one image, one name, one product number, one account number, etc.  However, if you want the template to display more of the data in a set at one time, then use a ForEach Tag in conjunction with several Out Tags to display more (or all!) of the names, product numbers, account numbers, etc.  The possibilities and combinations are endless.

Helpful Tips

  • You can have multiple ForEach/EndForEach Tags in a template
  • All tags between the ForEach and EndForEach Tags are processed from left to right, and from top to bottom

  • Any element or tags that are found between the ForEach Tag and EndForEach Tag will be repeated for each set of data from your data source
  • If you do not want a blank row for the last row, make sure your EndForEach Tag is placed OUTSIDE the last row of the table
  • When using a ForEach Tag in Excel, make sure your EndForEach Tag is located on the row BELOW your other tags.
  • You can insert almost any of the AutoTag tags into your ForEach loop, however the most often used is the Out Tag.

 

Inserting Tags Within A ForEach Tag Loop

Please see the following pages for more instructional information:

 

  • For a working sample template that demonstrates the ForEach Tag and its many uses, refer to the ‘Samples Templates’ button found in the AutoTag Manager tab.
  • To insert tags into a ForEach Tag, see Inserting Tags within a forEach Tag.
  • 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. Use this to set the data within your data source which the ForEach Loop should access for its associated tags.

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 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

Break Notes:

  • 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."
  • Windward doesn't allow break='sheet'  property for inner ForEach Tags; it will only work for the outer ForEach Tag. We offered this as a feature at one point, but discovered it caused more problems for users than it solved. Therefore, there is just no way to include breaking on an inner ForEach Tag.
  • 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.

  • Was this article helpful?