Mail merge is a concept that is used to create multiple documents from a single template. It is a process in which a template is merged with a data source to create a document. The data source can be a database, JSON, XML, or any other data source that contains the data that needs to be merged with the template.

TX Text Control provides a powerful MailMerge feature that allows you to create documents from templates that contain merge fields. Merge fields are placeholders in the template that are replaced with data from the data source when the document is generated.

In contrast to other reporting tools, TX Text Control uses the pre-shaped data approach to merge data into templates. This means that the data is prepared in the correct hierarchical structure before it is merged into the template. This approach has several advantages:

• Because the data is already structured correctly, the template is easier to understand and maintain.
• Merging of data into the template is faster because the data is already in the correct format.
• It is more flexible. You can use any data source that can be converted into the correct hierarchical structure.

TX Text Control expects a pre-selected data structure instead of implicitly accessing a data source with queries. This allows you to generate a proxy data structure, such as a business object or a JSON file, that has been generated from many different data sources. This makes it possible for you to use any data source with TX Text Control.

Hierarchical Data

TX Text Control uses a hierarchical data structure to merge data into templates. Let's take a look at this example JSON data structure:

[
  {
    "company_name": "Text Control, LLC",
    "address":
    {
      "street": "1111 Text Control Way",
      "zip": "28226",
      "city": "Charlotte",
      "country": "United States"
    },
    "contacts": [
      {
        "name": "Tim Typer",
        "email": "tim@textcontrol.com"
      },
      {
        "name": "Karl Keyboard",
        "email": "karl@textcontrol.com"
      },
      {
        "name": "Petra Paragraph",
        "email": "petra@textcontrol.com"
      }
    ],
    "orders": [
      {
        "id": 123,
        "articles": [
          {
            "id": 1,
            "product": {
              "name": "Product A",
              "description": "Description of product A",
              "price": 200
            },
            "qty": 5,
            "discount": 0.2
          },
          {
            "id": 2,
            "product": {
              "name": "Product B",
              "description": "Description of product B",
              "price": 244
            },
            "qty": 50,
            "discount": 0.0
          },
          {
            "id": 3,
            "product": {
              "name": "Product C",
              "description": "Description of product C",
              "price": 677
            },
            "qty": 2,
            "discount": 0.5
          }
        ]
      },
      {
        "id": 321,
        "articles": [
          {
            "id": 1,
            "product": {
              "name": "Product B",
              "description": "Description of product B",
              "price": 123
            },
            "qty": 12,
            "discount": 0.0
          },
          {
            "id": 2,
            "product": {
              "name": "Product D",
              "description": "Description of product D",
              "price": 556
            },
            "qty": 2,
            "discount": 0.7
          },
          {
            "id": 3,
            "product": {
              "name": "Product C",
              "description": "Description of product C",
              "price": 677
            },
            "qty": 20,
            "discount": 0.3
          }
        ]
      }
    ]
  }
]

The internal hierarchy structure is converted to tables:

The following screenshot shows a typical template consisting of merge fields and repeating merge blocks.

Child Tables

The company_name is taken directly from the root table, while the address is taken from a child table. The Contacts section contains a merge block (shown in red below) to list all contacts.

The following animation shows the header section before the merge process and the header section after the merge process:

Merge Blocks

Merge blocks are used to repeat a section of a document for each record in a child table. The details section lists all orders and their items. Therefore, two nested merge blocks are inserted. The outer block repeats the order objects and the inner block lists all items:

The outer block is repeated 2 times based on the actual data in the given JSON, as you can see in the animation below. The inner row of the table is defined as the nested block of elements and contains all of the elements:

Data Controls the Output

TX Text Control merges the data into the template based on the structure of the data. The data controls the output of the document. If no matching data is found for a merge field, the merge field is removed from the output document. If a merge block is empty, the block is removed from the output document.

The RemoveEmptyFields property is used to remove empty merge fields and the RemoveEmptyBlocks property is used to remove empty merge blocks.

In other words, the output document is generated based on the data structure. If the complete orders table is missing in the data, the output document will not contain any orders. And this is valid for all hierarchical levels of merge blocks and structures.

Conclusion

Mail merge is a powerful feature to create documents from templates that contain merge fields. TX Text Control uses a hierarchical data structure to merge data into templates. The data controls the output of the document. If no matching data is found for a merge field, the merge field is removed from the output document. If a merge block is empty, the block is removed from the output document.