RichEditControl.MailMerge(MailMergeOptions, String, DocumentFormat) Method

Merges the current document using the specified options and saves the result to the specified file and format.

Namespace: DevExpress.XtraRichEdit

Assembly: DevExpress.XtraRichEdit.v20.2.dll

NuGet Package: DevExpress.Win.RichEdit

Declaration

C#

public void MailMerge(
    MailMergeOptions options,
    string fileName,
    DocumentFormat format
)

VB.NET

Public Sub MailMerge(
    options As MailMergeOptions,
    fileName As String,
    format As DocumentFormat
)

Parameters

Name	Type	Description
options	MailMergeOptions	A MailMergeOptions interface exposing options for the merge.
fileName	String	A name of the file to which the merged document is saved.
format	DocumentFormat	A DocumentFormat enumeration member specifying the destination format.

Remarks

The MailMerge method merges the document with records, starting from the MailMergeOptions.FirstRecordIndex through the MailMergeOptions.LastRecordIndex.

Use the MailMergeOptions object to provide mail merge options (data source, the range of records to merge, etc.)

The MailMerge method fires the RichEditControl.CalculateDocumentVariable event.

Example

The following code creates a data source and performs mail merge using the document template. The MailMergeOptions object is created in code, used to specify data rows and merge mode and is subsequently passed to the RichEditControl.MailMerge method. The current RichEditControl instance is passed to the BarItem.ItemClick event handler using the BarItem.Tag property.

View Example

RichEditControlActions.cs

static void buttonCustomAction_ItemClick_MailMergeMethod(object sender, ItemClickEventArgs e) {
    RichEditControl richEdit = e.Item.Tag as RichEditControl;
    richEdit.LoadDocument("Documents\\MailMergeSimple.rtf", DevExpress.XtraRichEdit.DocumentFormat.Rtf);
    System.Data.DataTable MailMergeDataSource = new System.Data.DataTable();
    MailMergeDataSource.Columns.Add("FirstName");
    MailMergeDataSource.Columns.Add("LastName");
    MailMergeDataSource.Columns.Add("HiringDate");
    MailMergeDataSource.Columns.Add("Address");
    MailMergeDataSource.Columns.Add("City");
    MailMergeDataSource.Columns.Add("Country");
    MailMergeDataSource.Columns.Add("Position");
    MailMergeDataSource.Columns.Add("CompanyName");
    MailMergeDataSource.Columns.Add("Gender");
    MailMergeDataSource.Columns.Add("Phone");
    MailMergeDataSource.Columns.Add("HRManagerName");

    string[] firstName = { "Nancy", "Andrew", "Janet", "Margaret", 
                             "Steven", "Michael", "Robert", "Laura", "Anne" };

    string[] lastName = { "Davolio", "Fuller", "Leverling", "Peacock", 
                            "Buchanan", "Suyama", "King", "Callahan", "Dodsworth" };

    string[] city = { "Seattle", "Tacoma", "Kirkland", "Redmond", "London",                                 
                        "London", "London", "Seattle", "London" };

    string[] country = { "USA", "USA", "USA", "USA", 
                           "UK", "UK", "UK", "USA", "UK" };

    string[] address = { "507 - 20th Ave. E. Apt. 2A", "908 W. Capital Way", "722 Moss Bay Blvd.", 
                           "4110 Old Redmond Rd.", "14 Garrett Hill", "Coventry House Miner Rd.", 
                           "Edgeham Hollow Winchester Way", "4726 - 11th Ave. N.E.", "7 Houndstooth Rd." };

    string[] position = { "Sales Representative", "Vice President, Sales", "Sales Representative", 
                            "Sales Representative", "Sales Manager", "Sales Representative", 
                            "Sales Representative", "Inside Sales Coordinator", "Sales Representative" };

    char[] gender = { 'F', 'M', 'F', 'F', 'M', 'M', 'M', 'F', 'F' };
    string[] phone = { "[phone]", "[phone]", "[phone]", "[phone]", 
                         "(71) 555-4848", "(71) 555-7773", "(71) 555-5598", "[phone]", "(71) 555-4444" };

    string[] companyName = { "Consolidated Holdings", "Around the Horn", "North/South", "Island Trading", 
                               "White Clover Markets", "Trail's Head Gourmet Provisioners", "The Cracker Box", 
                               "The Big Cheese", "Rattlesnake Canyon Grocery", "Split Rail Beer & Ale", 
                               "Hungry Coyote Import Store", "Great Lakes Food Market" };

    Random rnd = new Random();
    for(int i = 0; i < 9; i++) {
        MailMergeDataSource.Rows.Add(new object[] { 
            firstName[i], 
            lastName[i], 
            DateTime.Now.AddDays(-(rnd.Next(0, 2000))), 
            address[i], 
            city[i], 
            country[i], 
            position[i], 
            companyName[i], 
            gender[i], 
            phone[i], 
            "Dan Marino" });
    }

    MailMergeOptions options = richEdit.CreateMailMergeOptions();
    options.DataSource = MailMergeDataSource;
    options.FirstRecordIndex = 2;
    options.LastRecordIndex = 5;
    options.MergeMode = MergeMode.NewSection;

    using(FileStream fsResult = new FileStream("MailMergeResult.rtf", FileMode.OpenOrCreate)) {
        richEdit.MailMerge(options, fsResult, DevExpress.XtraRichEdit.DocumentFormat.Rtf);
    }
    System.Diagnostics.Process.Start("MailMergeResult.rtf");
}

