Aspose.Words

How-to: Remove Unmerged Fields and Empty Paragraphs during Mail Merge

When merging data into a document you often require control over how unmerged merge fields are removed from a document. For instance you may want to have any leftover merge fields removed, along with any surronding fields. You may also wish to remove any paragraphs that become empty during mail merge.

The MailMerge.CleanupOptions property is used along with the MailMergeCleanupOptions enumeration to specify different options on how the mail merge engine deals with such left over merge fields.

The members of the MailMergeCleanupOptions enumeration are flags so that a combination of the different cleanup options can be used simultaneously.

The following diagram gives a general demonstration of how the different cleanup options will remove different field constructions during mail merge.

Given that the Amount field was not merged with any data:

·          If the MailMergeCleanupOptions.RemoveUnusedFields flag is enabled by itself then the Amount merge field is removed. The outer IF field and paragraph still remains and the IF field maybe updated with an error code as the left hand side of the expression is missing.

·          If the MailMergeCleanupOptions.RemoveContainingFields flag is enabled then not only would the merge field be removed, but also the outer IF field is removed as well leaving just the plain text result of the IF field.

·          If the MailMergeCleanupOptions.RemoveEmptyParagraphs flag is enabled then in addition, if the paragraph content became empty (for example if the result of the IF field happened to be empty text or spaces) then the entire paragraph would be removed.

It’s useful to note that if you are merging data using separate data sources then these options should be enabled only on the last execute call. This is so no fields or regions are prematurely removed the document.

Removing Merge Fields

You can request the mail merge engine to remove any unused mail merge fields automatically during mail merge by applying the MailMergeCleanupOptions.RemoveUnusedFields flag to MailMerge.CleanupOptions.

Example MailMergeRemoveUnusedFields

Shows how to automatically remove unmerged merge fields during mail merge.

[Java]

 

doc.getMailMerge().setCleanupOptions(MailMergeCleanupOptions.REMOVE_UNUSED_FIELDS);

 

 

Removing Containing Fields

Commonly a merge field can be contained within another field such as an IF field or a formula field. Aspose.Words provides an option to remove this outer field when the merge field is merged or removed from the document. To remove such containing fields you can enable the MailMergeCleanupOptions.RemoveContainingFields flag with MailMerge.CleanupOptions.

This option is used to match the behavior of Microsoft Word during mail merge which always automatically removes outer fields from a field which is merged and leaves only the plain text result.

Note that this option will only remove a containing field if the field was actually merged with data or if the merge field was removed by using the MailMergeCleanupOptions.RemoveUnusedFields option.

Example MailMergeRemoveContainingFields

Shows how to instruct the mail merge engine to remove any containing fields from around a merge field during mail merge.

[Java]

 

doc.getMailMerge().setCleanupOptions(MailMergeCleanupOptions.REMOVE_CONTAINING_FIELDS);

 

 

Removing Empty Paragraphs

Sometimes you may need to completely remove paragraphs that contained mail merge fields which became empty during mail merge. For example, the mail merge field could be merged with empty data or the merge field removed because it was unused.

In either of those two situations the MailMergeCleanupOptions.RemoveEmptyParagraphs flag will automatically remove such empty paragraphs from the document during mail merge.

Additionally, this option will also remove any TableStart and TableEnd merge fields if the rest of the paragraph is empty. This can be used to combine the tables inside a region into one automatically during mail merge.

Example MailMergeRemoveEmptyParagraphs

Shows how to make sure empty paragraphs that result from merging fields with no data are removed from the document.

[Java]

 

doc.getMailMerge().setCleanupOptions(MailMergeCleanupOptions.REMOVE_EMPTY_PARAGRAPHS);