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
   [Expand]Product Information
    Product Class Structure
   [Expand]Getting Started
   [Expand]RichEditControl Document
   [Expand]Fields
    Text Formatting
    Import and Export
   [Expand]Page Layout
    Printing
    Spell Checking
    AutoCorrect
    Mail Merge
    Restrictions and Protection
    Syntax Highlighting
    Traversing the Document
   [Expand]Visual Elements
    Services
    Events
    Commands
   [Expand]Member Tables
    Keyboard Shortcuts
    HTML Tag Interpretation
   [Collapse]Examples
    [Expand]Files
    [Expand]Text
    [Expand]Formatting
    [Expand]Styles
    [Expand]Lists
    [Expand]Pictures
    [Expand]Text Boxes
    [Expand]Tables
    [Expand]Layout
    [Expand]Automation
    [Expand]Search and Replace
    [Collapse]Mail Merge
      How to: Perform a Mail Merge
      How to: Create a Master-Detail Report
    [Expand]Spell Check
    [Expand]Export-Import
    [Expand]Printing
    [Expand]Protection
    [Expand]User Interface Customization
    [Expand]Miscellaneous
    [Expand]Commands
  [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]ASP.NET Core 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]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

How to: Perform a 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, which 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 Connect to Data

To perform a mail merge, you need a template and a data source.

  • The template is a document containing fields (placeholders for the information that will be merged).

  • The data source contains the data that will be merged into the fields in the main document to create the merged documents. The data source can be any object that exposes the System.Collections.IList interface.

    In most cases you can use objects which expose the System.Collections.ArrayList interface or external databases available as System.Data.DataTable objects (via corresponding data adapters).

The following code creates a sample System.Collections.ArrayList data source.

Show Me

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

The mail merge data source is specified via the RichEditMailMergeOptions.DataSource property.

Show Me

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

A mail merge document is not complete until it is assigned appropriate data fields names. After providing the data source, proceed to creating fields.

Expanded Insert Fields

To create a template, a merge field (or fields) is inserted into a text document . The field names correspond to the fields of a provided data source.

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

In the Main Toolbar, the Show All Field Codes button displays field codes for all fields in a document, the Show All Field Results displays field placeholders if the View Merged Data button is switched off. If this button is switched on (the corresponding RichEditMailMergeOptions.ViewMergedData property is true), the current record of the data source is displayed in place of the field.

The field is inserted at the cursor position. The merge field code looks like the following:

{MERGEFIELD "field name" [\* MERGEFORMAT]

The optional \* MERGEFORMAT switch, which you can add manually, retains formatting applied to the field.

Document fields that are used in a mail merge only enable 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 other fields (such as DATE or the conditional field IF), use the FieldCollection.Create method of the document's collection of fields.

Expanded Finish a Merge

To finish a mail merge, call the Document.MailMerge method. The resulting document can be saved to a file or a memory stream, or sent for further processing to another RichEditControl or RichEditDocumentServer instance.

The MailMerge method can take a MailMergeOptions object as a parameter that contains additional settings that are not available in the RichEditControlOptionsBase.MailMerge method.

These options enable specifying the data source, choosing records to merge (the MailMergeOptions.FirstRecordIndex and MailMergeOptions.LastRecordIndex properties) and separating the merged ranges in the resulting document (the MailMergeOptions.MergeMode property).

If a merge field is located in a document's header or footer, the MergeMode property should be set to MergeMode.NewSection for proper operation.

To create mail merge options, use the Document.CreateMailMergeOptions method.

To copy all styles contained in the template to the merged document, enable the MailMergeOptions.CopyTemplateStyles property.

Show Me

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

The following code uses records 1 to 3 to perform a mail merge. Each record is merged into a new section in a merged document. The target document is created in another RichEditControl (richEditControl2).

Expanded See Also

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