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.

Word document generated with mail merge process that has clear options defined
Screenshot of executed mail merge with clear options
Upload your file (Drag file here)
using GemBox.Document;
using GemBox.Document.MailMerging;

class Program
{
    static void Main()
    {
        // If using Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY");

        var document = DocumentModel.Load("%InputFileName%");

        // 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 Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY")

        Dim document = DocumentModel.Load("%InputFileName%")

        ' 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.

Want more?

Next example GitHub

Check the next example or select an example from the menu. You can also download our examples from the GitHub.


Like it?

Download Buy

If you want to try the GemBox.Document yourself, you can download the free version. It delivers the same performance and set of features as the professional version, but with some operations limited. To remove the limitation, you need to purchase a license.