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 Data ╰ 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" | |
} | |
] | |
} | |
] |
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.
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; | |
} |
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); |
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 Table ╰ 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; } | |
} |
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; | |
} |
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; | |
} | |
} | |
} |
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.