Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [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]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Collapse]Rich Text Editor
    Overview
   [Expand]Getting Started
   [Expand]Fundamentals
   [Collapse]Concepts
     Text Formatting
     Import and Export
     Mail Merge
     Restrictions and Protection
     Line Numbering
     Table of Contents
     Check Spelling
     AutoCorrect
     Printing
     Syntax Highlighting
     Traversing the Document
   [Expand]Visual Elements
   [Expand]Examples
   [Expand]Member Tables
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Mail Merge

This document provides an overview of an older approach to creating Mail Merge documents with the RichEditControl.

Note

A newer and more convenient approach to Master-Detail Mail Merge is provided by the SnapControl and SnapDocumentServer. This approach is described in the following document: Snap Mail Merge.

The following sections describe an obsolete mail merge implementation that is still available to provide backward compatibility.

Expanded Performing a Mail Merge

Performing a mail merge in a rich text document requires the following two steps.

  • Specify the document data source by using the RichEditMailMergeOptions.DataSource property (it can be accessed via the RichEditControl.Options.MailMerge.DataSource notation).

  • Create a template by inserting MERGEFIELD fields. The field names refer to data column names of a specified data source.

    The MERGEFIELD field only enables the substitution of plain text. Formatted text that is inserted from a data source into a merge field will not be recognized and properly parsed. To insert formatted content, use the DOCVARIABLE field .

    To insert images, insert the MERGEFIELD field into an INCLUDEPICTURE field.

    To create master-detail mail merge reports, insert a DOCVARIABLE field with the variable name specified by the MERGEFIELD field.

To finish a mail merge and publish the document, call the Document.MailMerge method. To use mail merge options (e.g., to choose records to merge or separate the merged ranges in the resulting document), call the Document.CreateMailMergeOptions method and specify the created MailMergeOptions instance in the MailMerge method call.

To indicate the progress of a mail merge, use the IProgressIndicationService interface.

The resulting document can be saved to a file or a memory stream, or sent for further processing to another RichEditControl or RichEditDocumentServer instance.

Expanded Using Mail Merge Options

When a RichEditControl is assigned a mail merge data source, a data field is inserted into the document by clicking Insert Merge Field and selecting the field name in the invoked drop-down list (if a Ribbon UI is used) or a dialog window (if the Bar UI is used).

To hide unnecessary fields from this list, or replace obscure or lengthy display names, handle the RichEditControl.CustomizeMergeFields event.

The following events control the processes of performing mail merge and merging individual records.
- RichEditControl.MailMergeStarted and RichEditControl.MailMergeFinished;
- RichEditControl.MailMergeRecordStarted and RichEditControl.MailMergeRecordFinished.

The following commands may be useful when creating mail merge documents.

Command

Description

InsertMergeFieldCommand

Inserts the MERGEFIELD field at the selection.

ShowInsertMergeFieldFormCommand

Invokes a dialog window to insert merge fields into a document from a connected data source.

ShowAllFieldCodesCommand

Displays the codes of all fields in a document.

ShowAllFieldResultsCommand

Displays field data in place of field codes.

ToggleFieldCodesCommand

Toggles the mode for displaying field codes.

ToggleViewMergedDataCommand

Toggles the mode for displaying field data.

FirstDataRecordCommand

Navigates to the first data record in the connected data source.

LastDataRecordCommand

Navigates to the last data record in the connected data source.

NextDataRecordCommand

Navigates to the next data record in the connected data source.

PreviousDataRecordCommand

Navigates to the previous data record in the connected data source.

Expanded See Also

How would you rate this topic?​​​​​​​