BeginColumnExpand and EndColumnExpand Tag Reference
The BeginColumnExpand and EndColumnExpand tags are extensions of the ForEach/End-Foreach tags that are more use-case specific. The BeginColumnExpand tag is equivalent to the ForEach tag with the order property set to column.
BeginColumnExpand/EndColumnExpand Tag Functionality
The BeginColumnExpand Tag tells the template to go find all the nodes in a set from your data source and loop over each item. For each iteration of the BeginColumnExpand tag, it will repeat all content that is between the BeginColumnExpand tag and the EndColumnExpand tag. However, unlike the BeginRepeat and BeginRowExpand tags, the each iteration will expand by column instead of by row, so each iteration will add additional columns onto your table. Each iteration of the loop will use the data for that specific iteration and will stop repeating the data once all rows or nodes in your data set have been iterated through.
The BeginColumnExpand and EndColumnExpand tags can only be used inside of tables.
Here is a sample template that demonstrates the BeginColumnExpand and EndColumnExpand tags: BeginColumnExpand Sample Template Download
BeginColumnExpand Properties
Tag Properties
nickname (optional)
The nickname will appear in the template rather than the generic "columnExpand:" label. Descriptive nicknames can be very important in designing complex templates.
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 BeginColumnExpand 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 BeginColumnExpand 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 BeginColumnExpand Tag.
- ${name.last} - returns 'true' if the current data element is the last data element in the data set returned by the BeginColumnExpand 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 BeginColumnExpand 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 BeginColumnExpand 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)
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 BeginColumnExpand Tag to "Page break before."
end (optional)
The last row or node in the BeginColumnExpand Tag data set to return. The default is the total number of rows or nodes in the data set returned by the BeginColumnExpand 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.
formula-expansion (default: row)
This property is for excel formulas. It defines how formulas inside of a RowExpand will be expanded.
The first (default) option for formula-expansion is row
This entails that the formula range will expand row by row from the RowExpand, and each row will have its own sum
Example: You have a SUM() function expanding across the first row SUM(A1:C1). If there is a RowExpand expanding down 3 rows, the 2nd row should be SUM(A2, C2), and the last row result should be SUM(A3, C3). The functions will be excusive to each row
The other option for formula-expansion is block
This entails that the formula range will expand by row and column from the RowExpand.
Example: You have a SUM() function expanding across the first row SUM(A1:C1). If there is a RowExpand expanding down 3 rows, the 1st, 2nd and 3rd row should be SUM(A1, C3). The functions will encapsulate the block created by the RowExpand
restart (default: false)
If set to 'true', restarts the numbering of a numbered list after each iteration. This is useful for BeginColumnExpand 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.
EndColumnExpand Properties
Tag Properties
nickname (optional)
The nickname will appear in the template rather than the generic ":columnExpand" 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.