The commands used to handle repeating data are the ForEach, List and Ordinal commands.
The term repeating data would apply, for example, to a list of parties to an agreement, or to a number of lines on an invoice. The central issue with repeating data is that the number of repeated items (data elements) is not known at the time the template is authored, and so XpressDox offers these commands as a way of processing a variable number of repeated data elements.
a. ForEach: An example, listing the surname and first names of a number of parties is:
The parties are:
<<ForEach( party)>>Surname:<<surname>>
First names:<<firstnames>>
<<End()>>
The output of this snippet would look like:
The parties are:
Surname: Potter
First names: Harry
Surname: Jones
First name: Juliet
Surname: Basset
First names: Fred
b. Sort: This is actually a subcommand of the ForEach command. For example, to sort the above list by surname, the ForEach would look like:
The parties are:
<<ForEach(party,surname,ascending,text)>>Surname:<<surname>>
First names:<<firstnames>>
<<End()>>
In this example the parties would be listed in ascending order of surname. The ‘ascending’ and ‘text’ are the order and data type respectively, and these values could in fact have been omitted in this example, as they are the defaults. The other option for order is ‘descending’, and the other option for data type is ‘number’.
The output of the snippet would now look like:
The parties are:
Surname: Basset
First names: Fred
Surname: Jones
First name: Juliet
Surname: Potter
First names: Harry
c. List: A common way of listing the names of parties is all in one phrase (rather than the tabular form above), with a comma separating each pair of names except for the last two which are separated by the word ‘and’.
This is what the List command does and might look like this:
The parties are:
<<List(parties,firstnames surname,!, , and )>>
The names in our example would be rendered:
Harry Potter, Juliet Jones and Fred Basset
Note the ‘!’ in front of the comma. This is an escape character and is required before a comma, or left or right parenthesis whenever that character is required as is in the output text.
This is because the characters ‘,’ ‘(‘ and ‘)’ are used by XpressDox as command and function parameter list delimiters. This means that, if any of those three characters are required to be in the printed output (as is the case with the comma above), then they must be prefixed by !
d. Ordinal: Used within a ForEach to output the ordinal value (that is, ‘first’, ‘second’, etc.) of the position in the list of the current item:
<<ForEach(party)>>
The<<Ordinal(only ,first ,second ,third ,fourth ,fifth ,sixth ,subsequent )>>party is<<firstnames surname>>.
<<End(ForEach party)>>
This would result in something like this:
The first party is Fred Basset.
The second party is Harry Smith.
The third party is Ivan Bosman.
The fourth party is Maximilian Jones.
The fifth party is Johan Smit.
The sixth party is William Wilberforce.
The subsequent party is Mortimer Rodent.
The subsequent party is Petrus du Toit.
Notice how when there are more repeated items than the arguments to the Ordinal command cater for (in the above there are 7 arguments but 8 repeated items), then the last argument is used for the excess items.
In the case of only one party in the list, this would read:
The only party is Fred Basset.
If the Ordinal command above were coded as
<<Ordinal(,first ,second ,third ,fourth ,fifth ,sixth ,subsequent )>>
In other words, the first parameter to the command is empty, then in the case of only one party in the list, it would then read:
The party is Fred Basset.
