A new feature in LiveDocx MailMerge API 1.1 is merging IncludeText fields. With IncludeText fields you can insert sub-templates into your main template during the merge process. This comes in handy, e.g. when you want to replace whole parts of your resulting document with something else under certain conditions. Another common application is to leave the document header blank, when printing onto pre-printed letter paper, but to include the document header, when sending the document by email. In this short article I'll show, how to build templates that enable you to use this new LiveDocx feature.

Prerequisites

To get started, you need at least two templates. The first one is your main template, which contains the IncludeText field(s), and the second one is the sub-template. Sub-templates may contain everything normal templates may contain, i.e. formatted text, fields (including IncludeText fields) and merge blocks. Building circular references with IncludeText fields won't work, of course. So, be sure to check your references, before merging.

The sub-template(s) have to be located in your template directory on the LiveDocx server. UploadTemplate() is your friend.

Creating Templates

All that's left to do now is to insert an IncludeText field into the main template. You can do this using MS Word or the TX Template Designer (LiveDocx Edition), which will be available here for download shortly. Instead of setting the field value to an absolute path like MS Word suggests, just insert the filename of the desired sub-template without leading path but including the file extension.

Please note, that MS Word will display an error message (something about the document name being invalid—depending on your system language). That's ok. MS Word expects an absolute path as argument to the IncludeText field, but LiveDocx will know, how to handle the document correctly.

That's it. There's nothing more to it. Now, you are good to go.

The next article on IncludeText fields will explain, how to merge or ignore sub-templates under certain conditions.