The MailMerge class provides a very effective way to merge data into merge field placeholders, repeating blocks, form fields, barcodes, images and chart objects. This engine handles the dynamic generation of documents based on document templates.

This article explains the data structure based on a simple template and sample JSON data.

The Sample JSON Data

The sample JSON data contains hierarchical data that allows to show different mail merge features including access to data from child tables and nested, repeating merge blocks.

[
  {
    "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
          }
        ]
      }
    ]
  }
]

Internally, the hierarchical structure is converted into tables. The following diagram shows these tables including their child tables:

The Sample Template

The sample template that is used in this article is very simple and contains static data, simple merge fields and a nested, repeating block. The merge block will list all "orders" from the sample data:

First, we take a look at the address part of the template. For this part, 3 tables are used and accessed in different ways.

Accessing Child Tables

company_name comes from the root table directly while the address is coming from a child table. These fields can be accessed using the "dot notation". For example, to access the street, the merge field name is address.street.

The contacts part contains a merge block (highlighted in red below) to list all of the contacts. A merge block repeats all elements part of the block based on the data for this block. In this case, the block includes a soft break and the tab character, so that all contacts are listed at the same indent position:

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

Repeating Blocks

The detail section lists all orders and their articles. Therefore, two nested merge blocks are inserted. The outer block repeats the orders objects and the inner block lists all articles:

As can be seen in the following animation, the outer block is getting repeated 2 times based on the actual data in the given JSON. The inner table row is defined as the nested block articles and contains all line items:

Using Dynamic Formulas in Merge Blocks

Several values are calculated on-the-fly and are not part of the JSON data:

The line total and the total sum values are calculated based on table cell formulas. The line total multiplies the qty with the product.price including the given discount. The total sum formula simply creates a sum of all values above in the same column of the table.

The IF field prints the text "This item is discounted!" in cases the discount is larger than 20%.

Download Sample Data

Download the sample template and the JSON data and test this on your own.

Download