Mail Merge

• Aug 08, 2024
• 5 minutes to read

The mail merge functionality enables you to bind the control to an external data source, preview dynamic content in the opened document template, and generate the resulting document with merged data.

Run Demo

Follow the steps below to execute the mail merge.

Step 1. Specify a Data Source

A data source contains data that is merged into a document template. Specify a data source either at the server side, at the client side, or at runtime.

.NET Core Server Settings

@(Html.DevExpress().RichEdit("richEdit")
    .MailMerge(m => m
        .DataSource(newDataSource.Companies)
    )
)

Client Settings

const options = DevExpress.RichEdit.createOptions();
options.mailMerge.dataSource = newDataSource;

Runtime Settings

richEdit.mailMergeOptions.setDataSource(newDataSource);

Show the data sources

.NET Core Server Data Source

using System.Collections.Generic;
namespace AspNetCoreDemos.RichEdit.Models {
    public class Company {
        public int ID { get; set; }
        public string Name { get; set; }
        public string Address { get; set; }
        public string City { get; set; }
        public string Phone { get; set; }
    }
    public partial class newDataSource  {
        public static List<Company> Companies = new List<Company> {
            new Company {ID = 1, Name = "Super Mart of the West", Address = "702 SW 8th Street", City = "Bentonville", Phone = "[phone]"},
            new Company {ID = 2, Name = "Electronics Depot", Address = "2455 Paces Ferry Road NW", City = "Atlanta", Phone = "[phone]"},
            new Company { ID = 3, Name = "K&S Music", Address = "1000 Nicllet Mall", City = "Minneapolis", Phone = "[phone]"},
            new Company { ID = 4, Name = "Tom's Club", Address = "999 Lake Drive", City = "Issaquah", Phone = "[phone]"}
        };
    }
}

Client Data Source

var newDataSource = [
    { ID: 1, Name: "Super Mart of the West", Address: "702 SW 8th Street", City: "Bentonville", Phone: "[phone]" },
    { ID: 2, Name: "Electronics Depot", Address: "2455 Paces Ferry Road NW", City: "Atlanta", Phone: "[phone]" },
    { ID: 3, Name: "K&S Music", Address: "1000 Nicllet Mall", City: "Minneapolis", Phone: "[phone]" },
    { ID: 4, Name: "Tom's Club", Address: "999 Lake Drive", City: "Issaquah", Phone: "[phone]" }
];

Data Source for Runtime Binding

var newDataSource = [
    { ID: 1, Name: "Super Mart of the West", Address: "702 SW 8th Street", City: "Bentonville", Phone: "[phone]" },
    { ID: 2, Name: "Electronics Depot", Address: "2455 Paces Ferry Road NW", City: "Atlanta", Phone: "[phone]" },
    { ID: 3, Name: "K&S Music", Address: "1000 Nicllet Mall", City: "Minneapolis", Phone: "[phone]" },
    { ID: 4, Name: "Tom's Club", Address: "999 Lake Drive", City: "Issaquah", Phone: "[phone]" }
];

The RichEdit control cannot get data from a nested field. If your data source contains complex fields, modify the data source before binding the control.

JS

var data = [
    { ID: 1, Name: "Super Mart of the West", Contacts: { Address: "702 SW 8th Street", City: "Bentonville", Phone: "[phone]" } },
    { ID: 2, Name: "Electronics Depot", Contacts: { Address: "2455 Paces Ferry Road NW", City: "Atlanta", Phone: "[phone]" } },
    { ID: 3, Name: "K&S Music", Contacts: { Address: "1000 Nicllet Mall", City: "Minneapolis", Phone: "[phone]" } },
    { ID: 4, Name: "Tom's Club", Contacts: { Address: "999 Lake Drive", City: "Issaquah", Phone: "[phone]" } }
];
var selector = function(dataItem) {
    return {
        ID: dataItem.ID,
        Name: dataItem.Name,
        Address: dataItem.Contacts.Address,
        City: dataItem.Contacts.City,
        Phone: dataItem.Contacts.Phone,
    };
};
var newDataSource = new DevExpress.data.DataSource({store: data, select: selector });
richEdit.mailMergeOptions.setDataSource(newDataSource);

Step 2. Create a Document Template

Add { MERGEFIELD "field name" } fields to a document to create a document template. These fields are placeholders for the information that is merged from the data source. A field’s field name parameter should refer to a data source field’s name.

Call the createMergeField(position, name) method to add the MERGEFIELD field to a document.

JS

// inserts the {MERGEFIELD "City"} field at the current position
richEdit.selection.activeSubDocument.fields.createMergeField(richEdit.selection.active, 'City');

Note

The MERGEFIELD field only enables you to substitute plain text. To insert formatted content, use the DOCVARIABLE field.

Step 3. Preview Merged Data

The Rich Text Editor can display the data of an active record in the document template. It also allows you to navigate through data records.

Set the viewMergedData property to true to display the merged data. The activeRecord property specifies the currently visible data record.

.NET Core Server Settings

@(Html.DevExpress().RichEdit("richEdit")
    .MailMerge(m => m
        .ViewMergedData(true)
        .ActiveRecord(0)
      ...

Client Settings

options.mailMerge.viewMergedData = true;
options.mailMerge.activeRecord = 0;

Runtime Settings

richEdit.mailMergeOptions.viewMergedData = true;
richEdit.mailMergeOptions.activeRecordIndex = 0;

Call the executeCommand(commandId) method with the corresponding command as a parameter to navigate through data records in code.

JS

// Navigate to the first data record.
richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.GoToFirstDataRecord);
// Navigate to the last data record.
richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.GoToLastDataRecord);
// Navigate to the next data record.
richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.GoToNextDataRecord);
// Navigate to the previous data record.
richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.GoToPreviousDataRecord);

Step 4. Merge the Document

Call the mailMerge(callback) method to merge the document. The method merges every record of the bound data to the document template. The resulting document contains the merged templates separated by a paragraph or a section (based on the mergeMode method parameter). When the document is ready, the control calls the callback function. The function gets the merged document as a parameter and allows you to further process the document (for instance, save or load it to the control).

The code sample below demonstrates how to load the resulting mail merge document to the RichEdit control.

JS

var format = DevExpress.RichEdit.DocumentFormat.OpenXml;
richEdit.mailMerge(function (mergedDocument) {
    richEdit.openDocument(mergedDocument, "MergedDocument", format);
}, DevExpress.RichEdit.MergeMode.NewParagraph, format);

The Mail Merge Ribbon Tab

When the RichEdit control is bound to a data source, the Mail Merge ribbon tab allows you to do the following:

• Insert merge fields from the bound data source.

  

• View merged data.
• Navigate through data source records.
• Merge the document and download the result.