New Sample: Creating Reports with Nested Repeating Blocks
The TX Text Control .NET Server 16.0 MailMerge class merges nested repeating blocks by recursively traversing relational data structures defined through DataRelations. This sample builds an employee accruals report linking employee records to sick leave and vacation tables.
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:
- Click on Load XML... from the Report main menu, browse for the data.xml file that comes with the sample and Open it.
- Click on Load... from the Template main menu, browse for the Accruals Report.docx file and confirm with Open.
- 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.
Related Posts
Learning Mail Merge Templates from Basic Fields to Advanced Reporting Structures
The new Mail Merge Template Assistant transforms the TX Text Control online demo into an interactive tutorial. It guides developers through basic data binding and merge fields, as well as advanced…
TX Text Control for Blazor: Mail Merge Integration Tutorial
This tutorial shows how to integrate the TX Text Control MailMerge component into a Blazor application using the TX Text Control .NET Server.
Mail Merge: Skipping Records During the Merge Process in .NET C#
This article shows how to skip records during the merge process in .NET C# using the MailMerge class of the Text Control Reporting engine.
Mail Merge MS Word DOCX Documents and Convert to PDF in .NET C#
This article shows how to merge data into MS Word DOCX documents and convert them to PDF using TX Text Control .NET Server.
Merging Self-Calculating Business Objects with TX Text Control MailMerge in C#
This article shows how to merge self-calculating business objects with TX Text Control MailMerge in C#. The sample shows how to merge a list of products with a total sum.