When merging multiple records using the TX Text Control's MergeJsonData method, the append parameter determines whether the output is a single document with each record in a new section or multiple separate documents.

Templates that contain only a first page header can be tricky in scenarios where the append parameter is set to true to append all records to a resulting document. If set to false, individual documents are created and the first page header is only visible on page 1.

The Problem

But when appended, the first page header is rendered for all sections, and if the header contains merge fields, they are populated with data from the first record. So basically, after the merge, you have all the records merged into separate sections, but the header and footer contain the merge field data from the first record.

Let's take a look at the following template:

You can see a first page header with a merge field and the main body containing a merge block. This is the JSON data that will be used to merge the content into the template.

[
    {
        "invoice": "INV-001",
        "date": "2023-10-01",
        "items": [
            {
                "name": "Widget A",
                "description": "A longer description of Widget A.",
                "quantity": 2,
                "unit_price": 10.00
            },
            {
                "name": "Widget B",
                "description": "A longer description of Widget B.",
                "quantity": 1,
                "unit_price": 20.00
            }
        ]
    },
    {
        "invoice": "INV-002",
        "date": "2023-10-02",
        "items": [
            {
                "name": "Widget C",
                "description": "A longer description of Widget C.",
                "quantity": 5,
                "unit_price": 5.00
            },
            {
                "name": "Widget D",
                "description": "A longer description of Widget D.",
                "quantity": 3,
                "unit_price": 15.00
            }
        ]
    }
]

The following code shows how to merge the JSON data into the template using the MergeJsonData method.

using System.IO;
using TXTextControl;
using TXTextControl.DocumentServer;

// Create and initialize a ServerTextControl instance
using var tx = new ServerTextControl();

// Create a new, empty document
tx.Create();

// Load the template in the internal Unicode format
tx.Load("template.tx", StreamType.InternalUnicodeFormat);

// Set up the MailMerge engine and assign the TextComponent
var mailMerge = new MailMerge
{
    TextComponent = tx
};

// Read JSON data from a file
var jsonData = File.ReadAllText("data.json");

// Merge JSON data into the loaded template
// `append: true` means merge all records into one document, each in a new section
mailMerge.MergeJsonData(jsonData, append: true);

// Save the merged result as a PDF file
tx.Save("result.pdf", StreamType.AdobePDF);

After the merge, the resulting document looks like this:

The Solution

As you can see, the header of the second attached document contains the merge data from the first record. This is not what we want. A new section is added for each record, and a unique first page header should be added for all pages in each section. But we know that a new section is added for all records, so we can use a header and footer setting to implement this requirement.

For the first page header, we use the ConnectedToPrevious property and set it to false for the first page header. This means that the first page header is not connected to the header of the previous section.

Now the first page header is not linked to the previous section, and the merge field is populated with the data from the current record. Below is the resulting document after the merge:

As you can see, the first page header is now populated with the data from the current record.

Conclusion

In this article, we learned how to use the MergeJsonData method to merge multiple records into a single document with a first page header. We also learned how to set the ConnectedToPrevious property to false for the first page header to ensure that it is not connected to the previous section.

By using this approach, we can ensure that the first page header is populated with the data from the current record and not the first record.