Mail Merge Clear Options
The GemBox.Document mail merge process allows you to remove or clear various parts of the document using MailMergeClearOptions, if no data has been merged or imported to that part of the document.
A merge field is considered to be merged if its data source value is defined, not null and empty.
The following example shows how you can perform mail merge operations with specified clear options for removing fields, paragraphs, rows, tables, or the whole merge range if no data has been merged into them.
using GemBox.Document;
using GemBox.Document.MailMerging;
class Program
{
static void Main()
{
// If using the Professional version, put your serial key below.
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
var document = DocumentModel.Load("%#MergeClearOptions.docx%");
// Data source with "Populated" value, but no "Empty" value.
var data = new { Populated = "sample value" };
// Execute mail merge on "Example1" merge range.
// Also, remove fields and paragraphs that didn't merge in this range.
document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveUnusedFields | MailMergeClearOptions.RemoveEmptyParagraphs;
document.MailMerge.Execute(data, "Example1");
// Execute mail merge on "Example2" merge range.
// Also, remove rows that didn't merge in this range.
document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyTableRows;
document.MailMerge.Execute(data, "Example2");
// Execute mail merge on "Example3" merge range.
// Also, remove fields and tables that didn't merge in this range.
document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveUnusedFields | MailMergeClearOptions.RemoveEmptyTables;
document.MailMerge.Execute(data, "Example3");
// Execute mail merge on "Example4" merge range.
// Also, remove the range if all fields didn't merge in this range.
document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyRanges;
document.MailMerge.Execute(data, "Example4");
document.Save("Merged Clear Options Output.%OutputFileType%");
}
}
Imports GemBox.Document
Imports GemBox.Document.MailMerging
Module Program
Sub Main()
' If using the Professional version, put your serial key below.
ComponentInfo.SetLicense("FREE-LIMITED-KEY")
Dim document = DocumentModel.Load("%#MergeClearOptions.docx%")
' Data source with "Populated" value, but no "Empty" value.
Dim data As New With {.Populated = "sample value"}
' Execute mail merge on "Example1" merge range.
' Also, remove fields and paragraphs that didn't merge in this range.
document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveUnusedFields Or MailMergeClearOptions.RemoveEmptyParagraphs
document.MailMerge.Execute(data, "Example1")
' Execute mail merge on "Example2" merge range.
' Also, remove rows that didn't merge in this range.
document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyTableRows
document.MailMerge.Execute(data, "Example2")
' Execute mail merge on "Example3" merge range.
' Also, remove fields and tables that didn't merge in this range.
document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveUnusedFields Or MailMergeClearOptions.RemoveEmptyTables
document.MailMerge.Execute(data, "Example3")
' Execute mail merge on "Example4" merge range.
' Also, remove the range if all fields didn't merge in this range.
document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyRanges
document.MailMerge.Execute(data, "Example4")
document.Save("Merged Clear Options Output.%OutputFileType%")
End Sub
End Module
Note, when starting the mail merge process, GemBox.Document will first locate a merge range in which it will operate. If the range name is resolved to a null or empty value, then the whole document is taken as the merge range.
In that case, if no data was merged, MailMergeClearOptions.RemoveEmptyRanges will remove the whole document content. To avoid this, you can specify the range name using the MailMerge.Execute overload method, as shown in the example above.
For more information, see the Mail merge process help page.
