Howto: Mail Merge

The chapter Connecting to Databases showed you how to store the entire contents of a TX Text Control in a database field. For implementing mail-merge functionality, however, the requirements are different: The contents of database fields have to be inserted at specified positions in a previously prepared document.

This chapter shows how to use the DocumentServer.MailMerge class in Windows Forms projects to merge TXTextControl.ApplicationFields in template documents with data from various data sources. The MailMerge class encapsulates powerful mail merge capabilities in a ready-to-use component. The DocumentServer.MailMerge class is part of the TXTextControl.DocumentServer namespace.

Using the DocumentServer.MailMerge component, template documents containing MS Word merge fields can be easily loaded, merged with a DataSet or DataTable of the Microsoft .NET System.Data namespace and exported to the supported file formats of TX Text Control like Adobe PDF or DOCX.

It is possible to pass a DataTable containing different columns that covers the merge field names. The data rows of the table equals the number of created documents. Optionally, it is possible to create separate documents or to append the documents to one resulting document.

Single merge fields can be inserted that will be filled with database content. Additionally, repeating blocks can be defined in the template. These blocks will be repeated according to the number of passed data rows.

The DocumentServer.MailMerge component supports the most important standard merge fields of MS Word. Supported fields are: MERGEFIELD, INCLUDETEXT, IF and DATE.

In the first step, this article explains how to connect the MailMerge component with an instance of TextControl. The source code for the examples is contained in the subfolders MailMerge_Simple, MailMerge_Blocks and MailMerge_Nested_Blocks of the following directories:

Used TX Text Control controls:

Relevant API links:

Connecting MailMerge to TextControl

Sample: Simple Mail Merge

Sample: Mail Merge with Repeating Blocks

Sample: Mail Merge with Nested Repeating Blocks

Creating Templates using TX Text Control Words