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 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 TableCellFormat 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.