The TXTextControl.DocumentServer.MailMerge class 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
2. TXTextControl.DocumentServer.MailMerge.RemoveEmptyLines property
3. TXTextControl.DocumentServer.MailMerge.RemoveEmptyBlocks property
4. TXTextControl.DocumentServer.MailMerge.RemoveEmptyImages property

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:

[
  {
    "Id": 1,
    "Name": "Sales Report",
    "Customer": {
      "Id": 1,
      "Name": "Text Control, LLC",
      "Street": "6926 Shannon-Willow Rd",
      "ZipCode": "28226",
      "City": "Charlotte",
      "Country": "United States"
    },
    "Contacts": [
      {
        "Name": "Paulsen",
        "FirstName": "Carl",
        "Email": "sales@textcontrol.com",
        "Phone": "7045447445"
      },
      {
        "Name": "Franklin",
        "FirstName": "Paul",
        "Email": "support@textcontrol.com",
        "Phone": "7045447445"
      }
    ]
  }
]

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:

textControl1.Load("template.tx", TXTextControl.StreamType.InternalUnicodeFormat);
string data = System.IO.File.ReadAllText("data.json");

using (TXTextControl.DocumentServer.MailMerge mailMerge =
       new TXTextControl.DocumentServer.MailMerge())
{
    mailMerge.TextComponent = textControl1;
    mailMerge.MergeJsonData(data);
}

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:

[
  {
    "Id": 1,
    "Name": "Sales Report",
    "Customer": {
      "Id": 1,
      "Name": "Text Control, LLC",
      "ZipCode": "28226",
      "City": "Charlotte",
      ...

In code, the RemoveEmptyFields property is set to false:

textControl1.Load("template.tx", TXTextControl.StreamType.InternalUnicodeFormat);
string data = System.IO.File.ReadAllText("data.json");

using (TXTextControl.DocumentServer.MailMerge mailMerge = new TXTextControl.DocumentServer.MailMerge())
{
    mailMerge.TextComponent = textControl1;

    mailMerge.RemoveEmptyFields = false;
    mailMerge.MergeJsonData(data);
}

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:

textControl1.Load("template.tx", TXTextControl.StreamType.InternalUnicodeFormat);
string data = System.IO.File.ReadAllText("data.json");

using (TXTextControl.DocumentServer.MailMerge mailMerge = new TXTextControl.DocumentServer.MailMerge())
{
    mailMerge.TextComponent = textControl1;
    mailMerge.RemoveEmptyLines = true;
    mailMerge.MergeJsonData(data);
}

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:

[
  {
    "Id": 1,
    "Name": "Sales Report",
    "Customer": {
      "Id": 1,
      "Name": "Text Control, LLC",
      "Street": "6926 Shannon-Willow Rd",
      "ZipCode": "28226",
      "City": "Charlotte",
      "Country": "United States"
    }
  }
]

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

textControl1.Load("template.tx", TXTextControl.StreamType.InternalUnicodeFormat);
string data = System.IO.File.ReadAllText("data.json");

using (TXTextControl.DocumentServer.MailMerge mailMerge = new TXTextControl.DocumentServer.MailMerge())
{
    mailMerge.TextComponent = textControl1;
    mailMerge.RemoveEmptyBlocks = true;
    mailMerge.MergeJsonData(data);
}

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:

textControl1.Load("template.tx", TXTextControl.StreamType.InternalUnicodeFormat);
string data = System.IO.File.ReadAllText("data.json");

using (TXTextControl.DocumentServer.MailMerge mailMerge = new TXTextControl.DocumentServer.MailMerge())
{
    mailMerge.TextComponent = textControl1;
    mailMerge.RemoveEmptyImages = true;
    mailMerge.MergeJsonData(data);
}

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.