MergeBlocks are merge elements in a template that allow content to be repeated based on a given set of hierarchical data. It is typically used to repeat line items in an invoice or a quote, or to repeat table rows with the same format.

Learn More

The MailMerge class provides very effective ways to merge data into MS Word compatible templates. This updated ultimate guide provides an overview of all the important features and functionalities of the mail merge process.

An Ultimate Guide to Mail Merge with MS Word Documents in C#

This article shows how to insert MergeBlocks with the DataSourceManager ╰ TX Text Control .NET Server for ASP.NET
╰ DocumentServer.DataSources Namespace
╰ DataSourceManager Class
The DataSourceManager class is designed for handling all existing kinds of data sources which can be used together with the MailMerge class. and how to apply table styles to those tables. The article uses the DocumentServer class to insert MergeBlocks with the DataSourceManager.

Sample Data JSON

The following JSON data is used in this article:

[
{
"name": "Model 1",
"mergeBlock1": [
{
"blockvalue_1": "Block Value 1",
"blockvalue_2": "123"
},
{
"blockvalue_1": "Block Value 2",
"blockvalue_2": "456"
}
]
}
]
view raw test.json hosted with ❤ by GitHub

You can see that there is an array element (mergeBlock1) in the JSON data that you want to insert as a merge block. A typical result table created by this merge block can be seen in the following animated screen shot.

Merge Block

Inserting MergeBlocks

Merge blocks can be added to a template using the Document Editor, which provides a full-featured interface for adding mail merge functionality to a document. However, the TX Text Control also provides a very powerful class for the insertion of merge blocks into a document.

The following code snippet shows how to insert a merge block into a document using the DataSourceManager class:

private Table AddMergeBlock(string tableName, DataSourceManager dataSourceManager)
{
// get the columns of the data table
var columns = dataSourceManager.DataTables[tableName].Columns;
// list of column names
var columnNames = columns.Select(c => c.ColumnName).ToList();
// create a new merge block info
MergeBlockInfo mergeBlockInfo = new MergeBlockInfo(tableName)
{
ColumnNames = columnNames
};
// create a new merge block settings
MergeBlockSettings mergeBlockSettings = new MergeBlockSettings()
{
BlockTemplateType = BlockTemplateType.TableRow,
CreateHeaderRow = true
};
// insert the merge block
dataSourceManager.InsertMergeBlock(textControl1, mergeBlockInfo, mergeBlockSettings);
return mergeBlockSettings.CreatedTable;
}
view raw block.cs hosted with ❤ by GitHub

The AddMergeBlock method takes all column names from a given table name and inserts the block using the InsertMergeBlock method of the DataSourceManager.

This method is called with an instance of the DataSourceManager, into which the sample JSON is loaded.

// load JSON data
var jsonData = File.ReadAllText("JsonModel.json");
// create a new DataSourceManager
DataSourceManager dataSourceManager1 = new DataSourceManager();
dataSourceManager1.LoadJson(jsonData);
var table = AddMergeBlock("mergeBlock1", dataSourceManager1);
TableStyle tableStyle = new TableStyle()
{
TableRowFormat = new TXTextControl.TableCellFormat()
{
BottomBorderWidth = 1,
TopBorderWidth = 1,
LeftBorderWidth = 1,
RightBorderWidth = 1,
BottomTextDistance = 100,
TopTextDistance = 100,
LeftTextDistance = 100,
RightTextDistance = 100
},
HeaderRowFormat = new TXTextControl.TableCellFormat()
{
BackColor = Color.DeepPink,
BottomBorderWidth = 1,
TopBorderWidth = 1,
LeftBorderWidth = 1,
RightBorderWidth = 1,
BottomTextDistance = 200,
TopTextDistance = 200,
LeftTextDistance = 100,
RightTextDistance = 100
}
};
ClearTableStyle(table, textControl1);
ApplyTableStyle(table, tableStyle);
view raw test.cs hosted with ❤ by GitHub

The table that is returned is then styled with a new specified TableStyle to define the style of the table row and the table header of the newly inserted merge block table. The TableStyle class uses the TableCellFormat ╰ TX Text Control .NET Server for ASP.NET
╰ TXTextControl Namespace
╰ TableCellFormat Class
An instance of the TableCellFormat class represents the formatting attributes of a table cell. class to define the style.

public class TableStyle
{
public TXTextControl.TableCellFormat TableRowFormat { get; set; }
public TXTextControl.TableCellFormat HeaderRowFormat { get; set; }
}
view raw test.cs hosted with ❤ by GitHub

Styling the Table

The two methods that are applied to the table that is returned will remove the style from the table and apply the specified style to the table.

The ClearTableStyle method loops through all rows and applies the default empty table row format of the TX Text Control to clear the table format.

public void ClearTableStyle(Table table, TextControl textControl)
{
var cellFormat = new TXTextControl.TableCellFormat();
// clear all row formats
foreach (TableRow row in table.Rows)
{
// apply each property of cellFormat to the row by using reflection
foreach (var property in cellFormat.GetType().GetProperties())
{
property.SetValue(row.CellFormat, property.GetValue(cellFormat));
}
}
table.Select();
textControl.Selection.ForeColor = Color.Black;
}
view raw test.cs hosted with ❤ by GitHub

The ApplyTableStyle method applies the specified table style to the table. The style is defined in the TableStyle class and is applied to the table rows and the table header.

public void ApplyTableStyle(Table table, TableStyle tableStyle)
{
// loop through rows and check for header row
foreach (TableRow row in table.Rows)
{
if (row.IsHeader)
{
row.CellFormat = tableStyle.HeaderRowFormat;
}
else
{
row.CellFormat = tableStyle.TableRowFormat;
}
}
}
view raw test.cs hosted with ❤ by GitHub

Conclusion

This article showed how to insert MergeBlocks with the DataSourceManager and how to apply table styles to those tables. The article used the DocumentServer class to insert MergeBlocks with the DataSourceManager.