In some situations, you might need to generate a list of field values separated by commas in a Word document. For example, you might be creating a simple summary document for each household, with the household name at the top, and the names of the children in the household separated by commas, as in the screenshot below.
The key issue here how to create the list of first names. The household name comes from the Account object, and can easily mapped to a single field in that object. But the list of children comes from the related list of Contact records. The need is to put together a comma-separated list of the first names of the contacts, with the last pair of first names separated by “and”.
Solution #
To make this happen, you will need to use the combine function.
- Create a template field with five parts, separated by colons: the Record group name, the name of the sublist field whose values should be combined, the word
combine, the default separator (comma in the above example), and the last separator (the word “and” in the above example). Below is a screenshot of the template.
The parts of the combine field are as indicated below.
- When building the merge action, map the fields to the sublist as indicated in the sublists documentation. Note that you don’t have to create a TableStart/TableEnd pair for the sublist. The existence of the “combine” function tells the generator that you need a sublist, with a record group named
Members(in this example). So it shows the record group panel, as in the screenshot below.
Examples and usage notes #
| Merge field | Examples of output | Comments |
«Members:First name:combine: and » |
Abraham and Jessica and Maria |
Since no last separator is specified, the separator value and is used between all the parts. |
«Members:First name:combine:-» |
Abraham-Jessica-Maria |
The separator used is a minus sign. |
Some notes to bear in mind:
- The separator doesn’t always have to be a comma, it can be any text, as shown in the above examples.
- When using the separator parts, the entire text of the separator, including any spaces, will be used in producing the output text. In “Solution” screenshot above, note the presence of a space after the comma in the separator field, and spaces around the “and” in the last separator field. These produce the necessary spacing after the comma and around the “and” in the example output of the very first screenshot above. See also the examples below.
- The “last separator” part is optional. If it is omitted, the “separator” text is used between all the generated text values.
- The bits of text being combined are automatically deduplicated. Thus, in the above example, if there is more than one Contact with the same first name, that first name will appear only once in the combined list.
The Document Generator includes a means for producing sublists. But that is not adequate in the present situation, for two reasons. One, that the sublist mechanism requires the sublist records (the first names, in this case) to appear in a table, a bullet-list, a numbered list, or other similar block. And second, that mechanism doesn’t offer a way to selectively include separators between the data – the separators in this case being the comma and the word “and”.
To address this situation, the Document Generator provides a combine function that can be applied to a single field from a sublist, to produce text with embedded separators.
