Snap Mail Merge

• Jun 30, 2021
• 4 minutes to read

This document explains how to create master-detail mail merge reports with Snap, and how to implement in-place filtering, report navigation, sorting and preview.

View Example: How to automatically create mail-merge documents using the Snap Report API

The mail-merge process consists of four general steps:

• creating a template document;

• selecting a data source;

• adding merge fields to the document;

• merging the data with the template document.

Master-Detail Mail Merge

A document can be transformed into a mail merge template by enabling this mode for one of the connected data sources. This can be done by right-clicking a data source in the Data Explorer and selecting Use for Mail Merge in the invoked context menu.

In the resulting document, the static content wraps around any inserted merge field. When merging a finished document, the static template is repeated with each record supplied by the corresponding merge field’s data source. This is in contrast to creating a regular master-detail report, in which an inserted field instantly expands to list all of its data records within the document body.

When performing a master-detail mail merge, Snap derives a field’s role from its level in the data source hierarchy.

• Master Report: Merge Fields

  When inserted from a hierarchical data source, fields that belong to its top level are attributed to the “master” section of a template. To blend with the rest of the report content, the data from these merge fields is inserted as inline text.

  

• Detail Report: Data Fields

  Fields that belong to nested levels of a data source form part of the “detail” document section. When inserted in a template, this data field is displayed as a list of rows representing the underlying data records.

  

  In a document structure, this template is reproduced with each new occurrence of data rows belonging to the “master” section, to accompany it with the corresponding detail data.

  Adding data fields that belong to the same hierarchical level results in creating columns in a document table. Snap tables support automatic summaries, sorting, grouping and filtering.

Note

If merged fields are inserted into page headers (footers), each subdocument that corresponds to a certain data record should start with a new section. A section must be unlinked from the previous section. Otherwise, the fields located in header (footer) do not update. Subscribe to the SnapControl.MailMergeExportFormShowing event to set options as required. The event handler is shown below.

C#

void snapControl1_MailMergeExportFormShowing(object sender, DevExpress.Snap.MailMergeExportFormShowingEventArgs e) {
            e.Options.HeaderFooterLinkToPrevious = false;
            e.Options.RecordSeparator = RecordSeparator.SectionNextPage;
        }

VB.NET

Private Sub snapControl1_MailMergeExportFormShowing(ByVal sender As Object, ByVal e As DevExpress.Snap.MailMergeExportFormShowingEventArgs)
          e.Options.HeaderFooterLinkToPrevious = False
          e.Options.RecordSeparator = RecordSeparator.SectionNextPage
End Sub

In-Place Filtering

Once the Snap template is created and bound, you may need to create filters, to allow end-users to filter the data displayed. Snap provides two filtering options: the quick filter and the expression filter.

• Quick Filter

  Quick filtering allows end-users to select data records by name.

  In the following image, the ‘country’ field is selected. As a result, clicking the Quick Filter button displays a list of countries to select.

  

• Expression Filter

  When simple record selection is not sufficient, you can easily create a complex expression using the Expression Filter dialog.

  

  The criteria in this dialog can include values from data fields and calculated fields.

Navigation, Sorting and Preview

You can switch between report pages that correspond to different master data table records on the Design Surface.

Current Record

To the left of the navigation controls, you can invoke the Sort dialog box to specify the sort order of records based on any field (or sub-field in a master-detail report) in the data source.

To publish a report, you have the following options:

• send it to a printer;
• export it to a third-party document format (DOC, DOCX, RTF, ODT, HTML, PDF, etc.);
• display it on-screen in a Print Preview window.

After selecting one of these options, you can select the range of records to publish, as well as how each record should be separated.

Since Snap assembles the report in a background thread, performance is improved.