Mail Merge Clear Options

The GemBox.Document mail merge process allows you to remove or clear various parts of the document if the mail merge operation doesn't import any data 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 or the whole merge range, if no data has been imported or 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 "Example2" merge range.
        // Also, remove the range if all fields didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyRanges;
        document.MailMerge.Execute(data, "Example3");

        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 "Example2" merge range.
        ' Also, remove the range if all fields didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyRanges
        document.MailMerge.Execute(data, "Example3")

        document.Save("Merged Clear Options Output.%OutputFileType%")

    End Sub
End Module

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.