MergeBlocks and DataSets
A MergeBlock is a region in a document that will be repeated in the merge process. This block can be easily inserted using the shipped TX Template Designer. A MergeBlock's start and end is marked by two document targets with special names. The start and end of a merge block must either be in the floating text, comprising of one or more table rows as a whole or inside a single table cell. The following illustration shows an example of such a block start and end with their special names (in red) in detail:
The format of the target name is as follows:
blockStart_ + unique name
blockEnd_ + unique name
Sample:
blockStart_block1
blockEnd_block1
Additionally, merge blocks can be nested. Consider the following setup, for instance:
Merged with appropriately prepared data, the template could result in following document:
A merge block can consist of all elements in the floating text, including tables or images that are inserted inline with text. The number of iterations a block runs through during the merge process directly relates to the number of DataRows in the associated DataTable. Typical applications for merge blocks include, e.g., generating a list of invoice items or an inventory list that is sorted by subsidiary.
The merge data must reflect the merge blocks' structure. Each merge block is associated with a DataTable object. This association works via the names of the data table and the merge block, e.g., the data belonging to the block Company would be contained in the data table Company. Additionally, when dealing with nested blocks, the corresponding data tables must be related using DataRelation objects. Data relations are the .NET way of setting up primary/foreign key relationships. Please see below for an example. All data tables associated with merge blocks are assembled in the same DataSet object. The name of this data set is not important and, thus, can be arbitrarily set.
The above image of three nested blocks could be merged with the following data of companies, divisions and employess:
Every data relation needs a name, a DataColumn object that acts as the parent and one that acts as the child:
[C#]
DataRelation relation = new DataRelation(dtCompany.TableName +
dtDivision.TableName, dcCompanyID, dcDivisionCompanyID);
dsCompany.Relations.Add(relation);
[Visual Basic]
Dim relation As New DataRelation(dtCompany.TableName + _
dtDivision.TableName, dcCompanyID, dcDivisionCompanyID)
dsCompany.Relations.Add(relation)
The same holds for the division-employee relation, of course:
[C#]
relation = new DataRelation(dtDivision.TableName +
dtEmployee.TableName, dcDivisionID, dcEmployeeDivisionID);
dsCompany.Relations.Add(relation);
[Visual Basic]
relation = New DataRelation(dtDivision.TableName + _
dtEmployee.TableName, dcDivisionID, dcEmployeeDivisionID)
dsCompany.Relations.Add(relation)
