Sample: Mail Merge with Nested Repeating Blocks

The DocumentServer.MailMerge component supports the merging of nested blocks. The component recursively descents into the tree structure and merges the

In this sample, a report should list the "sick leave hours" and "vacation days" of all employees of a purely fictional company. The template contains static content, dynamic content for each employee and nested dynamic content for each specific employee record.

Static content

Dynamic content

Dynamic content for each employee

Nested dynamic content for each employee

A repeating block can be any contiguous block of text in a template that is marked with a SubTextPart. The following screenshot shows such a repeating block in TX Text Control Words.

Using the MailMerge component that comes with the TX Text Control, the merge process is very easy. You don't need to iterate through the text fields and you don't need to care about the repeating blocks. The whole process is done automatically - including the nested blocks. The following code shows the required calls of the MailMerge component:

[C#]
mailMerge1.LoadTemplateFromMemory(data, 
     TXTextControl.DocumentServer.FileFormat.InternalUnicodeFormat); 


DataSet ds = new DataSet(); 
ds.ReadXml(tbDatabaseFile.Tag.ToString(), XmlReadMode.Auto); 


DataRelation relation_sick = new DataRelation("sick", 
     ds.Tables["employee"].Columns["dyn_employee_number"], 
     ds.Tables["sick"].Columns["dyn_employee_number"]); 


DataRelation relation_vacation = new DataRelation("vacation", 
     ds.Tables["employee"].Columns["dyn_employee_number"], 
     ds.Tables["vacation"].Columns["dyn_employee_number"]); 


ds.Relations.Add(relation_vacation); 
ds.Relations.Add(relation_sick); 


mailMerge1.MergeBlocks(ds); 
mailMerge1.Merge(ds.Tables["general"], true);
[Visual Basic]
mailMerge1.LoadTemplateFromMemory(data, _
     TXTextControl.DocumentServer.FileFormat.InternalUnicodeFormat)

Dim ds As New DataSet()
ds.ReadXml(tbDatabaseFile.Tag.ToString(), XmlReadMode.Auto)

Dim relation_sick As New DataRelation("sick", ds.Tables("employee").Columns("dyn_employee_number"), _
     ds.Tables("sick").Columns("dyn_employee_number"))

Dim relation_vacation As New DataRelation("vacation", _
     ds.Tables("employee").Columns("dyn_employee_number"), _
	 ds.Tables("vacation").Columns("dyn_employee_number"))

ds.Relations.Add(relation_vacation)
ds.Relations.Add(relation_sick)

mailMerge1.MergeBlocks(ds)
mailMerge1.Merge(ds.Tables("general"), True)

Let's have a look at the XML file we are using as a data source. The DataSet contains 4 DataTables:

The green highlighted columns indicate that these columns are connected through a DataRelation. The MailMerge class automatically descents into the tree structure and merges the contained fields with the corresponding relational data. This process is recursive, so that unlimited levels of nested blocks are feasible.

How to use this sample?

Assuming that you loaded this project into Visual Studio and started this project, the following steps are required to create a report:

1. Click on Load XML... from the Report main menu, browse for the data.xml file that comes with the sample and Open it.

2. Click the Create Report button in the button bar to start the merge process.

The following screenshot shows the merged report document that can be printed or exported as an Adobe PDF file.

Back to the MailMerge overview