Mail Merge
- 4 minutes to read
Perform the following steps to create the mail merge document:
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.
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;
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.
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.
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);
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. |
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 the RichEditControl with a Ribbon UI topic for details on how to provide the ribbon UI for the RichEditControl.
