[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications, and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Gantt Control
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
   [Expand]Product Information
   [Expand]Getting Started
   [Expand]Graphical User Interface
    Supported Formats
   [Expand]Developer Guidelines
   [Collapse]Data Acquisition
     Data Source Wizard
     Snap Mail Merge
     Query Builder
     Master-Detail Relation
     Calculated Fields
   [Expand]Data Shaping
  [Expand]TreeMap Control
  [Expand]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Snap Mail Merge

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.


A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E5078.

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.

These steps are outlined in the following sections of the document.

Expanded 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.


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.

Expanded 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.

Expanded 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.

Expanded See Also

Is this topic helpful?​​​​​​​