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

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 portion encapsulated by the repeater element is 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.

Insertion

You can insert the placeholder for the repeater element by dragging and dropping the report element from the content explorer of the Report Designer into the template. You will then see a start and an end tag for the repeater element:

Repeater Element Start Tag

{{<code>}}

Repeater Element Start Tag

{{/<code>}}

Every content between the start and the end tag of the repeater element will be repeated for every cross product combination of the repeater. If the repeater is excluded from the report document (e.g. if the cross product is empty), the portion encapsulated by the start and end tag will be removed from the report document. The following screenshot shows an example of a repeater:


Repeater Element Reference in HTML Template

:::(Info) (NOTE) If you change the code of a repeater element after you have inserted the placeholder into the template, you need to change the start and end tag of the element in the template as well. Otherwise error messages will occur when creating the report document. ::: ### Example To illustrate how repeater elements work, let's suppose you have a [Datasource](/release34/docs/introduction-to-datasources) that contains a field named Country which contains three values: Austria, Germany, and Switzerland. You have created a repeater element with a code CountryRepeater and designed the following template:


Example Template

In between the two repeater tags there is some text that references a [Chart Element ](/release34/docs/chart-element)with code BarChart that contains a bar chart from the datasource. When the report document is created, Mail & Deploy identifies the repeater references in the template and first queries the values over which to create repetitions; in our example we have four repetitions, one for each country. The portion within the template is copied so that there are for instances within the template. Mail & Deploy then takes the first repetition value (the country Austria) and filters the data model to that value. Then it replaces all report elements within the first instance of the portion; in our example this means that the bar chart will be processed. When processing that bar chart element - as stated previously - the data model of the associated datasource is filtered to the country Austria. Then Mail & Deploy proceeds with the second repetition value and does the same thing for the second portion within the template etc until at the end of the repetition all four countries have been processed.

Was this article helpful?

What's Next