Mail Merge

• Nov 16, 2018
• 3 minutes to read

Perform the following steps to create the mail merge document:

1. Provide a Data Source
2. Load a Document Template
3. Merge and Save the 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. RichEditDocumentServer supports the following data source types:

• System.Collections.IList;
• System.Collections.ArrayList;
• System.Data.DataTable.

C#

server.Options.MailMerge.DataSource = new SampleData();
server.Options.MailMerge.ViewMergedData = true;

VB.NET

server.Options.MailMerge.DataSource = New SampleData()
server.Options.MailMerge.ViewMergedData = True

Load a Document Template

Call the RichEditDocumentServer.LoadDocument or RichEditDocumentServer.LoadDocumentTemplate method to 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 RichEditDocumentServer instance, or save it to the file.

C#

using DevExpress.XtraRichEdit.API.Native;

...

MailMergeOptions myMergeOptions = server.Document.CreateMailMergeOptions();           
myMergeOptions.MergeMode = MergeMode.NewSection;
server.Document.MailMerge(myMergeOptions, "Result.docx", DocumentFormat.OpenXml);

VB.NET

Imports DevExpress.XtraRichEdit.API.Native

...

Dim myMergeOptions As MailMergeOptions = server.Document.CreateMailMergeOptions()
myMergeOptions.MergeMode = MergeMode.NewSection
server.Document.MailMerge(myMergeOptions, "Result.docx", DocumentFormat.OpenXml)

Mail Merge Events

Additionally, the RichEditDocumentServer provides the following events allowing you to control specific mail merging steps:

Event	Description
RichEditDocumentServer.MailMergeStarted	Fires before mail merge starts.
RichEditDocumentServer.MailMergeFinished	Fires when mail merge is completed.
RichEditDocumentServer.MailMergeRecordStarted	Fires before each data record is merged with the document in the mail merge process.
RichEditDocumentServer.MailMergeRecordFinished	Fires after each data record is merged with the document in the mail merge process.

Master-Detail Mail Merge Documents

The master-detail report requires creating a RichEditDocumentServer instance as an intermediate document on each data level that is inserted in place of the DOCVARIABLE field. Refer to the Master-Detail Report topic for details on how to create a master-detail mail merge document.

Tip

You can transform a mail merge template to a self-contained document in the same RichEditDocumentServer instance by using current data. Refer to the How to replace document fields with their values example for details.