MailMerge

Letters, invoices, labels and reports all start as a template with placeholders, and MailMerge fills the placeholders with your data. In a Windows Forms application, users design the template in the editor with the Reporting ribbon tab, and MailMerge merges it with a DataTable, business objects or JSON, either in the visible TextControl or in the background.

What MailMerge Is

MailMerge in the TXTextControl.DocumentServer namespace is a component, derived from System.ComponentModel.Component, that merges templates with data. It is in the TX Text Control 34.0 toolbox tab, and the designer places it in the component tray below the form.

MailMerge holds no document itself. Its TextComponent property connects it to a TextControl, whose document is the template and receives the result where the user sees it, or to a ServerTextControl, which merges in the background. Where the Merge Runs compares the two.

Mail merge, merge fields and the reporting features are part of the Enterprise and Professional editions. See Editions and Feature Availability.

Templates and Data

A template is a regular document with placeholders for the data. Merge fields, MS Word MERGEFIELD fields, are replaced with the value of the same name, and merge blocks repeat a part of the template, such as a table row, for each record of a list. Mail Merge Overview explains the reporting model and what a merge processes, and Merge Fields and Merge Blocks go into detail.

The data comes from a DataTable or DataSet with Merge, from business objects with MergeObjects and MergeObject, from JSON with MergeJsonData, or from a database named in a data source configuration file. How Data Reaches a Template lists each kind with its method.

The Reporting User Interface

Windows Forms applications get a ready-made user interface for designing templates, with the Reporting tab at its center. The RibbonReportingTab selects a data source through its DataSourceManager, inserts merge fields and merge blocks, and opens the dialog boxes of the namespace TXTextControl.DocumentServer.Windows.Forms, which your own menus can open as well. Reporting Ribbon and Dialog Boxes describes the tab and its dialogs.

Your First Merge

Mail Merge in Getting Started creates a template, merges data into its fields and adds a merge block. Properties such as RemoveEmptyFields decide what happens to placeholders without data, as Remove What Stays Empty describes, and events such as FieldMerged let your code take part in the merge, as The Events of MailMerge describes.

Key Classes

Next Steps

• Mail Merge in Getting Started: create a template, merge data into its fields and add merge blocks.
• Mail Merge and Reporting: data sources, merge fields, merge blocks, events and the reporting user interface in detail.
• Reporting Ribbon and Dialog Boxes: the Reporting tab and its dialogs.
• ServerTextControl: merge documents in the background.