TX Text Control sample template

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:

Loading...

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

TX Text Control sample template

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:

Loading...

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

TX Text Control sample template

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

Loading...

In code, the RemoveEmptyFields property is set to false:

Loading...

The resulting document is shown in the next screenshot:

TX Text Control sample template

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:

TX Text Control sample template

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:

Loading...

TX Text Control sample template

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:

Loading...

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

Loading...

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.

TX Text Control sample template

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:

TX Text Control sample template

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:

Loading...

TX Text Control sample template

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.