Document per Repeated Item (new style)

Problem Statement

Suppose you have an application which requires that one or more parties sign a suretyship document, with the requirement that each party signs their own document, not that they all sign the same document.

The first thing to do is set up the suretyship template, with the relevant fixed text, etc., just like any other template.  Suppose the template reads something like this:

I, «SuretyFirstNames» «SuretySurname» (Born on «FormatDate(SuretyDOB, “MMMM dd yyyy”)») hereby declare 

lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere und so weiter …

Signed: «SuretyFirstNames» «SuretySurname»

Of course, this will only produce the information for one surety, and doesn’t indicate in any way that there can be more than one surety.

The normal way of indicating repeating data to XpressDox is the «ForEach» command, so it is tempting to try the following:

«ForEach(Surety)»I, «SuretyFirstNames» «SuretySurname» (Born on «FormatDate(SuretyDOB, "dd MMMM yyyy")») hereby declare

lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere und so weiter …

Signed: «SuretyFirstNames» «SuretySurname»
«End()»

But, of course, this will repeat the sureties’ information for all of the sureties one after the other on the same document.

One Document for each Repeater

In the above code snippet, the ForEach() defines the context of all the data elements before the End() – i.e. that they all belong to one repeater called Surety. The idea of the context is important, and can be applied to a whole template in the following way.

Firstly, the document which should be produced for each Surety must be authored in a template much like the first example, i.e. something like:

I, «SuretyFirstNames» «SuretySurname» (Born on «FormatDate(SuretyDOB, "MMMM dd yyyy")») hereby declare

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
Nunc viverra imperdiet enim. Fusce est. Vivamus a tellus.
Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin pharetra nonummy pede. Mauris et orci.

Signed: «SuretyFirstNames» «SuretySurname»

Let’s assume that a document like this is saved as an XpressDox template, and called DeclarationBySurety.xdtpx. Then, in your main document, you put the following:

«ForEach(Surety)»
«MergeTemplate('DeclarationBySurety.xdtpx','Surety',position())»
«End()»

In the above MergeTemplate, the ‘Surety‘ and position() provide the context for the entire DeclarationBySurety.xdtpx template. By definition of the MergeTemplate function, each of the MergeTemplates in the ForEach will cause a separate document to be created.

One Section for each Repeater in the Same Document

Also, you could use the same DeclarationBySurety template to create one long document with declarations for all of the sureties in the same document, by replacing MergeTemplate with IncludeTemplate in the above, getting this:

«ForEach(Surety)»
«IncludeTemplate(DeclarationBySurety)»
«Comment(Include XpressDox and Word commands here to insert page or section breaks after each Declaration. See Working with Section Breaks for information on this.)»
«End()»

 

Filtering

Suppose you want to produce a separate document for each of the Sureties, but only for the sureties born before a particular date (July 1 2001). Have a look at this:

«ForEach(Surety)»
«If(DateAsNumber(SuretyDOB) < 20010701)»
«MergeTemplate('DeclarationBySurety.xdtpx','Surety',position())»
«End()»
«End()»

Note that you might be tempted to write (using XpressDox’s powerful XPATH capabilities):
«ForEach(Surety[DateAsNumber(SuretyDOB) < 20010701])»
«MergeTemplate('DeclarationBySurety.xdtpx','Surety',position())»
«End()»
The problem with this is that the position() function gives the position of the Surety relative to those conforming to the condition in the predicate (i.e. the bits between the [ and ]), whereas the MergeTemplate needs the context to reflect the position() in the complete list of Surety repeaters.

Naming each assembled document

Using the SetSavedDocumentFileName on the template you are merging is a way to name each document correctly, however you need to create a data element first and then use that command. This is the way to do it, remembering that this code goes onto the template that is being merged, not on the template that contains the MergeTemplate command.

«CreateDataElement('FileName',concat('Surety by',SuretyFirstNames))»
«SetSavedDocumentFileName(<FileName>)»
«SetSavedDocumentFolder(.\Documents)»

This technique is slightly different from the usual way of naming assembled documents and it needs to be done this way to ensure that each document does not get the same file name.

The Interview

The way that MergeTemplate functions, is that no interview is prepared for the data elements used in the template being merged – in this case the DeclarationBySurety.xdtpx. This means that all the data elements must be assigned a value in the template which calls the MergeTemplate function. The values can be assigned by retrieving them from a data source (The ChooseFromDataSource Command, or The LinkToDataSource Command, or The IncludeDataSourceData Command), or letting the user capture them in the interview.

PDF Forms

What if the document that you want repeated once for each repeating item is actually a PDF Form?

The Filling PDF Forms article describes how a PDF Form can be “prepared” for use by XpressDox. In the Surety case above, if one PDF Form were required per surety, then the PDF Form would be prepared with data elements referring to the elements inside the repeating instances, i.e.

SuretyFirstNames, SuretySurname and SuretyDOB.

Then, as in the above ForEach, the function MergePDFForm is used instead of MergeTemplate, with slight modifications for the PDF case, like this:

«ForEach(Surety)»
«MergePDFForm('DeclarationBySurety.pdf',concat('Surety(',position(),').pdf'),'RemoveFormFields','Surety',position())»
«End()»

The arguments passed to the MergePDFForm function are as follows:

• ‘DeclarationBySurety.pdf’ – the PDF form that has been prepared.
• concat(‘Surety(‘,position(),’).pdf) – will produce one document for each Surety with the names ‘Surety(1).pdf’, ‘Surety(2).pdf’, etc.
• ‘RemoveFormFields’ – the form fields will be filled and then flattened so that the end user can’t change the values.
• ‘Surety’ and
• position() – tell XpressDox that data elements in the PDF Form are relative to the instance of the ‘Surety’ repeater at the position specified by position().