You can download the complete source code of the RemoveEmptyRegions sample here.
In previous versions of Aspose.Words, mail merge regions which have been merged but which contained no data were removed from the document automatically. After upgrading you may find these regions now remain after mail merge is executed. A new feature has now been implemented which allows you to control how unused regions are handled during mail merge through the introduction of the MailMerge.CleanupOptions property. This property provides flags to control how the document is created.
By default the removal of unused regions is set to false and if unmerged regions are not removed automatically after upgrading this is the most likely reason why. If you choose to set this property before mail merge is executed then unused regions will be automatically removed.
The MailMergeCleanupOptions.RemoveUnusedRegions flag can be used to control how unused regions are handled during mail merge.
To demonstrate how this property is used, we will merge a document with an empty data source containing no data tables. It is apparent that this will result in unused regions in the document. The result after enabling the MailMerge.CleanupOptions property to true will demonstrate that the unused regions are removed automatically by the mail merge engine.
The following steps are used to demonstrate this:
1. Create an empty DataSet from an empty DataTable.
2. Enable the MailMergeCleanupOptions.RemoveUnusedRegions flag in MailMerge.CleanupOptions.
3. Merge the data with the document using the MailMerge.ExecuteWithRegions method.
The following document is used in our sample. It contains multiple regions which serve as a good example. Notice how the first region in the document includes a nested region.
The MailMergeCleanupOptions.RemoveUnusedRegions flag is enabled before mail merge is executed. This instructs the mail merge engine to remove any regions which are not merged with any data.
Example
Shows how to remove unmerged mail merge regions from the document.
[Java]
// Open the document.
Document doc = new Document(dataDir + "TestFile.doc");
// Create a dummy data source containing no data.
DataSet data = new DataSet();
// Set the appropriate mail merge clean up options to remove any unused regions from the document.
doc.getMailMerge().setCleanupOptions(MailMergeCleanupOptions.REMOVE_UNUSED_REGIONS);
// Execute mail merge which will have no effect as there is no data. However the regions found in the document will be removed
// automatically as they are unused.
doc.getMailMerge().executeWithRegions(data);
// Save the output document to disk.
doc.save(dataDir + "TestFile.RemoveEmptyRegions Out.doc");
The MailMergeCleanupOptions.RemoveUnusedRegions flag will remove any region in the document which is not found in the current data source.
If you are merging data from many data sources by using separate calls to MailMerge.ExecuteWithRegions then you need to make sure that this flag is only enabled with the very last merge. Otherwise all unused regions will be removed from the document before they can be merged.
The output below shows the result after merging the document with an empty data source and the MailMergeCleanupOptions.RemoveUnusedRegions flag to true. All of the regions which contained no data were successfully removed from the document.
You can also observe some of the related content surronding the region is not removed along with the unused region. To manually handle how a region is removed or replaced you can use the technique provided in the “Apply Custom Logic to Empty Regions” article here.