ForEach and End ForEach Tag Reference

info

The ForEach Tag tells the template to go find all the rows or nodes in a set from your data source and retrieve each item. Once a ForEach Tag loop has completed one iteration through the loop, it will iterate again through its assigned data set. This happens until it returns all the rows or nodes in your data set; the ForEach tag is looping through your data returning what you ask it to return, until you tell it to stop.

A ForEach Tag iterating through each row or node in a data set you define, is similar to a foreach statement in programming used to iterate through an array or object collection.

This article describes each property of ForEach and End ForEach Tags.

ForEach Tag Properties

Here we see the properties of a ForEach Tag. Below each property is described in detail. Unless otherwise noted, each property is required.

Tag Properties

block (default: false)

If set to 'true', expands the rows in a data set returned by the ForEach Tag in a contiguous block of cells, while preserving as much as possible the cells around the block. Blank cells will be added around the block as needed to preserve the shape and contents of the table.

This property also allows you to expand ForEach Tags side by side in the same table.

caution

• The block property only functions when the order property is set to "row".
• The block property only functions when the ForEach and End ForEach Tags are in the same table.

nickname (optional)

The nickname will appear in the template rather than the generic "forEach:" label. Descriptive nicknames can be very important in designing complex templates.

order (default: legacy)

This property allows you to control whether the ForEach Tag will expand row by row or column by column.

• legacy - the Foreach Tag will expand row by row (Note the End ForEach Tag 'deleteRow' property is ignored.)
• row - the ForEach Tag will expand row by row
• column - the ForEach Tag will expand column by column

caution

The order property only functions when the ForEach and End ForEach Tags are in the same table

var (optional; default: varName1)

The name used to access the current node or row in the loop. It can be referenced by other Tags within the loop using the Fluent variable name format "${varName1}". Tags within the loop can also reference an item within the current node or row using the format "${varName1.item}".

varStatus (optional)

The name is used to access the ForEach Tag status variables. The status variables can be used within the loop to obtain information about the loop such as the index of the current data element (row or node); the number of data elements returned so far; and a condition indicating whether the current data element is the first or last data element in the loop.

• ${name.index} - the zero-based index of the current data element in the data set returned by the ForEach Tag. This index is relative to the entire data set; it is independent of the 'begin' or 'step' property settings.
• ${name.count} - the number of data elements returned so far. The count begins at one and reflects the data elements actually returned, unlike ${name.index}, which includes the entire data set regardless of which data elements are returned.
• ${name.first} - returns 'true' if the current data element is the first data element in the data set returned by the ForEach Tag.
• ${name.last} - returns 'true' if the current data element is the last data element in the data set returned by the ForEach Tag.

Standard Properties

description (optional)

A brief description of this Tag.

enabled (default: on)

Controls whether a Tag is executed when generating output. This can be useful when debugging a template.

• on - this Tag will be executed when output is generated.
• off - this Tag will not be executed when output is generated.
• engine-only - this Tag will be executed only if output is generated using one of the Report Engines.
• autotag-only - this Tag will be executed only if output is generated using Report Designer.

Advanced Properties

begin (optional)

The row or node in the ForEach Tag data set to return first. This property is zero-based, i.e. the first element of the data set is begin=0, the second is begin=1, etc., and its range is 0 to 4,294,967,295.

break (optional)

Controls how to set a section break at the start of each iteration of the ForEach Tag. This property has different settings for Word and Excel.

• Word settings
  • page - inserts a next-page section break at the start of each iteration
  • even - inserts an even-page section break at the start of each iteration
  • odd - inserts an odd-page section break at the start of each iteration
• Excel settings
  • sheet - inserts a new worksheet into the Excel workbook at the start of each iteration
  • page - inserts a page break at the start of each iteration in the appropriate output type (e.g. PDF)

note

The 'page', 'even', and 'odd' settings create section breaks, not page breaks. This means each section will inherit the header/footer attributes of the previous section, including the previous section's Different First Page. To create a page break instead of a section break, set the Word paragraph formatting of the ForEach Tag to "Page break before."

end (optional)

The last row or node in the ForEach Tag data set to return. The default is the total number of rows or nodes in the data set returned by the ForEach Tag. Its range is 0 to 4,294,967,295.

error-handling (optional)

Selects which types of errors produce warnings rather than exceptions, which allows output to be generated despite the error.

• Ignore type error - these errors occur when a Tag's defined data type is different than the data type of the data returned by the Tag's query
• Ignore formatting error - these errors occur when a Tag's specified format is not compatible with the format of the data returned by the Tag's query
• Ignore select error - these errors occur when a Tag's query fails to find valid data
• Node must exist - these errors occur when a row or node is queried which doesn't exist in the data source. These errors typically return an empty value that is output without warning.
• Node must not return NULL - these errors occur when a query returns an empty or NULL value. These errors typically return an empty value that is output without warning.
• Treat warning as error - forces all of the above error-handling warnings to appear as errors (not exceptions). This is useful when used with Report Designer's Verify feature.

restart (default: false)

If set to 'true', restarts the numbering of a numbered list after each iteration. This is useful for ForEach Tag loops that contain numbered lists.

step (optional; default: 1)

Returns every stepth data element in the data set. For example, to skip every other data element, set step=2. The range is 0 to 4,294,967,295.

End ForEach Properties

End ForEach Tags are used to "close the loop" which begins with a ForEach Tag, meaning the Tags between a ForEach Tag and its matching End ForEach Tag are processed during each iteration of the ForEach Tag loop.

End ForEach Tags also define the scope of a ForEach Tag variable. For example, if a ForEach Tag's variable is ${varName1}, Tags before the matching End ForEach Tag can refer to ${varName1}, but not Tags after the matching End ForEach Tag.

Tag Properties

deleteRow (default: false)

By default, all of the content of the row containing the End ForEach Tag is output. When this property is set to 'true', nothing in the row containing the End ForEach Tag is output.

caution

The deleteRow property only functions when the ForEach and End ForEach Tags are in the same table, and the corresponding ForEach Tag's order property is set to row or column.

nickname (optional)

The nickname will appear in the template rather than the generic ":forEach" label. Descriptive nicknames can be very important in designing complex templates.

Standard Properties

description (optional)

A brief description of this Tag.

enabled (default: on)

Controls whether a Tag is executed when generating output. This can be useful when debugging a template.

• on - this Tag will be executed when output is generated.
• off - this Tag will not be executed when output is generated.
• engine-only - this Tag will be executed only if output is generated using one of the Report Engines.
• autotag-only - this Tag will be executed only if output is generated using Report Designer.