Mail Merge

• Sep 27, 2023
• 3 minutes to read

The Mail Merge retrieves data from a bound data source and fills in the fields in a document template. This feature is useful for letters, catalogs, mailing labels and for personalizing any kind of a document.

Run Demo: Built-in Mail Merge

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

• Specify the RichEdit’s data source by using the ASPxDataWebControl.DataSourceID (or ASPxDataWebControlBase.DataSource) property.

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

  Note

  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.

When an application runs with the mail merge data source attached to the ASPxRichEdit control, ribbon commands of the Mail Merge tab allow end-users to visually insert mail merge fields (placeholders for the dynamic content) from the bound data source, navigate through data source records and preview merged data.

For instance, an end-user can select the field to insert by clicking the Insert Merge Field button in the ribbon. The invoked dialog containing available filed names is shown.

End-users can also initiate the mail merge by clicking the Mail Merge ribbon button in the Finish group. The resulting merged document can be generated for all or specific data source records, and saved to a server folder or downloaded by a client.

To perform a mail merge programmatically, call the ASPxRichEdit.MailMerge method. You can pass required parameters by creating the MailMergeOptions instance using the ASPxRichEdit.CreateMailMergeOptions method and specifying it in the MailMerge call. The resulting document can be sent to another ASPxRichEdit control or to the RichEditDocumentServer instance for further processing, can be saved to a file or a Stream object.

The code sample below demonstrates how to execute a mail merge operation and open the resulting document in the Rich Text Editor:

Default.aspx

<dx:ASPxRichEdit ID="RichEdit" runat="server" Width="100%" Height="500px">
    <!-- ... -->
</dx:ASPxRichEdit>
<dx:ASPxButton runat="server" ID="Button" Text="Mail Merge" OnClick="ExecuteMailMerge" />

Default.cs

using DevExpress.XtraRichEdit;

protected void Page_Load(object sender, EventArgs e) {
    RichEdit.DataSource = DataModel.GetTestData();
    RichEdit.DataBind();
}

protected void ExecuteMailMerge(object sender, EventArgs e) {
    var myMergeOptions = RichEdit.CreateMailMergeOptions();
    myMergeOptions.DataSource = DataModel.GetTestData();
    myMergeOptions.MergeMode = DevExpress.XtraRichEdit.API.Native.MergeMode.NewSection;
    using (MemoryStream stream = new MemoryStream()) {
        RichEdit.MailMerge(myMergeOptions, stream, DocumentFormat.Rtf);
        stream.Position = 0;
        RichEdit.Open(Guid.NewGuid().ToString(), DocumentFormat.Rtf, () => { return stream; });
    }
}

DataModel.cs

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 static class DataModel {

    public static List<Company> GetTestData() {
        var data = 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]"}
            };
        return data;
    }
}