Mail Merge and Reporting
Invoices, letters, contracts and reports that share a layout but differ in their data come from one template and a merge. In a Windows Forms application, both halves live in the same form: users design templates in the TextControl with the Reporting ribbon tab, and the MailMerge component fills them with data, in the visible editor or in the background. Read on for the way from the reporting model to data sources, fields and blocks, conditions, formatting, the template designer and the events of a merge.
If you haven't merged a template yet, start with the tutorials of Getting Started: Mail Merge. MailMerge in the Overview introduces the component. Mail merge is part of the Professional and Enterprise editions, as Editions and Feature Availability lists.
How Mail Merge Works
A merge brings three parts together:
- The template is a document designed in the Reporting tab of your application, in MS Word or in code. It contains merge fields for single values, merge blocks for repeating and optional parts, special fields such as
IFandINCLUDETEXT, and placeholders for images and barcodes. - The data comes as business objects, a
DataSet, JSON or XML, in the structure the document needs. Its names match the names of the fields and blocks. MailMergefills the template held by aTextControlor aServerTextControlwith the data. The result is shown in the editor, saved as PDF, DOCX or another format, or printed, as one document or one document per record.
The template holds the layout and the rules, such as formats and filters, so the merge code doesn't change when a designer changes the template.
Find the Right Page
| If you want to | Read |
|---|---|
| Understand the reporting model, merge in the editor or in the background, create one document per record | Overview |
| Merge business objects, DataSets, JSON or XML, or connect a database in the designer | Data Sources |
| Format numbers and dates, add text before and after a value, insert date fields | Merge Fields |
| Repeat table rows or sections for each record | Merge Blocks |
| Build master-detail reports with blocks inside blocks | Nested Blocks and Master-Detail Reports |
| Reuse terms, letterheads or address blocks in many templates | Subtemplates |
| Merge logos, photos, QR codes, barcodes and charts | Images and Barcodes |
| Include text and sections only when the data calls for them | Conditional Content |
| Merge the rows of a block in order and only the rows you need | Sorting and Filtering |
| Color rows, highlight values or calculate totals in merged tables | Formatting and Styling |
| Design, store and test templates that hold up with real data | Template Design |
| Know every button and dialog box of the Reporting tab, or open them from your code | Reporting Ribbon and Dialog Boxes |
| Show users the merged result while they design | Template Preview |
| Follow, change or cancel a merge in its events | Merge Events |
Where to Start
- Overview: templates, data and where the merge runs.
- Data Sources: the data your application merges.
- Merge Fields and Merge Blocks: the elements of every template.
- Reporting Ribbon and Dialog Boxes and Template Design: the designer your users work with.
Pages in This Section
- Overview: the reporting model, pre-shaped data and one document per record.
- Data Sources: objects, DataSets, JSON, XML and configuration files.
- Merge Fields: formats, text before and after a value, date and form fields.
- Merge Blocks: repeating parts of a template.
- Nested Blocks and Master-Detail Reports: blocks inside blocks.
- Subtemplates: documents included with
INCLUDETEXTfields. - Images and Barcodes: placeholders and charts filled from the data.
- Conditional Content:
IFfields, optional blocks and conditions. - Sorting and Filtering: rules that blocks store.
- Formatting and Styling: formatting kept from the template and set in events.
- Template Design: where templates are designed, stored and tested.
- Reporting Ribbon and Dialog Boxes: the Reporting tab, its dialog boxes and their classes.
- Template Preview: the merged result in the editor while designing.
- Merge Events: the events of
MailMergeand their order.