Showing Fields
A simple template document loading a single specific instance.
{ MERGEFIELD with load Person [Peter Smith] }
{ MERGEFIELD [Age] }
{ MERGEFIELD [First Name] }
{ MERGEFIELD [Last Name] }
Style and colour
Any formatting such as bold or colour that is applied to the Word field (when in Field Code mode) is applied to the output result. For example:
{ MERGEFIELD [First Name] }
Loading all records of an object
To load all records of an object, a block of the template document gets repeated. Start the block that gets repeated with the 'with' command, then follow it with 'all' to indicate we're loading all records. Note: All is a calculation function therefore you need to put the definition name in round brackets ().
{ MERGEFIELD with all ([Person]) }
Name: { MERGEFIELD [First Name] } { MERGEFIELD [Last Name] }
Age: { MERGEFIELD [Age] }
{ MERGEFIELD end }
The content that gets repeated is whatever is between the starting instruction, and the 'end' instruction.
This includes any paragraph separators. The result may be contained within a single paragraph, or may span multiple paragraphs.
Note that if an 'end' keyword is not specified, then the block will implicitly end at the end of the document (or some other appropriate place).
Repeating within a paragraph
{ MERGEFIELD with all ([All Fields]) } { MERGEFIELD Name }{ MERGEFIELD end }.
Repeated content with exactly one paragraph separator
{ MERGEFIELD with all ([Person]) }
Welcome, { MERGEFIELD [First Name] } { MERGEFIELD [Last Name] }.{ MERGEFIELD end }
In this example, the start of the instruction is immediately followed by the paragraph break, which is repeated at the start of each paragraph. The 'end' is on the same line as the paragraph itself, to ensure that the following paragraph doesn't get included in repeated content. (So we only get one paragraph break instead of two).
Repeated content in a bullet or numeric list
A bulleted list
* { MERGEFIELD list all ([Building]) }{ MERGEFIELD Name }
A numbered list
1. { MERGEFIELD list all ([Building]) }{ MERGEFIELD Name }
For bullet lists it is usually more convenient to place the instruction within the bullet using the 'list' instruction. Note that these do not need to be closed with an 'end'.
Note that this example also illustrates the more general pattern for instructions that show repeated content. That is: first the display mode is set, then the data source is set. In this case 'list' is the display mode, and 'all Building' is the data source.
See also: list
Repeated content in tables
On the first column of a row, specify a repeating instruction with 'rows' as the display mode. If the 'end' instruction is not specified, then it will implicitly end at the end of the row.
| First Name | Age |
|---|---|
| { MERGEFIELD rows all (Person) }{ MERGEFIELD [First Name] } | { MERGEFIELD [Age] } |
Performing calculations
A variety of calculations can be performed. Refer to the Calculated Fields documentation.
{ MERGEFIELD Quantity * [Cost per Unit] }
Table Sums
It is possible to use the Word SUM field feature to perform sums and some other aggregate operations.
| First Name | Age |
|---|---|
| { MERGEFIELD rows all (Employee) }{ MERGEFIELD [First Name] } | { MERGEFIELD [Age] } |
| { =SUM(ABOVE) } |
Note that the SUM value is not computed by the document generator, rather this is a feature of Word.
After opening the result document, follow these steps:
- Ctrl+A (select the whole document)
- F9 (updates the field values, for the whole selection)
- Alt+F9 (toggle document from viewing field codes to field value ... if you don't see the sum already)
Table of Contents
Similar to using sum-above, the existing Word table-of-contents (TOC) can be used. Follow these steps:
- Include a Word heading in your repeated section.
- Include a Word table of contents at the top of the template.
- When the document is generated, the heading will be repeated - once for each value, but the TOC isn't updated yet
- Open the result in Word, then (as above) Ctrl+A, F9, and Alt+F9 if necessary.
Following Relationships
If an entity is already in context, you can show the name of a related entity by just using the name (or the from-name or to-name) of that relationship - exactly the same as you would with a field:
Example 1: Simply showing the name of a related entity.
{ MERGEFIELD with load Person [Peter Smith] }
Name: { MERGEFIELD [First Name] }
Manager: { MERGEFIELD [Manager] }
Organization: { MERGEFIELD [Works for Organization] }
You can switch the content to a related entity by using the 'with' keyword.
Example 2: Following all instances of a relationship of a specific resource. The paragraph is repeated for each related entry.
{ MERGEFIELD with load Person [Peter Smith] }
Direct reports of Peter:
{ MERGEFIELD with [Direct Reports] }
{ MERGEFIELD [First Name] } { MERGEFIELD [Last Name] }
{ MERGEFIELD end }
Example 3: Following all instances of a relationship, for all instances of a type. The bullet point is repeated for each related entry.
{ MERGEFIELD with all (Manager) }
Manager name: { MERGEFIELD [First Name] } { MERGEFIELD [Last Name] }
Direct reports:
* { MERGEFIELD list [Direct Reports] }{ MERGEFIELD [First Name] } { MERGEFIELD [Last Name] }
{ MERGEFIELD end }
Include a block of text, if there are values for a particular relationship
In the above example, the text 'Direct reports:' would appear even if the manager has no direct reports. We can wrap that whole section in an 'if' keyword, to test if there are any related entities first.
{ MERGEFIELD with all ([Manager]) }
Manager name: { MERGEFIELD [First Name] } { MERGEFIELD [Last Name] }
{ MERGEFIELD if [Direct Reports] }
Direct reports:
* { MERGEFIELD list [Direct Reports] }{ MERGEFIELD [First Name] } { MERGEFIELD [Last Name] }
{ MERGEFIELD end }
{ MERGEFIELD end }Inserting a Chart
Data-drived charts can be generated and inserted into Word documents. Calculations can also be used to filter the chart to only include certain records.
{ MERGEFIELD chart([Whatever] with [Created By]: currentuser( ) ) }See: insert chart