Typically, a merge block is used to repeat content based on data rows of a specific table or child table. Merge blocks can be also used to group elements for various reasons. One reason could be the conditional rendering of merge blocks.

This article describes how to add a merge block programmatically using the TXTextControl.DocumentServer.DataSources.DataSourceManager.InsertMergeBlock method and how to set filters and sorting instructions. Additionally, block merging conditions are introduced to specify whether a merge block is rendered or not.

In this article, the following simple data structure is used as the data source:

public class Report
{
    public string Name { get; set; }
    public List<Product> Products { get; set; }
}

public class Product
{
    public string Name { get; set; }
    public float Price { get; set; }
}

On loading, a new data object is created and loaded into the TXTextControl.DocumentServer.DataSources.DataSourceManager class which is designed for handling all existing kinds of data sources used together with the TXTextControl.DocumentServer.MailMerge class. The available merge block table names are listed in a combo box.

DataSourceManager dsManager;
Report report;

private void LoadData()
{
    List<Report> reports = new List<Report>();

    report = new Report()
    {
        Name = "Test Report",
        Products = new List<Product>() {
            new Product() { Name = "TX Text Control Product 1", Price = 634.34F },
            new Product() { Name = "TX Text Control Product 2", Price = 34.34F },
        }
    };

    reports.Add(report);

    // create a new DataSourceManager and load the data object
    dsManager = new DataSourceManager();
    dsManager.LoadSingleObject(report);

    // display the possible merge block tables in a combo box
    cbMergeBlocks.Text = "";
    cbMergeBlocks.DataSource =
        dsManager.PossibleMergeBlockTables.ToList<DataTableInfo>();
    cbMergeBlocks.DisplayMember = "TableName";
}

To insert a new merge block programmatically, the TXTextControl.DocumentServer.DataSources.DataSourceManager.InsertMergeBlock method can be used. The following code inserts a merge block with all available merge fields and some filter and sorting instructions:

// set the DataSourceManager master table
// in order to retrieve the available column names
dsManager.MasterDataTableInfo = dsManager.DataTables[cbMergeBlocks.Text];

// create a new MergeBlockInfo to specify instructions
MergeBlockInfo mergeBlockInfo = new MergeBlockInfo(cbMergeBlocks.Text);

// the SortingInstructions specify how the block should be sorte
// Sorting: Ascending by Price
mergeBlockInfo.SortingInstructions = 
    new List<TXTextControl.DocumentServer.DataShaping.SortingInstruction>()
{
    new TXTextControl.DocumentServer.DataShaping.SortingInstruction(
        "Price", 
        TXTextControl.DocumentServer.DataShaping.SortOrder.Ascending)
};

// the Filters define which rows are displayed
// Filter: Price > 500
mergeBlockInfo.Filters = 
    new List<TXTextControl.DocumentServer.DataShaping.FilterInstruction>()
{
    new TXTextControl.DocumentServer.DataShaping.FilterInstruction(
        "Price", 
        TXTextControl.DocumentServer.DataShaping.RelationalOperator.GreaterThan, 
        500
        )
};

// the BlockMergingCondition can be used to conditionally render a block
// based on a condition in the parent table
// Condition: If Name property is Test Report
mergeBlockInfo.BlockMergingCondition = 
    new List<TXTextControl.DocumentServer.DataShaping.FilterInstruction>()
{
    new TXTextControl.DocumentServer.DataShaping.FilterInstruction(
        "Name", 
        TXTextControl.DocumentServer.DataShaping.RelationalOperator.Equals, 
        "Test Report"
        )
};

// specify the column names
mergeBlockInfo.ColumnNames = dsManager.PossibleMergeFieldColumns.Select(
    column => column.ColumnName).ToList();

// define the block itself
MergeBlockSettings blockSettings = new MergeBlockSettings(BlockTemplateType.TableRow, true);

// insert the block
dsManager.InsertMergeBlock(textControl1, mergeBlockInfo, blockSettings);

There are three conditions in the merge block defined:

1. Sorting: The table is sorted ascending by the column Price.
2. Filtering: Only rows are rendered where the column Price is greater than 500.
3. Conditions: The whole block is only rendered, if the column Name of the parent table is Test Report.

The document is then merged using the TXTextControl.DocumentServer.MailMerge.MergeObject method:

MailMerge mailMerge = new MailMerge()
{
    TextComponent = textControl1
};

mailMerge.MergeObject(report);

These new merge block settings can be used to handle data shaping in the template directly and to render parts of a document conditionally based on merge field values in the data source. No custom event handling is required anymore to set the conditions for a merge block.

Test this on your own and download a trial version of TX Text Control X16.