MailMerge Class Settings Explained

The TXTextControl.DocumentServer.MailMerge class ╰ TX Text Control .NET Server for ASP.NET
╰ DocumentServer Namespace
╰ MailMerge Class
The MailMerge class is a .NET component that can be used to effortlessly merge template documents with database content in .NET projects, such as ASP.NET web applications, web services or Windows services. provides several settings to control the merging process and formatting in the resulting document. There are various switches to control how text fields, blocks, images and blank lines are handled. This article gives an overview of when and how to use which option.

We will look into four different switches:

1. TXTextControl.DocumentServer.MailMerge.RemoveEmptyFields property ╰ TX Text Control .NET Server for ASP.NET
   ╰ DocumentServer Namespace
   ╰ MailMerge Class
   ╰ RemoveEmptyFields Property
   Specifies whether empty fields should be removed from the template or not.
2. TXTextControl.DocumentServer.MailMerge.RemoveEmptyLines property ╰ TX Text Control .NET Server for ASP.NET
   ╰ DocumentServer Namespace
   ╰ MailMerge Class
   ╰ RemoveEmptyLines Property
   Specifies whether text lines which are empty after merging should be removed from the template or not.
3. TXTextControl.DocumentServer.MailMerge.RemoveEmptyBlocks property ╰ TX Text Control .NET Server for ASP.NET
   ╰ DocumentServer Namespace
   ╰ MailMerge Class
   ╰ RemoveEmptyBlocks Property
   Specifies whether the content of empty merge blocks should be removed from the template or not.
4. TXTextControl.DocumentServer.MailMerge.RemoveEmptyImages property ╰ TX Text Control .NET Server for ASP.NET
   ╰ DocumentServer Namespace
   ╰ MailMerge Class
   ╰ RemoveEmptyImages Property
   Specifies whether images which don't have merge data should be removed from the template or not.

To show the various settings, the same data source basis and template is used and will be slightly changed to illustrate different scenarios. The following JSON is used as the data source:

The following screenshot shows the simple template with text fields and a merge block highlighted in red:

Removing Empty Fields

In the first scenario, we would like to remove fields that are empty. This happens, if no data field can be found in the data source that matches the field name in the template. By default, the RemoveEmptyFields property is true, so that the text of empty fields is removed automatically.

The following code is used to merge the template with the sample JSON data source:

When passing all field values from the data source, the results would look similar to the following screenshot:

Now, we will remove one field Street from the data source:

In code, the RemoveEmptyFields property is set to false:

The resulting document is shown in the next screenshot:

Removing Empty Lines

Based on the previous example, we keep the Street field deleted from the data source and the RemoveEmptyFields is not set (by default true). The resulting document would contain an empty line where the empty field was:

By setting the RemoveEmptyLines property to true, the complete empty line will be removed. This is done, if no other content exists in the same line and an empty line would be created:

Removing Empty Blocks

In case, the data is missing a block, the RemoveEmptyBlocks property can be used to determine whether a block should be removed from the document completely. This concept can be used to conditionally remove content from a document.

In our data source, we will remove the complete merge block data:

The following code is used to create the document and to set the RemoveEmptyBlocks to true:

The complete block part is removed. In our sample, the table header is still visible. In order to remove the table header as well, the header should be part of the merge block or should be part of a hierarchical nested block. If the data of the parent table is missing, the complete merge blocks (including child blocks) are removed.

Removing Empty Images

For the next sample, we will insert an image placeholder into the template. If merged without any settings, the image placeholder will be still part of the template, even if there is no explicit data in the data source matching the image placeholder name:

When setting the RemoveEmptyImages property to true, the image will be removed after the merge process, if no associated data field has been found in the data source:

Test this on your own with any .NET product of TX Text Control. The MailMerge class is available for all platforms including Windows Forms, WPF and ASP.NET.