With version 14.0 of
TX Text Control .NET Server, we introduced a complete new namespace:
TXTextControl.DocumentServer. This namespace contains best practices for specific and typical server-side document service applications.
A common server-side application is template-based mail merging. This allows developers to merge templates with database content. A template consists of merge fields that can be bound to database fields.
TX Text Control .NET Server provides additional functionality to build sophisticated mail merge applications.
A template that can be loaded into the MailMerge component can contain two different types of fields: General fields that are part of the main text and fields that are part of a merge block. Merge blocks are repeated based on the number of data rows in a given DataSet. The block is acting like a sub-report with a separate set of data values.
The following diagram shows the idea behind these blocks:
Diagram
The merge block consists of a number of merge fields. For each data row of the passed DataSet, all fields in the block are merged with the given data of the current row. Additionally, the BlockRowMerged event is fired when a complete block is merged. In the event arguments of this event, the merged block is returned as a byte array in the internal
TX Text Control format. This allows you to change the content of a merged block row. This approach can be used, for example, to change the background color of a table row to realize alternating table row colors
Another event is fired when the complete template has been merged. This allows you to save the document into a file when the append parameter of the Merge method has been set to false. In this case, the resulting documents are not appended to the same document.
Using the following code, you can load a template into the MailMerge component:
mailMerge1.LoadTemplate("template.docx", TXTextControl.DocumentServer.FileFormat.WordprocessingML);
The Merge method is called to merge all fields in the template that are not part of a merge block:
mailMerge1.Merge(mergeData, true);
To pass the data for the blocks, the MergeBlocks method must be called. The passed DataSet must contain a DataTable for each block in the template. The name of the block must be the same as the DataTable name:
mailMerge1.MergeBlocks(mergeBlockData);
Each time a block row is merged, the BlockRowMerged event is fired and can be used as shown in the following code example. The returned byte array is loaded into a ServerTextControl instance for further processing. The changed document can be passed back to the e.MergedBlockRow property:
void mailMerge1_BlockRowMerged(object sender, TXTextControl.DocumentServer.MailMerge.BlockRowMergedEventArgs e)
{
byte[] data = e.MergedBlockRow;
serverTextControl1.Load(data, TXTextControl.BinaryStreamType.InternalUnicodeFormat);
}
Finally, the document can be saved in one of the supported file formats. The next two code lines save the merged document as an Adobe PDF document:
TXTextControl.SaveSettings sSettings = new TXTextControl.SaveSettings();
mailMerge1.SaveDocument("results.pdf", TXTextControl.StreamType.AdobePDF, sSettings);
The next illustration shows the complete MailMerge class and it's properties, methods and events. It gives an overview of the possibilities using the MailMerge component.
Illustration
Try that on your own by downloading the TX Text Control .NET Server trial version. It comes with a complete set of sample projects for Visual Studio 2005 and 2008 that shows the different functionality of our MailMerge component.
Download TX Text Control .NET Server Trial Version
