Now that we have a couple of new and shiny templates, what do we do it them? Let's assume we want to create a telephone bill. We want to email it to the customer directly after creation, but—for legal reasons—the customer also receives a hard copy, printed on company letter paper. This means, the document generated for emailing and the one generated for printing differ in that the latter must not have a header, since that's already pre-printed on the company letter paper. Using IncludeText fields this is easy to accomplish.

Let's get ourselves equipped!

Besides a couple of templates, all we need is a little bit of application logic. In case you haven't created any templates of your own yet, you can use these:

template.docx (8.25 kb)

sub_template.docx (16.32 kb)

There are three different ways to toggle the inclusion/exclusion of sub-templates, when using IncludeText fields with LiveDocx. Let's take a look at 'em!

Using SetIgnoreSubTemplates()

The default for LiveDocx is to include sub-templates. I.e. when there's an IncludeText field in your template pointing to an existent sub-template, the sub-template is inserted at the corresponding position into the template holding the reference during the merge process.

To experience this yourself using the above templates, make sure to put the sub-template file into your server-side user directory as 'sub_template.docx' before you start merging. If you don't want to spend time on generating merge data, simply set it to null, i.e. SetFieldValues(null), and create the document. The resulting document contains a headline and an image coming from the sub-template.

If you need to exclude the sub-template, say for printing on company letter paper, there is just one more line of code for you to type. A call to SetIgnoreSubTemplates() using true as argument does the trick, i.e. SetIgnoreSubTemplates(true).

That was simple, wasn't it?

Using an empty sub-template

Obviously, another way to prevent anything from being inserted into the main template, is to replace the sub-template with an empty document. Please note, that the empty sub-template must not be a completely empty file but a valid doc, docx, rtf or txd file without contents. Big difference!

Deleting the sub-template

Also, if you do not upload the sub-template to the LiveDocx server or delete it before merging, the resulting document won't contain the contents of the sub-template—obviously. This is to prevent the merge process from crashing, in case you forget to put the sub-template in place, but can be used to toggle off the sub-template, too.

Playtime

For the impatient, here's a .NET project to try the things described above right away:

IncludeTextSample.zip (41.34 kb)

The above archive contains a VS.NET project. All you need to do is, double-click the .csproj file to fire up Visual Studio. Then, simply run the project, enter your LiveDocx credentials in the text fields and hit one of the buttons entitled 'Don't include' or 'Include'. After a few seconds the resulting document should open automatically. Feel free to play around with the source code to explore the possibilties LiveDocx offers to you.