New Sample: Creating Reports with Nested Repeating Blocks

Since version 16.0 of TX Text Control .NET Server, the MailMerge class supports the merging of nested blocks. The component recursively descents into the tree structure and merges the contained fields with the corresponding relational data.

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
  • Heading: "Accruals Report"
  • Page number: "Page n"
• Dynamic content
  • Company name: "Software Consultants, LLC"
  • Date
• Dynamic content for each employee
  • Employee number
  • Employee name
• Nested dynamic content for each employee
  • Date
  • Type
  • Action
  • Note
  • Hours
  • Balance

The above described content sections are marked in the following template illustration:

A repeating block can be any contiguous block of text in a template that is marked with specifically named DocumentTargets at the beginning and the end. The following screenshot shows such a repeating block in the TX Template Designer.

Using the MailMerge component that comes with the TX Text Control .NET Server licenses, 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:

mailMerge1.LoadTemplateFromMemory(data,
            TXTextControl.DocumentServer.FileFormat.InternalUnicodeFormat);

// load the XML file
DataSet ds = new DataSet();
ds.ReadXml(tbDatabaseFile.Tag.ToString(), XmlReadMode.Auto);

// add the relations for the nested blocks
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);

// pass the data
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:

general
dyn_company

employee
dyn_employee_fullname
dyn_employee_number

sick
dyn_employee_number
date
type
action
note
hours
balance

vacation
dyn_employee_number
date
type
action
note
hours
balance

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 on Load... from the Template main menu, browse for the Accruals Report.docx file and confirm with Open.
3. Finally, 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.

Test this sample now and download the sources in our source code library.