RichEditControlActions.vb

Private Shared Sub buttonCustomAction_ItemClick_MailMergeMethod(ByVal sender As Object, ByVal e As ItemClickEventArgs)
    Dim richEdit As RichEditControl = TryCast(e.Item.Tag, RichEditControl)
    richEdit.LoadDocument("Documents\MailMergeSimple.rtf", DevExpress.XtraRichEdit.DocumentFormat.Rtf)
    Dim MailMergeDataSource As New System.Data.DataTable()
    MailMergeDataSource.Columns.Add("FirstName")
    MailMergeDataSource.Columns.Add("LastName")
    MailMergeDataSource.Columns.Add("HiringDate")
    MailMergeDataSource.Columns.Add("Address")
    MailMergeDataSource.Columns.Add("City")
    MailMergeDataSource.Columns.Add("Country")
    MailMergeDataSource.Columns.Add("Position")
    MailMergeDataSource.Columns.Add("CompanyName")
    MailMergeDataSource.Columns.Add("Gender")
    MailMergeDataSource.Columns.Add("Phone")
    MailMergeDataSource.Columns.Add("HRManagerName")

    Dim firstName() As String = {"Nancy", "Andrew", "Janet", "Margaret",
                                 "Steven", "Michael", "Robert", "Laura", "Anne"}

    Dim lastName() As String = {"Davolio", "Fuller", "Leverling", "Peacock",
                                "Buchanan", "Suyama", "King", "Callahan", "Dodsworth"}

    Dim city() As String = {"Seattle", "Tacoma", "Kirkland", "Redmond",
                            "London", "London", "London", "Seattle", "London"}

    Dim country() As String = {"USA", "USA", "USA", "USA",
                               "UK", "UK", "UK", "USA", "UK"}

    Dim address() As String = {"507 - 20th Ave. E. Apt. 2A", "908 W. Capital Way", "722 Moss Bay Blvd.",
                               "4110 Old Redmond Rd.", "14 Garrett Hill", "Coventry House Miner Rd.",
                               "Edgeham Hollow Winchester Way", "4726 - 11th Ave. N.E.", "7 Houndstooth Rd."}

    Dim position() As String = {"Sales Representative", "Vice President, Sales", "Sales Representative",
                                "Sales Representative", "Sales Manager", "Sales Representative",
                                "Sales Representative", "Inside Sales Coordinator", "Sales Representative"}

    Dim gender() As Char = {"F"c, "M"c, "F"c, "F"c, "M"c, "M"c, "M"c, "F"c, "F"c}

    Dim phone() As String = {"[phone]", "[phone]", "[phone]", "[phone]",
                             "(71) 555-4848", "(71) 555-7773", "(71) 555-5598", "[phone]", "(71) 555-4444"}

    Dim companyName() As String = {"Consolidated Holdings", "Around the Horn", "North/South", "Island Trading",
                                   "White Clover Markets", "Trail's Head Gourmet Provisioners", "The Cracker Box",
                                   "The Big Cheese", "Rattlesnake Canyon Grocery", "Split Rail Beer & Ale",
                                   "Hungry Coyote Import Store", "Great Lakes Food Market"}

    Dim rnd As New Random()
    For i As Integer = 0 To 8
        MailMergeDataSource.Rows.Add(New Object() {
                                     firstName(i),
                                     lastName(i),
                                     DateTime.Now.AddDays(-(rnd.Next(0, 2000))),
                                     address(i),
                                     city(i),
                                     country(i),
                                     position(i),
                                     companyName(i),
                                     gender(i),
                                     phone(i),
                                     "Dan Marino"})
    Next i

    Dim options As MailMergeOptions = richEdit.CreateMailMergeOptions()
    options.DataSource = MailMergeDataSource
    options.FirstRecordIndex = 2
    options.LastRecordIndex = 5
    options.MergeMode = MergeMode.NewSection

    Using fsResult As New System.IO.FileStream("MailMergeResult.rtf", System.IO.FileMode.OpenOrCreate)
        richEdit.MailMerge(options, fsResult, DevExpress.XtraRichEdit.DocumentFormat.Rtf)
    End Using
    System.Diagnostics.Process.Start("MailMergeResult.rtf")
End Sub