How to: Perform a Mail Merge
- 5 minutes to read
The following sections describe a mail merge implementation:
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 IList interface.
In most cases you can use objects which expose the ArrayList interface or external databases available as DataTable objects (via corresponding data adapters).
The following code creates a sample ArrayList data source.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/how-to-implement-mail-merge-in-a-richeditcontrol-e1680
class SampleData : System.Collections.ArrayList
{
public SampleData()
{
Add(new AddresseeRecord("Andrew", "XYZ Inc.", "Tullamore Way, 21"));
Add(new AddresseeRecord("Benny", "ABC Ltd.", "Casablanca Rd., 46"));
Add(new AddresseeRecord("Jose", "CASA S.A.", "Paseo di Ronda, 88"));
}
}
public class AddresseeRecord
{
public string Name { get; set; }
public string Company { get; set; }
public string Address { get; set; }
public AddresseeRecord(string fName, string fCompany, string fAddress)
{
Name = fName;
Company = fCompany;
Address = fAddress;
}
}
The mail merge data source is specified via the RichEditMailMergeOptions.DataSource property.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/how-to-implement-mail-merge-in-a-richeditcontrol-e1680
richEditControl1.Options.MailMerge.DataSource = new SampleData();
richEditControl1.Options.MailMerge.ViewMergedData = true;
A mail merge document is not complete until it is assigned appropriate data fields names. After providing the data source, proceed to creating fields.
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.
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.
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).
Note
A complete sample project is available at https://github.com/DevExpress-Examples/how-to-implement-mail-merge-in-a-richeditcontrol-e1680
using DevExpress.XtraRichEdit.API.Native;
MailMergeOptions myMergeOptions = richEditControl1.Document.CreateMailMergeOptions();
myMergeOptions.FirstRecordIndex = 1;
myMergeOptions.LastRecordIndex = 3;
myMergeOptions.MergeMode = MergeMode.NewSection;
richEditControl1.Document.MailMerge(myMergeOptions, richEditControl2.Document);
Tip
You can export each merged record to a new PDF file. Refer to the E4308 example for details.