Typically, a merge block is used to repeat content based on data rows of a specific table or child table. Merge blocks can be also used to group elements for various reasons. One reason could be the conditional rendering of merge blocks.
This article describes how to add a merge block programmatically using the TXText
╰ TX Text Control .NET for Windows Forms
╰ DocumentServer.DataSources Namespace
╰ DataSourceManager Class
╰ InsertMergeBlock Method
Inserts a repeating merge block into a TextControl instance, a WPF.TextControl instance or a ServerTextControl instance at the current input position. and how to set filters and sorting instructions. Additionally, block merging conditions are introduced to specify whether a merge block is rendered or not.
In this article, the following simple data structure is used as the data source:
| public class Report | |
| { | |
| public string Name { get; set; } | |
| public List<Product> Products { get; set; } | |
| } | |
| public class Product | |
| { | |
| public string Name { get; set; } | |
| public float Price { get; set; } | |
| } |
On loading, a new data object is created and loaded into the TXText ╰ TX Text Control .NET for Windows Forms
╰ 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. which is designed for handling all existing kinds of data sources used together with the TXText ╰ TX Text Control .NET for Windows Forms
╰ DocumentServer Namespace
╰ MailMerge Class
The MailMerge class is a .NET component that can be used to effortlessly merge template documents with database content in .NET projects, such as ASP.NET web applications, web services or Windows services. . The available merge block table names are listed in a combo box.
| DataSourceManager dsManager; | |
| Report report; | |
| private void LoadData() | |
| { | |
| List<Report> reports = new List<Report>(); | |
| report = new Report() | |
| { | |
| Name = "Test Report", | |
| Products = new List<Product>() { | |
| new Product() { Name = "TX Text Control Product 1", Price = 634.34F }, | |
| new Product() { Name = "TX Text Control Product 2", Price = 34.34F }, | |
| } | |
| }; | |
| reports.Add(report); | |
| // create a new DataSourceManager and load the data object | |
| dsManager = new DataSourceManager(); | |
| dsManager.LoadSingleObject(report); | |
| // display the possible merge block tables in a combo box | |
| cbMergeBlocks.Text = ""; | |
| cbMergeBlocks.DataSource = | |
| dsManager.PossibleMergeBlockTables.ToList<DataTableInfo>(); | |
| cbMergeBlocks.DisplayMember = "TableName"; | |
| } |
To insert a new merge block programmatically, the TXText ╰ TX Text Control .NET for Windows Forms
╰ DocumentServer.DataSources Namespace
╰ DataSourceManager Class
╰ InsertMergeBlock Method
Inserts a repeating merge block into a TextControl instance, a WPF.TextControl instance or a ServerTextControl instance at the current input position. can be used. The following code inserts a merge block with all available merge fields and some filter and sorting instructions:
| // set the DataSourceManager master table | |
| // in order to retrieve the available column names | |
| dsManager.MasterDataTableInfo = dsManager.DataTables[cbMergeBlocks.Text]; | |
| // create a new MergeBlockInfo to specify instructions | |
| MergeBlockInfo mergeBlockInfo = new MergeBlockInfo(cbMergeBlocks.Text); | |
| // the SortingInstructions specify how the block should be sorte | |
| // Sorting: Ascending by Price | |
| mergeBlockInfo.SortingInstructions = | |
| new List<TXTextControl.DocumentServer.DataShaping.SortingInstruction>() | |
| { | |
| new TXTextControl.DocumentServer.DataShaping.SortingInstruction( | |
| "Price", | |
| TXTextControl.DocumentServer.DataShaping.SortOrder.Ascending) | |
| }; | |
| // the Filters define which rows are displayed | |
| // Filter: Price > 500 | |
| mergeBlockInfo.Filters = | |
| new List<TXTextControl.DocumentServer.DataShaping.FilterInstruction>() | |
| { | |
| new TXTextControl.DocumentServer.DataShaping.FilterInstruction( | |
| "Price", | |
| TXTextControl.DocumentServer.DataShaping.RelationalOperator.GreaterThan, | |
| 500 | |
| ) | |
| }; | |
| // the BlockMergingCondition can be used to conditionally render a block | |
| // based on a condition in the parent table | |
| // Condition: If Name property is Test Report | |
| mergeBlockInfo.BlockMergingCondition = | |
| new List<TXTextControl.DocumentServer.DataShaping.FilterInstruction>() | |
| { | |
| new TXTextControl.DocumentServer.DataShaping.FilterInstruction( | |
| "Name", | |
| TXTextControl.DocumentServer.DataShaping.RelationalOperator.Equals, | |
| "Test Report" | |
| ) | |
| }; | |
| // specify the column names | |
| mergeBlockInfo.ColumnNames = dsManager.PossibleMergeFieldColumns.Select( | |
| column => column.ColumnName).ToList(); | |
| // define the block itself | |
| MergeBlockSettings blockSettings = new MergeBlockSettings(BlockTemplateType.TableRow, true); | |
| // insert the block | |
| dsManager.InsertMergeBlock(textControl1, mergeBlockInfo, blockSettings); |
There are three conditions in the merge block defined:
- Sorting: The table is sorted ascending by the column Price.
- Filtering: Only rows are rendered where the column Price is greater than 500.
- Conditions: The whole block is only rendered, if the column Name of the parent table is Test Report.
The document is then merged using the TXText ╰ TX Text Control .NET for Windows Forms
╰ DocumentServer Namespace
╰ MailMerge Class
╰ Merge Method
Merges a single instance of an arbitrary type into the loaded document template. :
| MailMerge mailMerge = new MailMerge() | |
| { | |
| TextComponent = textControl1 | |
| }; | |
| mailMerge.MergeObject(report); |
These new merge block settings can be used to handle data shaping in the template directly and to render parts of a document conditionally based on merge field values in the data source. No custom event handling is required anymore to set the conditions for a merge block.
Test this on your own and download a trial version of TX Text Control X16.
