In the context of the TX Text Control MailMerge class, a merge block is a feature that allows repeating data structures in documents to be handled during a mail merge operation.

A merge block represents a section of the document that is repeated for each data entry in a data source, such as a table or list. This is particularly useful when you want to merge multiple records into a single document, such as invoices, order lists or reports with multiple line items per document.

When the MailMerge class processes the document, the merge block is repeated for each row in the associated data source (e.g., a DataTable or JSON array).

DataSourceManager

The out-of-the-box TX Text Control interface can be used to insert merge fields and merge blocks, and available drop-down lists are automatically populated with available block names based on a loaded data source. However, if you want to create your own UI or programmatically add merge blocks to a template, this article shows how to use the DataSourceManager to retrieve available merge blocks and their fields.

Getting Merge Blocks Names

This code demonstrates how to automate the process of inserting merge blocks into a document. It loads data from a JSON file, dynamically inserts merge blocks for tables into the JSON data, and then merges this data into the document. Finally, it saves the document as a PDF.

First, by loading a data source, in this case JSON, we need to create an instance of the DataSourceManager.

// Load JSON data from file
 string jsonData = File.ReadAllText("tabledata.json");

 var dataSourceManager = new DataSourceManager();
 dataSourceManager.LoadJson(jsonData); // Load JSON data

The PossibleMergeBlockTables method returns a list of merge block names in a loaded data source. The following code snippet shows how to loop through the list of merge blocks:

foreach (var table in dataSourceManager.PossibleMergeBlockTables)
{
   // table.TableName
}

All available column names for a specific merge block can be retrieved using the Columns property. The following code snippet shows how to create a new MergeBlockInfo object and how to set the column names:

// Create a new MergeBlockInfo object with the table name
 var mergeBlockInfo = new MergeBlockInfo(table.TableName)
 {
     ColumnNames = table.Columns.Select(c => c.ColumnName).ToList()
 };

Inserting Merge Blocks

Here is the full code that shows how to insert a merge block for each available block in a document and how to finally merge the template to create a PDF document.

using TXTextControl;
using TXTextControl.DocumentServer.DataSources;
using TXTextControl.DocumentServer;

using (var tx = new ServerTextControl())
{
    tx.Create();

    // Load JSON data from file
    string jsonData = File.ReadAllText("tabledata.json");

    var dataSourceManager = new DataSourceManager();
    dataSourceManager.LoadJson(jsonData); // Load JSON data

    // Add merge blocks for all tables
    foreach (var table in dataSourceManager.PossibleMergeBlockTables)
    {
        // Create a new MergeBlockInfo object with the table name
        var mergeBlockInfo = new MergeBlockInfo(table.TableName)
        {
            ColumnNames = table.Columns.Select(c => c.ColumnName).ToList()
        };

        // Create a new MergeBlockSettings object with the block type and header flag
        var mergeBlockSettings = new MergeBlockSettings(BlockTemplateType.TableRow, true);


        // Insert the merge block
        dataSourceManager.InsertMergeBlock(tx, mergeBlockInfo, mergeBlockSettings);
    }

    new MailMerge { TextComponent = tx }.MergeJsonData(jsonData);

    tx.Save("results.pdf", StreamType.AdobePDF);
}

When the document is merged, the merge block is repeated for each row in the data source. The resulting document is a PDF file that contains the merged data.

Conclusion

The DataSourceManager class provides a simple way to retrieve merge block names and their fields from a data source. This allows you to programmatically insert merge blocks into a document and merge data from a data source into the document.