Repeater Elements
  • 18 Sep 2024
  • 5 Minutes to read
  • Dark
    Light

Repeater Elements

  • Dark
    Light

Article summary

General

Repeater elements can be used to repeat portions of a Template.

Example: A repeater can be used to repeat a worksheet in a template for every value of a Datasource field.

Properties

Every repeater element has the following properties:

Name

Description
NameThe name of the repeater element. This name will be displayed in the tree hierarchy of the content explorer of the Report Designer.
CodeThe code of the repeater element. There must be no other report element within the same report with the same code. The code is used to reference the report element from within a Template (see below).
ConditionAn optional condition Expression; if it returns True or 1 the condition is considered to be fulfilled and the portion encapsulated by the repeater element will be included in the report document and repeated. If it returns something other than True or 1 the portion encapsulated by the repeater element will be removed from the report document. If you leave this property empty, the condition is considered to be always fulfilled. The condition expression is evaluated after the preparation Actions of the repeater element have been executed.
Preparation ActionsA list of Actions that will be executed before the repeater element will be processed.
Fail On Filter ExceptionDetermines what shall happen if an exception occurs when executing a preparation action that performs a filter (e.g. because the value to which you want to filter does not exist). When enabled, an exception will be thrown and the report document creation will be cancelled; when disabled, the portion encapsulated by the repeater element will be removed from the report document.
Number Of Repeated ItemsThe number of repeated worksheets per row of the cross-product (e.g.: if you set this to 2 then the worksheet that contains the reference to the repeater plus the worksheet right next to it will be repeated per cross-product row). This property is only applicable if the repeater is used as a sheet repeater (see below).

Levels

Every repeater element has one or more levels. The portion encapsulated by the repeater element will be repeated once for each cross product combination of all repeater levels.

Example: If you have two levels; one for the Datasource field Year (which has the values 2008 and 2009) and one for the datasource field Country (which has the values Austria and Germany) the cross product of these two values (2008/Austria, 2008/Germany, 2009/Austria, 2009/Germany) will lead to four repetitions of the portion encapsulated by the repeater element.

Properties

Every repeater level has the following properties:

Name

Description
SourceThe type of source for the list of repeated values.

Datasource Field. If you select this option you can select a datasource field whose values will be used for repetition.

Expression. If you select this option you can enter an Expression that returns one or more values to be used for the repetition.
Datasource FieldThe Datasource field from which to read values to repeat over. This property is only available if the Source is set to Datasource Field.
ExpressionThe Expression that returns one or more values to be used for the repetition. This property is only available if the Source is set to Expression.
Sort OrderNone. If you select this option, the values of the datasource field will not be sorted and used in the order in which the datasource returns them.

Ascending. If you select this option, the values of the datasource field will be sorted in ascending order.

Descending. If you select this option, the values of the datasource field will be sorted in descending order.
Value NameThe name of the internal variable that contains the currently repeated value which can be accessed in Expressions using a Repeated Value Placeholder.
Fields To FilterA list of datasource fields that shall be filtered to the repeated value when the rows or sheets are repeated.This property is not available if Source is set to Table Rows, because no filtering will be performed in that case. If Source is set to Datasource Field and you leave this list empty, only the datasource field you specified in the property Datasource Field will be filtered. In most cases it is not required to specify any fields here unless you want to also filter fields in datasources different from the one from which the repeated values are read.

Sheet Repeater

When using a repeater element as a sheet repeater, the worksheet on which the reference to the repeater element is placed (plus additional worksheets, depending on the Number Of Repeated Items property) will be repeated for every row of the cross-product of repeater levels. To use the repeater as a sheet repeater, place a reference to the repeater element anywhere on the first worksheet to be repeated using the following syntax:

Sheet Repeater Element Reference

{{<code>}}

Then set the *Number Of Repeated Items *of the repeater element (see properties above) to the number of worksheets to be repeated per cross-product row.

NOTE

Microsoft Excel requires worksheet names within a workbook to be unique. When using a sheet repeater, you will have to create an Expression Element for every repeated worksheet that returns a String that contains the name of the repeated worksheet and put the placeholder of the expression element into the title of the repeated sheet.

NOTE

If you change the code of a repeater element after you have inserted the placeholder into the template, you need to change the placeholder of the element in the template as well. Otherwise error messages will occur when creating the report document.

Row Repeater

You can use a repeater element to repeat one or more rows within a worksheet per cross-product row by placing a start tag and an end tag with the following syntax:

Row Repeater Element Start Tag

{{<code>}}

Row Repeater Element End Tag

{{</code>}}

In the template, this look like this:


Row Repeater Element Reference in Microsoft Excel Template

NOTE

The rows that contain the start and end tags of the repeater element will be removed from the worksheet; you therefore have to place them into rows which contain no other content.

NOTE

If you change the code of a repeater element after you have inserted the placeholder into the template, you need to change the placeholder of the element in the template as well. Otherwise error messages will occur when creating the report document.


Was this article helpful?

What's Next