Using Arrays in your XpressDox templates
Arrays are similar to variables, and have a very similar set of functions to manipulate them. XpressDox arrays can be indexed using data of (almost) any type for the index – i.e. you can index with strings or numerics, or both in the same array. For this reason instead of using the term “index” we use the term “key”.
An example would be:
Suppose the data contain a repeater called Child. And one of the attributes of a child is the name of the school that they attend. You (the template author) would then like to list each school attended by any of the children, and the number of children attending each such school. Here’s how you would do it:
«ForEach(Child)»
«ArrayIncrementVr(‘schools’,SchoolName)»
«Comment(this creates an array called “schools” and adds an element to it
with the name of the school which is contained in the “Child/SchoolName” data element (and increments that value
by 1 which means it starts its life with a value of 1). If the array element for that SchoolName already exists,
then the value of that element is incremented by 1. The net result is that after this ForEach, the value of the
array element named after each school will be number of children attending that school)»
«End()»
«SetVr(‘Ix’,1)»
«RepeatWhile(GetV(‘Ix’) <= ArrayCount(‘schools’))»
The number of children at school «ArrayKeys(‘schools’,GetV(‘Ix’))» is «ArrayValues(‘schools’,GetV(‘Ix’))»
«IncrementVr(‘Ix’)»
«End()»
Other Array Functions:
The array functions not used in the above example (but found in the Command Editor list) are analogous to the similar-sounding functions for manipulating XpressDox variables. For example:
«ArraySetV('schools','Pinelands High',3)»: if this applied to the above example, it would mean that 3 children attend the school called ‘Pinelands High’.- Suppose an array called ‘things’ has an element whose key is ‘arbitray’ which has a (semi-colon delimited) list of arbitrary things in it. To add another arbitrary thing, you would use:
«ArrayAppendVr('things','arbitrary',NewThing,';')». This will add a string consisting of the value of data element NewThing and a semi-colon to the end of the ‘arbitrary’ element of the ‘things’ array. - To output the above list of arbitrary things you would use
«ArrayGetV('things','arbitrary')»</code?. - Of course, the array ‘things’ would probably have more elements than just ‘arbitrary’, otherwise you would just use a variable for this. The example of counting the schools in the first section is thus an important use of the array as against a set of variables (although, with a bit of ingenuity it would be possible, but tedious, to get the same functionality using only variables).
Create an Array from a delimited string.
In this example the string is an address, each part of the address is delimited by a comma and the aim is to print it all over multiple lines. The reverse of this is the «InsertUnformattedLongText()» command but we don’t have a command to take a string and print it over multiple lines. It can be achieved in an array like this:
«ArraySetFromString(‘addressArray',Address,’,’)»
«SetVr('count',1)»
«RepeatWhile(GetV('count') <= ArrayCount('addressArray'))»
«Trim(ArrayGetV('addressArray',GetV('count')))»
«IncrementVr('count')»
«End()»
