Generally, IncludeText fields contain a reference to external documents that will be included during the mail merge process. That allows you to store a specific sub-template separately in order to reuse it in other templates.

But these fields can do much more. This article shows how to use the IncludeTextMerging event to inject dynamic formatted content. In this case, the Filename parameter of the IncludeText field can be used to save a specific identifier like an ID or a field name. Based on this value, we can decide which document or text should be inserted. This approach keeps the sub-templates more flexible as we do not need to store the actual name of each sub-template nor do we need to save the sub-templates physically.

Our sample template just contains two IncludeText fields and some text:

In the following code, this template is loaded, the IncludeTextMerging event is attached and merged. As we do not have any normal merge fields in the template, we can call the Merge method without a DataTable. Instead of passing data, null is passed.

mailMerge1.LoadTemplate("template.docx", TXTextControl.DocumentServer.FileFormat.WordprocessingML);
mailMerge1.IncludeTextMerging += new TXTextControl.DocumentServer.MailMerge.IncludeTextMergingHandler(
                                 mailMerge1_IncludeTextMerging);
mailMerge1.Merge(null, false);
mailMerge1.SaveDocument("results.pdf", TXTextControl.StreamType.AdobePDF,
                        new TXTextControl.SaveSettings());

Now the interesting part. In the IncludeTextMerging event, a new ServerTextControl instance is created to provide the formatted text. At this point, it is also possible to load a sub-template from a database or a physical file.

The event arguments return the Filename property of the IncludeText field which is used as an identifier in our scenario. A simple switch statement shows how to handle this argument. Based on the field's Filename value, different text is added to the temporary ServerTextControl. After some formatting operations, the content is saved in a byte array in the internal TX Text Control format. This byte array can be passed to the IncludeTextDocument property of the IncludeTextEvent arguments. The complete document will be inserted at the current field location.

void mailMerge1_IncludeTextMerging(object sender,
                                   TXTextControl.DocumentServer.MailMerge.IncludeTextMergingEventArgs e)
{
    TXTextControl.ServerTextControl tempTX = new TXTextControl.ServerTextControl();
    tempTX.Create();

    switch (e.Filename)
    {
        case "\field1":
            tempTX.Text = "Field 1 inserted at " + DateTime.Now.ToString();
            tempTX.Select(0, 7);
            tempTX.Selection.Bold = true;
            break;

        case "\field2":
            tempTX.Text = "Field 2 inserted at " + DateTime.Now.ToString();
            tempTX.Select(0, 7);
            tempTX.Selection.Italic = true;
            break;
    }

  byte[] data;

    tempTX.Save(out data, TXTextControl.BinaryStreamType.InternalUnicodeFormat);
    tempTX.Dispose();

    e.IncludeTextDocument = data;
}

Using this approach, you can insert complete documents or just dynamic formatted field text which is not possible using the normal merge fields. The idea of the merge field is that the formatting is part of the template and the merge process just replaces the text. The following screenshot shows the resultsing PDF document with the injected formatted text.

Download sample project

Feel free to post your questions or comments on this.