Working with repeated elements – Part 1

One of XpressDox’s strong points is the smoothness with which it caters for repeating data.

Capturing and formatting repeated data

To illustrate this, we will imagine the example of a Will (i.e. “Last Will and Testament”) where the names of the children are repeated. A typical template would have this snippet:

My heir«When(count(Child) > 1,s are, is)» my child«When(count(Child) > 1,ren)», viz. «Foreach(Child)»«When(position() > 1, AND )»«Firstname» «Surname» (age «Age» years) of «AddressLine1», «AddressLine2»«End()»

A snippet like this in a template would have a number of effects:

• The «Foreach(Child)» would signal to XpressDox that the data element Child will be repeated. Then, each Child will have its own Firstname, Surname, Age, and two lines of address data elements. This XpressDox knows because those data elements appear between «Foreach(Child)» and «End()».
• The data capture dialog would automatically be constructed with an area for capturing these repeated data elements, and would look like this:
• The command «When(position() > 1, AND )» will ensure that the word “AND” (with a space on either side) will precede every heir’s description except for the first.

A typical merged result for this snippet, where there are two children, would look like this:

My heirs are my children, viz. Harry Smith (age 31 years) of One Long Road, Winelands AND Mary Jones (nee Smith) (age 25 years) of 33 Tortoise Avenue, Marylebone

If Harry were an only child, the result would read:

My heir is my child, viz. Harry Smith (age 31 years) of One Long Road, Winelands

Selecting a particular Child

Continuing with the example: during the course of the winding up of the estate, it might become necessary to write to each of the heirs separately, and for this purpose one or more letter templates are set up where the addressee information needs to refer to just one of the heirs.

The simplest way of marking up the addressee portion of such a letter template would be:

«Child[$ChildNumber]/Firstname» «Child[$ChildNumber]/Surname»
«Child[$ChildNumber]/AddressLine1»
«Child[$ChildNumber]/AddressLine2»

• This would cause XpressDox to include an area for the capture of a data element called ChildNumber.
• The square brackets [] notation causes a process which could be called an “array element selection”. Because the ChildNumber data element is captured as a number, it will cause the Child element with that number to be selected.
• The / between data element names indicates that the data element after the / is a sub-element of the preceding element, which is then the parent element. In this way the Child element is the parent element of Firstnames, Surname, Age and the two addresses.
• When data elements are referred to within the scope of a «ForEach» command (i.e. between the ForEach and its End()), then the parent data element is inferred as the data element defined in the ForEach command. Because of this inference, looking at the first snippet, it wasn’t necessary to refer to the Child’s Firstname element as «Child/Firstname» (in fact it would be incorrect to do so).

The XpressDox terminology for a «ForEach» together with its «End()» and the text in between is a ForEach block. Similarly we talk about an If block and an Else block.

Other ways of using the array element selection (square bracket notation) would be the following, where the names of the minor children (i.e. those with ages less than 18 years) are to be listed:

My minor child«When(count(Child[Age < 18]) > 1,ren are, is)» «ForEach(Child[Age < 18])»«When(position() > 1, AND »«Firstname» «Surname»«End()»

Referring to a repeated element when you know at template authoring time what its position is, is a simple case of typing in a constant value for the position:

My firstborn heir is «Child[1]/Firstname» «Child[1]/Surname».

And, just for completeness, the last child would be (assuming the chidren were entered in descending order of age):

My youngest is «Child[last()]/Firstname» «Child[last()]/Surname».

Referencing Non-repeating elements within a ForEach block

At this point it makes sense to discuss another aspect of repeated elements: what if, from within a ForEach block you want to refer to a data element that is NOT a sub-element of that Child data element? This is a pertinent question because the last bullet point above says that within the scope of a ForEach(Child) block the parent data element of each data element referenced (i.e. Firstname, Surname, etc.) is inferred as the Child data element. The question is: how can we refer to a data element inside a ForEach block without having the data element being inferred as a sub-element of the Child element?

To illustrate this, suppose that the testator dictates that each heir should be given the same fixed amount of money, but for some reason (if only for this example), to be totally pedantic the drafter of the Will decides to list the heirs by name and next to each name reflect this one fixed amount. We would probably expect a template snippet to look something like this:

«ForEach(Child)»«When(position() > 1, AND )»To «Firstname» «Surname» the amount of $«Share»«End()».

However, seeing a the Share inside the scope of the ForEach like this, XpressDox would want to capture a separate Share data value for each Child, which is not what is intended here.

What IS intended is that the Share is captured once for the entire Will template, and that this data element is referred to inside the scope of the ForEach block. This can be achieved in one of the following ways:

• If the Share data element is referred to in a Fillpoint anywhere in the template but NOT inside a ForEach block then XpressDox will capture the Share element in the data set at the correct level (i.e. the level of the parent data element of the Child data element).
• Otherwise, XpressDox can be forced to capture the Share data element at the correct level in the data set by use of the command «CaptureDataElement(Share)».

Then, the previous snippet must be changed to read:

«ForEach(Child)» «When(position() > 1, AND )»To «Firstname» «Surname» the amount of $«../Share»«End()».

Note the ../ notation – it is very reminiscent of the Windows (and DOS) file path notation, i.e. where ../ indicates “move up to the previous folder in the file path”. In XML terms it means “move up one level in the data element path”.

A look at what a specific XML data set for this example would look like might be instructive. Here it is:

<ChildNumber>3</ChildNumber>
<Share>100,000</Share>
<Child>
<Firstnames>Harry</Firstnames>
<Surname>Smith</Surname>
<AddressLine1>One Long Road</AddressLine1>
<AddressLine2>Winelands</AddressLine1>
<Age>31</Age>
</Child>
<Child>
<Firstnames>Mary</Firstnames>
<Surname>Jones (nee Smith)</Surname>
<AddressLine1>33 Tortoise Avenue</AddressLine1>
<AddressLine2>Marylebone</AddressLine1>
<Age>25</Age>
</Child>

Defining Repeating Elements outside a ForEach Block

This is the converse of the previous example.
A case where this would be used is where, for example, the gender of each child is to be captured, using a ChooseFromRDBList command. There are numerous ForEach blocks in the template already, and so the question is in which of them should the «ChooseFromRDBList(Gender,M,F)» go? The short answer is that it can go into any of them (even into a ForEach block where the Gender data element is not used!).
But another option is to place the command outside of ANY ForEach block. In order to indicate to XpressDox that this Gender data element being captured in the RDB List refers to the Child data elements and not to the global Will data element, the path notation introduced above is used. The command would then read:

«ChooseFromRDBList(Child/Gender,M,F)»

This technique can be used with the ChooseFromList, ChooseFromSamples, ChooseUsingCheckBox, Help and CaptureDataElement commands.