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
   [Expand]Examples
  [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

Mail Merge

Important

The SnapControl and SnapDocumentServer components provide a newer and more convenient approach to Mail Merge. Refer to the Snap Mail Merge topic for details.

Perform the following steps to create the mail merge document:
  1. Provide a Data Source
  2. Load a Document Template
  3. Merge and Save the Document

Expanded Provide a Data Source

Use the RichEditMailMergeOptions.DataSource property to set the data source to use in a mail merge. If the data source contains multiple data tables, use the MailMergeOptions.DataMember property to define a specific data member. RichEditCotnrol supports the following data source types:

  • System.Collections.IList;
  • System.Collections.ArrayList;
  • System.Data.DataTable.

Show Me

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

Expanded Load a Document Template

The template is a document containing fields, which refer to a specified data source's data column names. Call the FieldCollection.Create method to insert the desired field to the given document position in code. Depending on the content to be inserted, use one of the following fields:

  • MERGEFIELD - to insert plain text;
  • DOCVARIABLE - to insert formatted content;
  • INCLUDEPICTURE - to insert images. Use the INCLUDEPICTURE field as follows: {INCLUDEPICTURE "{MERGEFIELD PictureLocation}" \d}, where PictureLocation is the path to the desired picture. Make sure that images have the same name as the field's contents in the database (for example, as the "FirstName" field) if the template requires mail merging different images, and insert the INCLUDEPICTURE as follows: { INCLUDEPICTURE "PicturesLocation\\{ MERGEFIELD FieldName }.jpg” \*MERGEFORMAT \d }.
  • Tip

    Use the IUriStreamProvider to insert pictures from a data base. Refer to the E4164 code example for details.

Expanded Merge and Save the Document

Use the following API to set additional merging options (the number of records, merged ranges delimitation, etc.) and merge the document:

API Description
RichEditControlOptionsBase.MailMerge Provides access to the default mail merge options.
Document.CreateMailMergeOptions Initializes an MailMergeOptions instance, which contains additional mail merge options.
MailMergeOptions.FirstRecordIndex Gets or sets the record index from which the merge starts.
MailMergeOptions.LastRecordIndex Gets or sets the record index at which the merge finishes.
MailMergeOptions.MergeMode Gets or sets how the merged ranges are delimited in the resulting document.
Document.MailMerge Merges the current document using the specified options, and sends the result to the specified document.

After the mail merge is finished, you can send the document to further processing to another RichEditControl (as shown in the code below) or RichEditDocumentServer instance, or save it to the file.

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

Mail Merge Events

Additionally, the RichEditControl provides the following events allowing you to control specific mail merging steps:

Event Description
RichEditControl.CustomizeMergeFields Fires when the 'Insert Merge Field' command button is clicked, and enables you to customize a drop-down field list.
RichEditControl.MailMergeStarted Fires before mail merge starts.
RichEditControl.MailMergeFinished Fires when mail merge is completed.
RichEditControl.MailMergeRecordStarted Fires before each data record is merged with the document in the mail merge process.
RichEditControl.MailMergeRecordFinished Fires after each data record is merged with the document in the mail merge process.

Expanded Master-Detail Mail Merge Documents

The master-detail report requires creating a RichEditDocumentServer instance as an intermediate document on each data level that is inserted in place of the DOCVARIABLE field. Refer to the How to: Create a Master-Detail Report topic and Master-Detail Mail Merge module in the XtraRichEdit MainDemo demo for details on how to create a master-detail mail merge document.

Expanded Mail Merging Functionality in the User Interface

The RichEditControl provides the Mail Merge ribbon tab, which allows end-users to insert merge fields, toggle field codes and results and view the merged data. Refer to the How to: Create a Simple Word Processor with a Ribbon UI topic for details on how to provide the ribbon UI for the RichEditControl.

Expanded See Also

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