Mail Merge

• May 22, 2020
• 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.

NOTE

MERGEFIELD allows only plain text substitution. If a data source provides formatted text to insert in a merge field, its formatting will not be recognized and properly processed. Use DOCVARIABLE field to insert a complex content.

To perform a mail merge,MERGEFIELD fields are inserted into the text document to create a template. Field names contain data column names of the provided data source.

You should use the RichEditMailMergeOptions.DataSource property to specify a data source. This property can be accessed via the RichEditControl.Options.MailMerge.DataSource notation.

Then, when an application runs with the mail merge data source attached to the RichEditControl, the user can select the field to insert by clicking the Insert Merge Field button. The drop-down list or a dialog window containing filed names is shown:

The DevExpress Rich Edit Control allows you to customize this list and change display names of mail merge fields. This feature is useful when you wish to avoid the display of obscure or lengthy field names or simply to hide unwanted fields. Handle the RichEditControl.CustomizeMergeFields event for this purpose.

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

During mail merge you can take advantage of the special events that fire before a process is started, after the process is completed and before and after each record is merged: RichEditControl.MailMergeStarted, RichEditControl.MailMergeFinished, RichEditControl.MailMergeRecordStarted, RichEditControl.MailMergeRecordFinished.

Since the mail merge process tends to be lengthy, you can use the IProgressIndicationService to inform end-users how the merge proceeds.

You can use MERGEFIELD field nested in the INCLUDEPICTURE to insert images.

NOTE

A technique that uses DOCVARIABLE with variable name specified via the MERGEFIELD can be used to create master-detail reports, as illustrated in our demo (Master-Detail Mail Merge module).

NOTE

If you use our DXTabControl to hold several RichEditControls, as it is shown in our Master-Detail Mail Merge demo, handle the Loaded event of the RichEditControl to which you are switching to assign a mail merge data source via the MailMergeOptions.DataSource property.

The following list contains commands useful for mail merge tasks.

Command	Description
InsertMergeFieldCommand	Inserts the MERGEFIELD field at the selection.
ShowInsertMergeFieldFormCommand	Invokes a dialog window that allows for the inserting of merge fields from a data source into a document.
ShowAllFieldCodesCommand	Displays all field codes in place of the fields in the document.
ShowAllFieldResultsCommand	Displays merged data in place of field codes.
ToggleFieldCodesCommand	Toggles field code display on/off.
ToggleViewMergedDataCommand	Displays or hides data in place of the field codes.
FirstDataRecordCommand	Navigates to the first data record in the bound data source.
LastDataRecordCommand	Navigates to the last data record in the bound data source.
NextDataRecordCommand	Navigates to the next data record in the bound data source.
PreviousDataRecordCommand	Navigates to the previous data record in the bound data source.