repeat (DOCX)

A Word content command that iterates through all items of a Collection and produces a copy of its host content control, documents contents included, for every item in the Collection. Any other Word content commands of lower priority that are in the host content control, as well as content commands within the copied document contents, are also copied and evaluated on each round of the iteration, with one of the items of the Collection as a variable in the context for these commands to make use of.

This command produces a local variable context for the Word content commands evaluated within the iteration rounds. This local context's primary feature is that it contains one of the Collection's items for the other content commands to access. A new context is created at the start of every round of the iteration process and then terminated at the end of the round.

This attribute has a priority of 100.

Syntax:

repeat(value,var,varStatus,roundTest)

With required attributes only:

repeat(value,var)

Attributes

#1 - value

Required

Value type

EL-evaluated

Yes

Collection, Map, Data Item

Yes

This attribute defines the container whose contents the command will iterate through. While this container is primarily expected to be a Collection, two other types of values are also accepted.

The three types are handled in the following ways:

If the value is a Collection, repeat iterates through the items in it in their proper order.
If the value is a Map, repeat iterates through its entries. The item of every round is therefore a Map entry that allows both the key, and the value to be accessed. Note that the order in which the entries appear is, in most cases, not consistent and random.
If the value is a Data Item, repeat performs just one loop round, with the Data Item being the item of the round.

#2 - var
Required	Value type	EL-evaluated
Yes	String	No
The value of this attribute defines the name of the local context variable that holds the current item of the loop.

#3 - varStatus

Required

Value type

EL-evaluated

No

String

No

Defines the name of the variable that holds a Loop Status value. Loop Status has the properties count, first, and last ad index. A new value is generated for every iteration of the loop.

Property count is the number of iterations starting from 1.
The property index is the same as the count, with the difference that it starts from 0.
Property first is a Boolean true during the first round of the loop. Note that if roundTest causes the first item of the iteration to be skipped, this will never be true.
Property last is a Boolean true during the last round of the loop. Note that if roundTest causes the last item of the iteration to be skipped, this will never be true.

#4 - roundTest

Required

Value type

EL-evaluated

No

Boolean

Yes

This attribute can be used to define a condition for skipping certain iteration rounds. This attribute's expression is evaluated at the start of every round and if it doesn't resolve into true, the current item and loop round is skipped, resulting in no copy of the content being produced.

If undefined, no iteration rounds are skipped.

Examples

Use repeat for presenting a Collection's contents on the document. However, do note that the table command is generally more suitable for presenting Collection contents on a table - repeat works for multiplying tables as a whole, though.

As repeat copies is host content control as well, a lower priority command like out can be used in the same content control title to output the looped content. The following example could be used as a content control around a paragraph to output names of Opportunity records in a Collection found in the "opportunities" variable.

CODE

repeat(opportunities,opp) out(opp.Name)

The fourth attribute roundTest attribute exists as the if command has higher priority than repeat and therefore cannot be used in the same title to make items individually conditional. It is, however, possible to use it in another content control that is inside repeat's host content control. Note that in roundTest it is possible to use the Loop Status value created through the third attribute varStatus or the current item of the iteration. Of the following examples, the first would only loop through non-closed Opportunities and the second only through the first 20.

CODE

repeat(opportunities,opp,,!opp.IsClosed)
repeat(opportunities,opp,status,status.index < 20)