com.aspose.words

Class MailMerge

java.lang.Object

com.aspose.words.MailMerge

public class MailMerge
extends java.lang.Object

Represents the mail merge functionality.

To learn more, visit the Mail Merge and Reporting documentation article.

Remarks:

For mail merge operation to work, the document should contain Word MERGEFIELD and optionally NEXT fields. During mail merge operation, merge fields in the document are replaced with values from your data source.

There are two distinct ways to use mail merge: with mail merge regions and without.

The simplest mail merge is without regions and it is very similar to how mail merge works in Word. Use Execute methods to merge information from some data source such as DataTable, DataSet or an array of objects into your document. The MailMerge object processes all records of the data source and copies and appends content of the whole document for each record.

Note that when MailMerge object encounters a NEXT field, it selects next record in the data source and continues merging without copying any content.

Use executeWithRegions(com.aspose.words.IMailMergeDataSource) and other overloads to merge information into a document with mail merge regions defined. You can use DataTable or DataSet as data sources for this operation.

You need to use mail merge regions if you want to dynamically grow portions inside the document. Without mail merge regions whole document will be repeated for every record of the data source.

Examples:

Shows how to execute a mail merge with data from a DataTable.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertField(" MERGEFIELD CustomerName ");
 builder.insertParagraph();
 builder.insertField(" MERGEFIELD Address ");

 // This example creates a table, but you would normally load table from a database
 DataTable table = new DataTable("Test");
 table.getColumns().add("CustomerName");
 table.getColumns().add("Address");
 table.getRows().add("Thomas Hardy", "120 Hanover Sq., London");
 table.getRows().add("Paolo Accorti", "Via Monte Bianco 34, Torino");

 // Field values from the table are inserted into the mail merge fields found in the document
 doc.getMailMerge().execute(table);

 doc.save(getArtifactsDir() + "MailMerge.ExecuteDataTable.docx");

 // Create a copy of our document to perform another mail merge
 doc = new Document();
 builder = new DocumentBuilder(doc);
 builder.insertField(" MERGEFIELD CustomerName ");
 builder.insertParagraph();
 builder.insertField(" MERGEFIELD Address ");

 // We can also source values for a mail merge from a single row in the table
 doc.getMailMerge().execute(table.getRows().get(1));

 doc.save(getArtifactsDir() + "MailMerge.ExecuteDataTable.OneRow.docx");
 
 

See Also:

Document, Document.getMailMerge()

Method Summary

Modifier and Type	Method and Description
void	deleteFields() Removes mail merge related fields from the document.
void	execute(DataRow row) Performs mail merge from a DataRow into the document.
void	execute(DataTable table) Performs mail merge from a com.aspose.words.net.System.Data.DataTable into the document.
void	execute(DataView dataView) Performs mail merge from a DataView into the document.
void	execute(IDataReader dataReader) Performs mail merge from IDataReader into the document.
void	execute(IMailMergeDataSource dataSource) Performs a mail merge from a custom data source.
void	execute(java.lang.String[] fieldNames, java.lang.Object[] values) Performs a mail merge operation.
void	executeWithRegions(DataSet dataSet) Performs a mail merge operation into a document with mail merge regions.
void	executeWithRegions(DataTable dataTable) Performs mail merge from a DataTable into the document with mail merge regions.
void	executeWithRegions(DataView dataView) Performs mail merge from a DataView into the document with mail merge regions.
void	executeWithRegions(IDataReader dataReader, java.lang.String tableName) Performs mail merge from IDataReader into the document with mail merge regions.
void	executeWithRegions(IMailMergeDataSource dataSource) Performs a mail merge from a custom data source with mail merge regions.
void	executeWithRegions(IMailMergeDataSourceRoot dataSourceRoot) Performs a mail merge from a custom data source with mail merge regions.
int	getCleanupOptions() Gets a set of flags that specify what items should be removed during mail merge.
boolean	getCleanupParagraphsWithPunctuationMarks() Gets a value indicating whether paragraphs with punctuation marks are considered as empty and should be removed if the MailMergeCleanupOptions.REMOVE_EMPTY_PARAGRAPHS option is specified.
IFieldMergingCallback	getFieldMergingCallback() Occurs during mail merge when a mail merge field is encountered in the document.
java.lang.String[]	getFieldNames() Returns a collection of mail merge field names available in the document.
java.lang.String[]	getFieldNamesForRegion(java.lang.String regionName) Get mail merge field names from the region.
java.lang.String[]	getFieldNamesForRegion(java.lang.String regionName, int regionIndex) Returns a collection of mail merge field names available in the region.
IMailMergeCallback	getMailMergeCallback() Allows to handle particular events during mail merge.
MappedDataFieldCollection	getMappedDataFields() Returns a collection that represents mapped data fields for the mail merge operation.
boolean	getMergeDuplicateRegions() Gets a value indicating whether all of the document mail merge regions with the name of a data source should be merged while executing of a mail merge with regions against the data source or just the first one.
boolean	getMergeWholeDocument() Gets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.
boolean	getPreserveUnusedTags() Gets a value indicating whether the unused "mustache" tags should be preserved.
java.lang.String	getRegionEndTag() Gets a mail merge region end tag.
java.util.ArrayList	getRegionsByName(java.lang.String regionName) Returns a collection of mail merge regions with the specified name.
MailMergeRegionInfo	getRegionsHierarchy() Returns a full hierarchy of regions (with fields) available in the document.
java.lang.String	getRegionStartTag() Gets a mail merge region start tag.
boolean	getRestartListsAtEachSection() Gets a value indicating whether lists are restarted at each section after executing of a mail merge.
boolean	getRetainFirstSectionStart() Gets a value indicating whether the PageSetup.getSectionStart() / PageSetup.setSectionStart(int) of the first document section and its copies for subsequent data source rows are retained during mail merge or updated according to MS Word behaviour.
boolean	getTrimWhitespaces() Gets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values.
boolean	getUnconditionalMergeFieldsAndRegions() Gets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field's condition.
boolean	getUseNonMergeFields() When true, specifies that in addition to MERGEFIELD fields, mail merge is performed into some other types of fields and also into "{{fieldName}}" tags.
boolean	getUseWholeParagraphAsRegion() Gets a value indicating whether whole paragraph with TableStart or TableEnd field or particular range between TableStart and TableEnd fields should be included into mail merge region.
void	setCleanupOptions(int value) Sets a set of flags that specify what items should be removed during mail merge.
void	setCleanupParagraphsWithPunctuationMarks(boolean value) Sets a value indicating whether paragraphs with punctuation marks are considered as empty and should be removed if the MailMergeCleanupOptions.REMOVE_EMPTY_PARAGRAPHS option is specified.
void	setFieldMergingCallback(IFieldMergingCallback value) Occurs during mail merge when a mail merge field is encountered in the document.
void	setMailMergeCallback(IMailMergeCallback value) Allows to handle particular events during mail merge.
void	setMergeDuplicateRegions(boolean value) Sets a value indicating whether all of the document mail merge regions with the name of a data source should be merged while executing of a mail merge with regions against the data source or just the first one.
void	setMergeWholeDocument(boolean value) Sets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.
void	setPreserveUnusedTags(boolean value) Sets a value indicating whether the unused "mustache" tags should be preserved.
void	setRegionEndTag(java.lang.String value) Sets a mail merge region end tag.
void	setRegionStartTag(java.lang.String value) Sets a mail merge region start tag.
void	setRestartListsAtEachSection(boolean value) Sets a value indicating whether lists are restarted at each section after executing of a mail merge.
void	setRetainFirstSectionStart(boolean value) Sets a value indicating whether the PageSetup.getSectionStart() / PageSetup.setSectionStart(int) of the first document section and its copies for subsequent data source rows are retained during mail merge or updated according to MS Word behaviour.
void	setTrimWhitespaces(boolean value) Sets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values.
void	setUnconditionalMergeFieldsAndRegions(boolean value) Sets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field's condition.
void	setUseNonMergeFields(boolean value) When true, specifies that in addition to MERGEFIELD fields, mail merge is performed into some other types of fields and also into "{{fieldName}}" tags.
void	setUseWholeParagraphAsRegion(boolean value) Sets a value indicating whether whole paragraph with TableStart or TableEnd field or particular range between TableStart and TableEnd fields should be included into mail merge region.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

execute

public void execute(IMailMergeDataSource dataSource)
             throws java.lang.Exception

Performs a mail merge from a custom data source.

Remarks:

Use this method to fill mail merge fields in the document with values from any data source such as a list or hashtable or objects. You need to write your own class that implements the IMailMergeDataSource interface.

You can use this method only when FieldOptions.isBidiTextSupportedOnUpdate() / FieldOptions.isBidiTextSupportedOnUpdate(boolean) is false, that is you do not need Right-To-Left language (such as Arabic or Hebrew) compatibility.

This method ignores the MailMergeCleanupOptions.REMOVE_UNUSED_REGIONS option.

Examples:

Shows how to execute a mail merge with a data source in the form of a custom object.

 
 public void customDataSource() throws Exception {
     // Create a destination document for the mail merge
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);
     builder.insertField(" MERGEFIELD FullName ");
     builder.insertParagraph();
     builder.insertField(" MERGEFIELD Address ");

     // Create some data that we will use in the mail merge
     CustomerList customers = new CustomerList();
     customers.add(new Customer("Thomas Hardy", "120 Hanover Sq., London"));
     customers.add(new Customer("Paolo Accorti", "Via Monte Bianco 34, Torino"));

     // To be able to mail merge from your own data source, it must be wrapped
     // into an object that implements the IMailMergeDataSource interface
     CustomerMailMergeDataSource customersDataSource = new CustomerMailMergeDataSource(customers);

     // Now you can pass your data source into Aspose.Words
     doc.getMailMerge().execute(customersDataSource);

     doc.save(getArtifactsDir() + "MailMergeCustom.CustomDataSource.docx");
 }

 // An example of a "data entity" class in your application.
 public class Customer {
     public Customer(final String aFullName, final String anAddress) {
         mFullName = aFullName;
         mAddress = anAddress;
     }

     public String getFullName() {
         return mFullName;
     }

     public void setFullName(final String value) {
         mFullName = value;
     }

     public String getAddress() {
         return mAddress;
     }

     public void setAddress(final String value) {
         mAddress = value;
     }

     private String mFullName;
     private String mAddress;
 }

 // An example of a typed collection that contains your "data" objects.
 public class CustomerList extends ArrayList {
     public Customer get(final int index) {
         return (Customer) super.get(index);
     }

     public void set(final int index, final Customer value) {
         super.set(index, value);
     }
 }

 // A custom mail merge data source that you implement to allow Aspose.Words
 // to mail merge data from your Customer objects into Microsoft Word documents.
 public class CustomerMailMergeDataSource implements IMailMergeDataSource {
     public CustomerMailMergeDataSource(final CustomerList customers) {
         mCustomers = customers;

         // When the data source is initialized, it must be positioned before the first record.
         mRecordIndex = -1;
     }

     // The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions.
     public String getTableName() {
         return "Customer";
     }

     // Aspose.Words calls this method to get a value for every data field.
     public boolean getValue(final String fieldName, final Ref<Object> fieldValue) throws Exception {
         if (fieldName.equals("FullName")) {
             fieldValue.set(mCustomers.get(mRecordIndex).getFullName());
             return true;
         } else if (fieldName.equals("Address")) {
             fieldValue.set(mCustomers.get(mRecordIndex).getAddress());
             return true;
         } else {
             // A field with this name was not found,
             // return false to the Aspose.Words mail merge engine
             fieldValue.set(null);
             return false;
         }
     }

     // A standard implementation for moving to a next record in a collection.
     public boolean moveNext() {
         if (!isEof()) mRecordIndex++;

         return (!isEof());
     }

     public IMailMergeDataSource getChildDataSource(final String tableName) {
         return null;
     }

     private boolean isEof() {
         return (mRecordIndex >= mCustomers.size());
     }

     private final CustomerList mCustomers;
     private int mRecordIndex;
 }
 
 

Parameters:

dataSource - An object that implements the custom mail merge data source interface.

Throws:

java.lang.Exception

execute

public void execute(java.lang.String[] fieldNames,
                    java.lang.Object[] values)
             throws java.lang.Exception

Performs a mail merge operation. Performs a mail merge operation for a single record.

Remarks:

Use this method to fill mail merge fields in the document with values from an array of objects.

This method merges data for one record only. The array of field names and the array of values represent the data of a single record.

This method does not use mail merge regions.

This method ignores the MailMergeCleanupOptions.REMOVE_UNUSED_REGIONS option.

Examples:

Demonstrates how to merge an image from a web address using an Image field.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertField("MERGEFIELD  Image:Logo ");

 // Pass a URL which points to the image to merge into the document
 doc.getMailMerge().execute(new String[]{"Logo"}, new Object[]{DocumentHelper.getBytesFromStream(getAsposelogoUri().toURL().openStream())});

 doc.save(getArtifactsDir() + "MailMergeEvent.ImageFromUrl.doc");
 
 

Shows how to perform a mail merge, and then save the document to the client browser.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 builder.insertField(" MERGEFIELD FullName ");
 builder.insertParagraph();
 builder.insertField(" MERGEFIELD Company ");
 builder.insertParagraph();
 builder.insertField(" MERGEFIELD Address ");
 builder.insertParagraph();
 builder.insertField(" MERGEFIELD City ");

 doc.getMailMerge().execute(new String[]{"FullName", "Company", "Address", "City"},
         new Object[]{"James Bond", "MI5 Headquarters", "Milbank", "London"});
 
 

Parameters:

fieldNames - Array of merge field names. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.

values - Array of values to be inserted into the merge fields. Number of elements in this array must be the same as the number of elements in fieldNames.

Throws:

java.lang.Exception

execute

public void execute(DataTable table)
             throws java.lang.Exception

Performs mail merge from a com.aspose.words.net.System.Data.DataTable into the document.

Remarks:

Use this method to fill mail merge fields in the document with values from a DataTable.

All records from the table are merged into the document.

You can use NEXT field in the Word document to cause MailMerge object to select next record from the DataTable and continue merging. This can be used when creating documents such as mailing labels.

When MailMerge object reaches end of the main document and there are still more rows in the DataTable, it copies entire content of the main document and appends it to the end of the destination document using a section break as a separator.

This method ignores the MailMergeCleanupOptions.REMOVE_UNUSED_REGIONS option.

Examples:

Shows how to execute a mail merge with data from a DataTable.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertField(" MERGEFIELD CustomerName ");
 builder.insertParagraph();
 builder.insertField(" MERGEFIELD Address ");

 // This example creates a table, but you would normally load table from a database
 DataTable table = new DataTable("Test");
 table.getColumns().add("CustomerName");
 table.getColumns().add("Address");
 table.getRows().add("Thomas Hardy", "120 Hanover Sq., London");
 table.getRows().add("Paolo Accorti", "Via Monte Bianco 34, Torino");

 // Field values from the table are inserted into the mail merge fields found in the document
 doc.getMailMerge().execute(table);

 doc.save(getArtifactsDir() + "MailMerge.ExecuteDataTable.docx");

 // Create a copy of our document to perform another mail merge
 doc = new Document();
 builder = new DocumentBuilder(doc);
 builder.insertField(" MERGEFIELD CustomerName ");
 builder.insertParagraph();
 builder.insertField(" MERGEFIELD Address ");

 // We can also source values for a mail merge from a single row in the table
 doc.getMailMerge().execute(table.getRows().get(1));

 doc.save(getArtifactsDir() + "MailMerge.ExecuteDataTable.OneRow.docx");
 
 

Parameters:

table - Table that contains data to be inserted into mail merge fields. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.

Throws:

java.lang.Exception

execute

public void execute(IDataReader dataReader)
             throws java.lang.Exception

Performs mail merge from IDataReader into the document.

Remarks:

You can pass SqlDataReader or OleDbDataReader object into this method as a parameter because they both implemented IDataReader interface.

Note this method does not use mail merge regions and for multiple records the document will grow by repeating the whole document.

This method ignores the MailMergeCleanupOptions.REMOVE_UNUSED_REGIONS option.

Examples:

Shows how to run a mail merge using data from a data reader.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 builder.write("Product:\t");
 builder.insertField(" MERGEFIELD ProductName");
 builder.write("\nSupplier:\t");
 builder.insertField(" MERGEFIELD CompanyName");
 builder.writeln();
 builder.insertField(" MERGEFIELD QuantityPerUnit");
 builder.write(" for $");
 builder.insertField(" MERGEFIELD UnitPrice");

 // "DocumentHelper.executeDataTable" is utility function that creates a connection, command,
 // executes the command and return the result in a DataTable.
 ResultSet resultSet = DocumentHelper.executeDataTable(
         "SELECT Products.ProductName, Suppliers.CompanyName, Products.QuantityPerUnit, " +
                 "{fn ROUND(Products.UnitPrice,2)} as UnitPrice " +
                 "FROM Products INNER JOIN Suppliers ON Products.SupplierID = Suppliers.SupplierID");
 DataTable dataTable = new DataTable(resultSet, "OrderDetails");
 IDataReader dataReader = new DataTableReader(dataTable);

 // Now we can take the data from the reader and use it in the mail merge.
 doc.getMailMerge().execute(dataReader);

 doc.save(getArtifactsDir() + "MailMerge.ExecuteDataReader.docx");
 
 

Parameters:

dataReader - Data source for the mail merge operation.

Throws:

java.lang.Exception

execute

public void execute(DataView dataView)
             throws java.lang.Exception

Performs mail merge from a DataView into the document.

Remarks:

This method is useful if you retrieve data into a DataTable but then need to apply a filter or sort before the mail merge.

Note this method does not use mail merge regions and for multiple records the document will grow by repeating the whole document.

This method ignores the MailMergeCleanupOptions.REMOVE_UNUSED_REGIONS option.

Parameters:

dataView - Data source for the mail merge operation.

Throws:

java.lang.Exception

execute

public void execute(DataRow row)
             throws java.lang.Exception

Performs mail merge from a DataRow into the document.

Remarks:

Use this method to fill mail merge fields in the document with values from a DataRow.

This method ignores the MailMergeCleanupOptions.REMOVE_UNUSED_REGIONS option.

Examples:

Shows how to execute a mail merge with data from a DataTable.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);
 builder.insertField(" MERGEFIELD CustomerName ");
 builder.insertParagraph();
 builder.insertField(" MERGEFIELD Address ");

 // This example creates a table, but you would normally load table from a database
 DataTable table = new DataTable("Test");
 table.getColumns().add("CustomerName");
 table.getColumns().add("Address");
 table.getRows().add("Thomas Hardy", "120 Hanover Sq., London");
 table.getRows().add("Paolo Accorti", "Via Monte Bianco 34, Torino");

 // Field values from the table are inserted into the mail merge fields found in the document
 doc.getMailMerge().execute(table);

 doc.save(getArtifactsDir() + "MailMerge.ExecuteDataTable.docx");

 // Create a copy of our document to perform another mail merge
 doc = new Document();
 builder = new DocumentBuilder(doc);
 builder.insertField(" MERGEFIELD CustomerName ");
 builder.insertParagraph();
 builder.insertField(" MERGEFIELD Address ");

 // We can also source values for a mail merge from a single row in the table
 doc.getMailMerge().execute(table.getRows().get(1));

 doc.save(getArtifactsDir() + "MailMerge.ExecuteDataTable.OneRow.docx");
 
 

Parameters:

row - Row that contains data to be inserted into mail merge fields. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.

Throws:

java.lang.Exception

executeWithRegions

public void executeWithRegions(IMailMergeDataSource dataSource)
                        throws java.lang.Exception

Performs a mail merge from a custom data source with mail merge regions.

Remarks:

Use this method to fill mail merge fields in the document with values from any custom data source such as an XML file or collections of business objects. You need to write your own class that implements the IMailMergeDataSource interface.

You can use this method only when FieldOptions.isBidiTextSupportedOnUpdate() / FieldOptions.isBidiTextSupportedOnUpdate(boolean) is false, that is you do not need Right-To-Left language (such as Arabic or Hebrew) compatibility.

Parameters:

dataSource - An object that implements the custom mail merge data source interface.

Throws:

java.lang.Exception

executeWithRegions

public void executeWithRegions(IMailMergeDataSourceRoot dataSourceRoot)
                        throws java.lang.Exception

Performs a mail merge from a custom data source with mail merge regions.

Remarks:

Use this method to fill mail merge fields in the document with values from any custom data source such as an XML file or collections of business objects. You need to write your own classes that implement the IMailMergeDataSourceRoot and IMailMergeDataSource interfaces.

You can use this method only when FieldOptions.isBidiTextSupportedOnUpdate() / FieldOptions.isBidiTextSupportedOnUpdate(boolean) is false, that is you do not need Right-To-Left language (such as Arabic or Hebrew) compatibility.

Examples:

Performs mail merge from a custom data source with master-detail data.

 
 public void customDataSourceRoot() throws Exception {
     // Create a document with two mail merge regions named "Washington" and "Seattle"
     Document doc = createSourceDocumentWithMailMergeRegions(new String[]{"Washington", "Seattle"});

     // Create two data sources
     EmployeeList employeesWashingtonBranch = new EmployeeList();
     employeesWashingtonBranch.add(new Employee("John Doe", "Sales"));
     employeesWashingtonBranch.add(new Employee("Jane Doe", "Management"));

     EmployeeList employeesSeattleBranch = new EmployeeList();
     employeesWashingtonBranch.add(new Employee("John Cardholder", "Management"));
     employeesWashingtonBranch.add(new Employee("Joe Bloggs", "Sales"));

     // Register our data sources by name in a data source root
     DataSourceRoot sourceRoot = new DataSourceRoot();
     sourceRoot.registerSource("Washington", new EmployeeListMailMergeSource(employeesWashingtonBranch));
     sourceRoot.registerSource("Seattle", new EmployeeListMailMergeSource(employeesSeattleBranch));

     // Since we have consecutive mail merge regions, we would normally have to perform two mail merges
     // However, one mail merge source data root call every relevant data source and merge automatically
     doc.getMailMerge().executeWithRegions(sourceRoot);

     doc.save(getArtifactsDir() + "MailMergeCustom.CustomDataSourceRoot.docx");
 }

 /// <summary>
 /// Create document that contains consecutive mail merge regions, with names designated by the input array,
 /// for a data table of employees.
 /// </summary>
 private static Document createSourceDocumentWithMailMergeRegions(String[] regions) throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     for (String s : regions) {
         builder.writeln("\n" + s + " branch: ");
         builder.insertField(" MERGEFIELD TableStart:" + s);
         builder.insertField(" MERGEFIELD FullName");
         builder.write(", ");
         builder.insertField(" MERGEFIELD Department");
         builder.insertField(" MERGEFIELD TableEnd:" + s);
     }

     return doc;
 }

 /// <summary>
 /// An example of a "data entity" class in your application.
 /// </summary>
 private static class Employee {
     public Employee(String aFullName, String aDepartment) {
         mFullName = aFullName;
         mDepartment = aDepartment;
     }

     public String getFullName() {
         return mFullName;
     }

     private final String mFullName;

     public String getDepartment() {
         return mDepartment;
     }

     private final String mDepartment;
 }

 /// <summary>
 /// An example of a typed collection that contains your "data" objects.
 /// </summary>
 private static class EmployeeList extends ArrayList {
     public Employee get(int index) {
         return (Employee) super.get(index);
     }

     public void set(int index, Employee value) {
         super.set(index, value);
     }
 }

 /// <summary>
 /// Data source root that can be passed directly into a mail merge which can register and contain many child data sources.
 /// These sources must all implement IMailMergeDataSource, and are registered and differentiated by a name
 /// which corresponds to a mail merge region that will read the respective data.
 /// </summary>
 private static class DataSourceRoot implements IMailMergeDataSourceRoot {
     public IMailMergeDataSource getDataSource(String tableName) {
         EmployeeListMailMergeSource source = mSources.get(tableName);
         source.reset();
         return mSources.get(tableName);
     }

     public void registerSource(String sourceName, EmployeeListMailMergeSource source) {
         mSources.put(sourceName, source);
     }

     private final HashMap<String, EmployeeListMailMergeSource> mSources = new HashMap<>();
 }

 /// <summary>
 /// Custom mail merge data source.
 /// </summary>
 private static class EmployeeListMailMergeSource implements IMailMergeDataSource {
     public EmployeeListMailMergeSource(EmployeeList employees) {
         mEmployees = employees;
         mRecordIndex = -1;
     }

     /// <summary>
     /// A standard implementation for moving to a next record in a collection.
     /// </summary>
     public boolean moveNext() {
         if (!isEof())
             mRecordIndex++;

         return (!isEof());
     }

     private boolean isEof() {
         return (mRecordIndex >= mEmployees.size());
     }

     public void reset() {
         mRecordIndex = -1;
     }

     /// <summary>
     /// The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions.
     /// </summary>
     public String getTableName() {
         return "Employees";
     }

     /// <summary>
     /// Aspose.Words calls this method to get a value for every data field.
     /// </summary>
     public boolean getValue(String fieldName, Ref<Object> fieldValue) {
         switch (fieldName) {
             case "FullName":
                 fieldValue.set(mEmployees.get(mRecordIndex).getFullName());
                 return true;
             case "Department":
                 fieldValue.set(mEmployees.get(mRecordIndex).getDepartment());
                 return true;
             default:
                 // A field with this name was not found,
                 // return false to the Aspose.Words mail merge engine
                 fieldValue.set(null);
                 return false;
         }
     }

     /// <summary>
     /// Child data sources are for nested mail merges.
     /// </summary>
     public IMailMergeDataSource getChildDataSource(String tableName) {
         throw new UnsupportedOperationException();
     }

     private final EmployeeList mEmployees;
     private int mRecordIndex;
 }
 
 

Parameters:

dataSourceRoot - An object that implements the custom mail merge data source root interface.

Throws:

java.lang.Exception

executeWithRegions

public void executeWithRegions(DataSet dataSet)
                        throws java.lang.Exception

Performs a mail merge operation into a document with mail merge regions. Supports parent-child (master-detail) data sources and nested mail merge regions. Performs mail merge from a DataSet into a document with mail merge regions.

Remarks:

Use this method to perform mail merge from one or more tables into repeatable mail merge regions in the document. The mail merge regions inside the document will dynamically grow to accommodate records in the corresponding tables.

The document must have mail merge regions defined with names that refer to the tables in the DataSet.

To specify a mail merge region in the document you need to insert two mail merge fields to mark beginning and end of the mail merge region.

All document content that is included inside a mail merge region will be automatically repeated for every record in the DataTable.

To mark beginning of a mail merge region insert a MERGEFIELD with name TableStart:MyTable, where MyTable corresponds to one of the table names in your DataSet.

To mark the end of the mail merge region insert another MERGEFIELD with name TableEnd:MyTable.

To insert a MERGEFIELD in Word use Insert/Field command and select MergeField then type the name of the field.

The TableStart and TableEnd fields must be inside the same section in your document.

If used inside a table, TableStart and TableEnd must be inside the same row in the table.

Mail merge regions in a document should be well formed (there always needs to be a pair of matching TableStart and TableEnd merge fields with the same table name).

Examples:

Shows how to execute a nested mail merge with two merge regions and two data tables.

 
 public void executeWithRegionsNested() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     // Normally, MERGEFIELDs contain the name of a column of a mail merge data source.
     // Instead, we can use "TableStart:" and "TableEnd:" prefixes to begin/end a mail merge region.
     // Each region will belong to a table with a name that matches the string immediately after the prefix's colon.
     builder.insertField(" MERGEFIELD TableStart:Customers");

     // This MERGEFIELD is inside the mail merge region of the "Customers" table.
     // When we execute the mail merge, this field will receive data from rows in a data source named "Customers".
     builder.write("Orders for ");
     builder.insertField(" MERGEFIELD CustomerName");
     builder.write(":");

     // Create column headers for a table that will contain values from a second inner region.
     builder.startTable();
     builder.insertCell();
     builder.write("Item");
     builder.insertCell();
     builder.write("Quantity");
     builder.endRow();

     // Create a second mail merge region inside the outer region for a table named "Orders".
     // The "Orders" table has a many-to-one relationship with the "Customers" table on the "CustomerID" column.
     builder.insertCell();
     builder.insertField(" MERGEFIELD TableStart:Orders");
     builder.insertField(" MERGEFIELD ItemName");
     builder.insertCell();
     builder.insertField(" MERGEFIELD Quantity");

     // End the inner region
     // One stipulation of using regions and tables is that the opening and closing of a mail merge region must
     // only happen over one row of a document's table
     builder.insertField(" MERGEFIELD TableEnd:Orders");
     builder.endTable();

     builder.insertField(" MERGEFIELD TableEnd:Customers");

     // Create a dataset that contains the two tables with the required names and relationships.
     // Each merge document for each row of the "Customers" table of the outer merge region will perform its mail merge on the "Orders" table.
     // Each merge document will display all rows of the latter table whose "CustomerID" column values match the current "Customers" table row.
     DataSet customersAndOrders = createDataSet();
     doc.getMailMerge().executeWithRegions(customersAndOrders);

     doc.save(getArtifactsDir() + "MailMerge.ExecuteWithRegionsNested.docx");
 }

 /// <summary>
 /// Generates a data set which has two data tables named "Customers" and "Orders",
 /// with a one-to-many relationship between the former and latter on the "CustomerID" column.
 /// </summary>
 private static DataSet createDataSet() {
     // Create the outer mail merge
     DataTable tableCustomers = new DataTable("Customers");
     tableCustomers.getColumns().add("CustomerID");
     tableCustomers.getColumns().add("CustomerName");
     tableCustomers.getRows().add(1, "John Doe");
     tableCustomers.getRows().add(2, "Jane Doe");

     // Create the table for the inner merge
     DataTable tableOrders = new DataTable("Orders");
     tableOrders.getColumns().add("CustomerID");
     tableOrders.getColumns().add("ItemName");
     tableOrders.getColumns().add("Quantity");
     tableOrders.getRows().add(1, "Hawaiian", 2);
     tableOrders.getRows().add(2, "Pepperoni", 1);
     tableOrders.getRows().add(2, "Chicago", 1);

     // Add both tables to a data set
     DataSet dataSet = new DataSet();
     dataSet.getTables().add(tableCustomers);
     dataSet.getTables().add(tableOrders);

     // The "CustomerID" column, also the primary key of the customers table is the foreign key for the Orders table
     dataSet.getRelations().add(tableCustomers.getColumns().get("CustomerID"), tableOrders.getColumns().get("CustomerID"));

     return dataSet;
 }
 
 

Parameters:

dataSet - DataSet that contains data to be inserted into mail merge fields.

Throws:

java.lang.Exception

executeWithRegions

public void executeWithRegions(DataTable dataTable)
                        throws java.lang.Exception

Performs mail merge from a DataTable into the document with mail merge regions.

Remarks:

If there are other mail merge regions defined in the document they are left intact. This allows to perform several mail merge operations.

Examples:

Shows how to use regions to execute two separate mail merges in one document.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // If we want to perform two consecutive mail merges on one document while taking data from two tables
 // related to each other in any way, we can separate the mail merges with regions.
 // Normally, MERGEFIELDs contain the name of a column of a mail merge data source.
 // Instead, we can use "TableStart:" and "TableEnd:" prefixes to begin/end a mail merge region.
 // Each region will belong to a table with a name that matches the string immediately after the prefix's colon.
 // These regions are separate for unrelated data, while they can be nested for hierarchical data.
 builder.writeln("\tCities: ");
 builder.insertField(" MERGEFIELD TableStart:Cities");
 builder.insertField(" MERGEFIELD Name");
 builder.insertField(" MERGEFIELD TableEnd:Cities");
 builder.insertParagraph();

 // Both MERGEFIELDs refer to the same column name, but values for each will come from different data tables.
 builder.writeln("\tFruit: ");
 builder.insertField(" MERGEFIELD TableStart:Fruit");
 builder.insertField(" MERGEFIELD Name");
 builder.insertField(" MERGEFIELD TableEnd:Fruit");

 // Create two unrelated data tables.
 DataTable tableCities = new DataTable("Cities");
 tableCities.getColumns().add("Name");
 tableCities.getRows().add("Washington");
 tableCities.getRows().add("London");
 tableCities.getRows().add("New York");

 DataTable tableFruit = new DataTable("Fruit");
 tableFruit.getColumns().add("Name");
 tableFruit.getRows().add("Cherry");
 tableFruit.getRows().add("Apple");
 tableFruit.getRows().add("Watermelon");
 tableFruit.getRows().add("Banana");

 // We will need to run one mail merge per table. The first mail merge will populate the MERGEFIELDs
 // in the "Cities" range while leaving the fields the "Fruit" range unfilled.
 doc.getMailMerge().executeWithRegions(tableCities);

 doc.save(getArtifactsDir() + "MailMerge.ExecuteWithRegionsConcurrent.docx");
 
 

Demonstrates how to implement custom logic in the MergeField event to apply cell formatting.

 
 public void alternatingRows() throws Exception {
     Document doc = new Document(getMyDir() + "Mail merge destination - Northwind suppliers.docx");

     // Add a handler for the MergeField event
     doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldAlternatingRows());

     // Execute mail merge with regions
     DataTable dataTable = getSuppliersDataTable();
     doc.getMailMerge().executeWithRegions(dataTable);

     doc.save(getArtifactsDir() + "MailMergeEvent.AlternatingRows.docx");
 }

 private class HandleMergeFieldAlternatingRows implements IFieldMergingCallback {
     // Called for every merge field encountered in the document.
     // We can either return some data to the mail merge engine or do something
     // else with the document. In this case we modify cell formatting.
     public void fieldMerging(final FieldMergingArgs args) throws Exception {
         if (mBuilder == null) {
             mBuilder = new DocumentBuilder(args.getDocument());
         }

         // This way we catch the beginning of a new row
         if (args.getFieldName().equals("CompanyName")) {
             // Select the color depending on whether the row number is even or odd
             Color rowColor;
             if (isOdd(mRowIdx)) rowColor = new Color(213, 227, 235);
             else rowColor = new Color(242, 242, 242);

             // There is no way to set cell properties for the whole row at the moment,
             // so we have to iterate over all cells in the row
             for (int colIdx = 0; colIdx < 4; colIdx++) {
                 mBuilder.moveToCell(0, mRowIdx, colIdx, 0);
                 mBuilder.getCellFormat().getShading().setBackgroundPatternColor(rowColor);
             }

             mRowIdx++;
         }
     }

     public void imageFieldMerging(final ImageFieldMergingArgs args) {
         // Do nothing
     }

     private DocumentBuilder mBuilder;
     private int mRowIdx;
 }

 /*
 // Returns true if the value is odd; false if the value is even.
 /

 private static boolean isOdd(final int value) {
     return (value % 2 != 0);
 }

 // Create DataTable and fill it with data.
 // In real life this DataTable should be filled from a database.
 private static DataTable getSuppliersDataTable() throws Exception {
     DataTable dataTable = new DataTable("Suppliers");
     dataTable.getColumns().add("CompanyName");
     dataTable.getColumns().add("ContactName");
     for (int i = 0; i < 10; i++) {
         DataRow datarow = dataTable.newRow();
         dataTable.getRows().add(datarow);
         datarow.set(0, "Company " + i);
         datarow.set(1, "Contact " + i);
     }

     return dataTable;
 }
 
 

Parameters:

dataTable - Data source for the mail merge operation. The table must have its DataTable.getTableName() / DataTable.setTableName(java.lang.String) property set.

Throws:

java.lang.Exception

executeWithRegions

public void executeWithRegions(DataView dataView)
                        throws java.lang.Exception

Performs mail merge from a DataView into the document with mail merge regions.

Remarks:

This method is useful if you retrieve data into a DataTable but then need to apply a filter or sort before the mail merge.

The document must have a mail merge region defined with name that matches DataView.Table.TableName.

If there are other mail merge regions defined in the document they are left intact. This allows to perform several mail merge operations.

Examples:

Shows how to use regions to execute two separate mail merges in one document.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // If we want to perform two consecutive mail merges on one document while taking data from two tables
 // related to each other in any way, we can separate the mail merges with regions.
 // Normally, MERGEFIELDs contain the name of a column of a mail merge data source.
 // Instead, we can use "TableStart:" and "TableEnd:" prefixes to begin/end a mail merge region.
 // Each region will belong to a table with a name that matches the string immediately after the prefix's colon.
 // These regions are separate for unrelated data, while they can be nested for hierarchical data.
 builder.writeln("\tCities: ");
 builder.insertField(" MERGEFIELD TableStart:Cities");
 builder.insertField(" MERGEFIELD Name");
 builder.insertField(" MERGEFIELD TableEnd:Cities");
 builder.insertParagraph();

 // Both MERGEFIELDs refer to the same column name, but values for each will come from different data tables.
 builder.writeln("\tFruit: ");
 builder.insertField(" MERGEFIELD TableStart:Fruit");
 builder.insertField(" MERGEFIELD Name");
 builder.insertField(" MERGEFIELD TableEnd:Fruit");

 // Create two unrelated data tables.
 DataTable tableCities = new DataTable("Cities");
 tableCities.getColumns().add("Name");
 tableCities.getRows().add("Washington");
 tableCities.getRows().add("London");
 tableCities.getRows().add("New York");

 DataTable tableFruit = new DataTable("Fruit");
 tableFruit.getColumns().add("Name");
 tableFruit.getRows().add("Cherry");
 tableFruit.getRows().add("Apple");
 tableFruit.getRows().add("Watermelon");
 tableFruit.getRows().add("Banana");

 // We will need to run one mail merge per table. The first mail merge will populate the MERGEFIELDs
 // in the "Cities" range while leaving the fields the "Fruit" range unfilled.
 doc.getMailMerge().executeWithRegions(tableCities);

 doc.save(getArtifactsDir() + "MailMerge.ExecuteWithRegionsConcurrent.docx");
 
 

Parameters:

dataView - Data source for the mail merge operation. The source table of the DataView must have its TableName property set.

Throws:

java.lang.Exception

executeWithRegions

public void executeWithRegions(IDataReader dataReader,
                               java.lang.String tableName)
                        throws java.lang.Exception

Performs mail merge from IDataReader into the document with mail merge regions.

Remarks:

You can pass SqlDataReader or OleDbDataReader object into this method as a parameter because they both implemented IDataReader interface.

Examples:

Shows how to insert images stored in a database BLOB field into a report.

 
 public void imageFromBlob() throws Exception {
     Document doc = new Document(getMyDir() + "Mail merge destination - Northwind employees.docx");

     // Set up the event handler for image fields
     doc.getMailMerge().setFieldMergingCallback(new HandleMergeImageFieldFromBlob());

     // Loads the driver
     Class.forName("net.ucanaccess.jdbc.UcanaccessDriver");

     // Open the database connection
     String connString = "jdbc:ucanaccess://" + getDatabaseDir() + "Northwind.accdb";

     // DSN-less DB connection
     java.sql.Connection conn = java.sql.DriverManager.getConnection(connString, "Admin", "");

     // Create and execute a command
     java.sql.Statement statement = conn.createStatement();
     java.sql.ResultSet resultSet = statement.executeQuery("SELECT * FROM Employees");

     DataTable table = new DataTable(resultSet, "Employees");

     // Perform mail merge
     doc.getMailMerge().executeWithRegions(table);

     // Close the database
     conn.close();

     doc.save(getArtifactsDir() + "MailMergeEvent.ImageFromBlob.docx");
 }

 private class HandleMergeImageFieldFromBlob implements IFieldMergingCallback {
     public void fieldMerging(final FieldMergingArgs args) {
         // Do nothing
     }

     // This is called when mail merge engine encounters Image:XXX merge field in the document.
     // You have a chance to return an Image object, file name or a stream that contains the image.
     public void imageFieldMerging(final ImageFieldMergingArgs e) {
         // The field value is a byte array, just cast it and create a stream on it
         ByteArrayInputStream imageStream = new ByteArrayInputStream((byte[]) e.getFieldValue());
         // Now the mail merge engine will retrieve the image from the stream
         e.setImageStream(imageStream);
     }
 }
 
 

Parameters:

dataReader - Source of the data records for mail merge such as OleDbDataReader or SqlDataReader.

tableName - Name of the mail merge region in the document to populate.

Throws:

java.lang.Exception

getFieldNames

public java.lang.String[] getFieldNames()
                                 throws java.lang.Exception

Returns a collection of mail merge field names available in the document.

Remarks:

Returns full merge field names including optional prefix. Does not eliminate duplicate field names.

A new string array is created on every call.

Includes "mustache" field names if getUseNonMergeFields() / setUseNonMergeFields(boolean) is true.

Examples:

Shows how to get names of all merge fields in a document.

 
 String[] fieldNames = doc.getMailMerge().getFieldNames();
 
 

Throws:

java.lang.Exception

getFieldNamesForRegion

public java.lang.String[] getFieldNamesForRegion(java.lang.String regionName)
                                          throws java.lang.Exception

Get mail merge field names from the region. Returns a collection of mail merge field names available in the region.

Remarks:

Returns full merge field names including optional prefix. Does not eliminate duplicate field names.

If document contains multiple regions with the same name the very first region is processed.

A new string array is created on every call.

Examples:

Shows how to create, list, and read mail merge regions.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // These tags, which go inside MERGEFIELDs, denote the strings that signify the starts and ends of mail merge regions
 Assert.assertEquals(doc.getMailMerge().getRegionStartTag(), "TableStart");
 Assert.assertEquals(doc.getMailMerge().getRegionEndTag(), "TableEnd");

 // By using these tags, we will start and end a "MailMergeRegion1", which will contain MERGEFIELDs for two columns
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.insertField(" MERGEFIELD Column1");
 builder.write(", ");
 builder.insertField(" MERGEFIELD Column2");
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // We can keep track of merge regions and their columns by looking at these collections
 ArrayList<MailMergeRegionInfo> regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 1);
 Assert.assertEquals(regions.get(0).getName(), "MailMergeRegion1");

 String[] mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1");
 Assert.assertEquals(mergeFieldNames[0], "Column1");
 Assert.assertEquals(mergeFieldNames[1], "Column2");

 // Insert a region with the same name inside the existing region, which will make it a parent.
 // Now a "Column2" field will be inside a new region.
 builder.moveToField(regions.get(0).getFields().get(1), false);
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.moveToField(regions.get(0).getFields().get(1), true);
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // Regions that share the same name are still accounted for and can be accessed by index
 regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 2);
 // Check that the second region now has a parent region.
 Assert.assertEquals("MailMergeRegion1", regions.get(1).getParentRegion().getName());

 mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1", 1);
 Assert.assertEquals(mergeFieldNames[0], "Column2");
 
 

Parameters:

regionName - Region name (case-insensitive).

Throws:

java.lang.Exception

getFieldNamesForRegion

public java.lang.String[] getFieldNamesForRegion(java.lang.String regionName,
                                                 int regionIndex)
                                          throws java.lang.Exception

Returns a collection of mail merge field names available in the region.

Remarks:

Returns full merge field names including optional prefix. Does not eliminate duplicate field names.

If document contains multiple regions with the same name the Nth region (zero-based) is processed.

A new string array is created on every call.

Examples:

Shows how to create, list, and read mail merge regions.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // These tags, which go inside MERGEFIELDs, denote the strings that signify the starts and ends of mail merge regions
 Assert.assertEquals(doc.getMailMerge().getRegionStartTag(), "TableStart");
 Assert.assertEquals(doc.getMailMerge().getRegionEndTag(), "TableEnd");

 // By using these tags, we will start and end a "MailMergeRegion1", which will contain MERGEFIELDs for two columns
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.insertField(" MERGEFIELD Column1");
 builder.write(", ");
 builder.insertField(" MERGEFIELD Column2");
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // We can keep track of merge regions and their columns by looking at these collections
 ArrayList<MailMergeRegionInfo> regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 1);
 Assert.assertEquals(regions.get(0).getName(), "MailMergeRegion1");

 String[] mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1");
 Assert.assertEquals(mergeFieldNames[0], "Column1");
 Assert.assertEquals(mergeFieldNames[1], "Column2");

 // Insert a region with the same name inside the existing region, which will make it a parent.
 // Now a "Column2" field will be inside a new region.
 builder.moveToField(regions.get(0).getFields().get(1), false);
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.moveToField(regions.get(0).getFields().get(1), true);
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // Regions that share the same name are still accounted for and can be accessed by index
 regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 2);
 // Check that the second region now has a parent region.
 Assert.assertEquals("MailMergeRegion1", regions.get(1).getParentRegion().getName());

 mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1", 1);
 Assert.assertEquals(mergeFieldNames[0], "Column2");
 
 

Parameters:

regionName - Region name (case-insensitive).

regionIndex - Region index (zero-based).

Throws:

java.lang.Exception

getRegionsByName

public java.util.ArrayList getRegionsByName(java.lang.String regionName)
                                     throws java.lang.Exception

Returns a collection of mail merge regions with the specified name.

Examples:

Shows how to create, list, and read mail merge regions.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // These tags, which go inside MERGEFIELDs, denote the strings that signify the starts and ends of mail merge regions
 Assert.assertEquals(doc.getMailMerge().getRegionStartTag(), "TableStart");
 Assert.assertEquals(doc.getMailMerge().getRegionEndTag(), "TableEnd");

 // By using these tags, we will start and end a "MailMergeRegion1", which will contain MERGEFIELDs for two columns
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.insertField(" MERGEFIELD Column1");
 builder.write(", ");
 builder.insertField(" MERGEFIELD Column2");
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // We can keep track of merge regions and their columns by looking at these collections
 ArrayList<MailMergeRegionInfo> regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 1);
 Assert.assertEquals(regions.get(0).getName(), "MailMergeRegion1");

 String[] mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1");
 Assert.assertEquals(mergeFieldNames[0], "Column1");
 Assert.assertEquals(mergeFieldNames[1], "Column2");

 // Insert a region with the same name inside the existing region, which will make it a parent.
 // Now a "Column2" field will be inside a new region.
 builder.moveToField(regions.get(0).getFields().get(1), false);
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.moveToField(regions.get(0).getFields().get(1), true);
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // Regions that share the same name are still accounted for and can be accessed by index
 regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 2);
 // Check that the second region now has a parent region.
 Assert.assertEquals("MailMergeRegion1", regions.get(1).getParentRegion().getName());

 mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1", 1);
 Assert.assertEquals(mergeFieldNames[0], "Column2");
 
 

Parameters:

regionName - Region name (case-insensitive).

Returns:

The list of regions.

Throws:

java.lang.Exception

getRegionsHierarchy

public MailMergeRegionInfo getRegionsHierarchy()
                                        throws java.lang.Exception

Returns a full hierarchy of regions (with fields) available in the document.

Remarks:

Hierarchy is returned in the form of the MailMergeRegionInfo class.

Examples:

Shows how to get MailMergeRegionInfo and work with it.

 
 Document doc = new Document(getMyDir() + "Mail merge regions.docx");

 // Returns a full hierarchy of regions (with fields) available in the document
 MailMergeRegionInfo regionInfo = doc.getMailMerge().getRegionsHierarchy();

 // Get top regions in the document
 ArrayList topRegions = regionInfo.getRegions();
 Assert.assertEquals(topRegions.size(), 2);
 Assert.assertEquals(((MailMergeRegionInfo) topRegions.get(0)).getName(), "Region1");
 Assert.assertEquals(((MailMergeRegionInfo) topRegions.get(1)).getName(), "Region2");
 Assert.assertEquals(((MailMergeRegionInfo) topRegions.get(0)).getLevel(), 1);
 Assert.assertEquals(((MailMergeRegionInfo) topRegions.get(1)).getLevel(), 1);

 // Get nested region in first top region
 ArrayList nestedRegions = ((MailMergeRegionInfo) topRegions.get(0)).getRegions();
 Assert.assertEquals(nestedRegions.size(), 2);
 Assert.assertEquals(((MailMergeRegionInfo) nestedRegions.get(0)).getName(), "NestedRegion1");
 Assert.assertEquals(((MailMergeRegionInfo) nestedRegions.get(1)).getName(), "NestedRegion2");
 Assert.assertEquals(((MailMergeRegionInfo) nestedRegions.get(0)).getLevel(), 2);
 Assert.assertEquals(((MailMergeRegionInfo) nestedRegions.get(1)).getLevel(), 2);

 // Get field list in first top region
 ArrayList fieldList = ((MailMergeRegionInfo) topRegions.get(0)).getFields();
 Assert.assertEquals(fieldList.size(), 4);

 FieldMergeField startFieldMergeField = ((MailMergeRegionInfo) nestedRegions.get(0)).getStartField();
 Assert.assertEquals(startFieldMergeField.getFieldName(), "TableStart:NestedRegion1");

 FieldMergeField endFieldMergeField = ((MailMergeRegionInfo) nestedRegions.get(0)).getEndField();
 Assert.assertEquals(endFieldMergeField.getFieldName(), "TableEnd:NestedRegion1");
 
 

Returns:

Regions' hierarchy.

Throws:

java.lang.Exception

deleteFields

public void deleteFields()
                  throws java.lang.Exception

Removes mail merge related fields from the document.

Remarks:

This method removes MERGEFIELD and NEXT fields from the document.

This method could be useful if your mail merge operation does not always need to populate all fields in the document. Use this method to remove all remaining mail merge fields.

Examples:

Shows how to delete all merge fields from a document without executing mail merge.

 
 doc.getMailMerge().deleteFields();
 
 

Throws:

java.lang.Exception

getRegionStartTag

public java.lang.String getRegionStartTag()

Gets a mail merge region start tag.

Examples:

Shows how to create, list, and read mail merge regions.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // These tags, which go inside MERGEFIELDs, denote the strings that signify the starts and ends of mail merge regions
 Assert.assertEquals(doc.getMailMerge().getRegionStartTag(), "TableStart");
 Assert.assertEquals(doc.getMailMerge().getRegionEndTag(), "TableEnd");

 // By using these tags, we will start and end a "MailMergeRegion1", which will contain MERGEFIELDs for two columns
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.insertField(" MERGEFIELD Column1");
 builder.write(", ");
 builder.insertField(" MERGEFIELD Column2");
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // We can keep track of merge regions and their columns by looking at these collections
 ArrayList<MailMergeRegionInfo> regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 1);
 Assert.assertEquals(regions.get(0).getName(), "MailMergeRegion1");

 String[] mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1");
 Assert.assertEquals(mergeFieldNames[0], "Column1");
 Assert.assertEquals(mergeFieldNames[1], "Column2");

 // Insert a region with the same name inside the existing region, which will make it a parent.
 // Now a "Column2" field will be inside a new region.
 builder.moveToField(regions.get(0).getFields().get(1), false);
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.moveToField(regions.get(0).getFields().get(1), true);
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // Regions that share the same name are still accounted for and can be accessed by index
 regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 2);
 // Check that the second region now has a parent region.
 Assert.assertEquals("MailMergeRegion1", regions.get(1).getParentRegion().getName());

 mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1", 1);
 Assert.assertEquals(mergeFieldNames[0], "Column2");
 
 

Returns:

A mail merge region start tag.

setRegionStartTag

public void setRegionStartTag(java.lang.String value)

Sets a mail merge region start tag.

Examples:

Shows how to create, list, and read mail merge regions.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // These tags, which go inside MERGEFIELDs, denote the strings that signify the starts and ends of mail merge regions
 Assert.assertEquals(doc.getMailMerge().getRegionStartTag(), "TableStart");
 Assert.assertEquals(doc.getMailMerge().getRegionEndTag(), "TableEnd");

 // By using these tags, we will start and end a "MailMergeRegion1", which will contain MERGEFIELDs for two columns
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.insertField(" MERGEFIELD Column1");
 builder.write(", ");
 builder.insertField(" MERGEFIELD Column2");
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // We can keep track of merge regions and their columns by looking at these collections
 ArrayList<MailMergeRegionInfo> regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 1);
 Assert.assertEquals(regions.get(0).getName(), "MailMergeRegion1");

 String[] mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1");
 Assert.assertEquals(mergeFieldNames[0], "Column1");
 Assert.assertEquals(mergeFieldNames[1], "Column2");

 // Insert a region with the same name inside the existing region, which will make it a parent.
 // Now a "Column2" field will be inside a new region.
 builder.moveToField(regions.get(0).getFields().get(1), false);
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.moveToField(regions.get(0).getFields().get(1), true);
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // Regions that share the same name are still accounted for and can be accessed by index
 regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 2);
 // Check that the second region now has a parent region.
 Assert.assertEquals("MailMergeRegion1", regions.get(1).getParentRegion().getName());

 mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1", 1);
 Assert.assertEquals(mergeFieldNames[0], "Column2");
 
 

Parameters:

value - A mail merge region start tag.

getRegionEndTag

public java.lang.String getRegionEndTag()

Gets a mail merge region end tag.

Examples:

Shows how to create, list, and read mail merge regions.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // These tags, which go inside MERGEFIELDs, denote the strings that signify the starts and ends of mail merge regions
 Assert.assertEquals(doc.getMailMerge().getRegionStartTag(), "TableStart");
 Assert.assertEquals(doc.getMailMerge().getRegionEndTag(), "TableEnd");

 // By using these tags, we will start and end a "MailMergeRegion1", which will contain MERGEFIELDs for two columns
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.insertField(" MERGEFIELD Column1");
 builder.write(", ");
 builder.insertField(" MERGEFIELD Column2");
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // We can keep track of merge regions and their columns by looking at these collections
 ArrayList<MailMergeRegionInfo> regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 1);
 Assert.assertEquals(regions.get(0).getName(), "MailMergeRegion1");

 String[] mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1");
 Assert.assertEquals(mergeFieldNames[0], "Column1");
 Assert.assertEquals(mergeFieldNames[1], "Column2");

 // Insert a region with the same name inside the existing region, which will make it a parent.
 // Now a "Column2" field will be inside a new region.
 builder.moveToField(regions.get(0).getFields().get(1), false);
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.moveToField(regions.get(0).getFields().get(1), true);
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // Regions that share the same name are still accounted for and can be accessed by index
 regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 2);
 // Check that the second region now has a parent region.
 Assert.assertEquals("MailMergeRegion1", regions.get(1).getParentRegion().getName());

 mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1", 1);
 Assert.assertEquals(mergeFieldNames[0], "Column2");
 
 

Returns:

A mail merge region end tag.

setRegionEndTag

public void setRegionEndTag(java.lang.String value)

Sets a mail merge region end tag.

Examples:

Shows how to create, list, and read mail merge regions.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // These tags, which go inside MERGEFIELDs, denote the strings that signify the starts and ends of mail merge regions
 Assert.assertEquals(doc.getMailMerge().getRegionStartTag(), "TableStart");
 Assert.assertEquals(doc.getMailMerge().getRegionEndTag(), "TableEnd");

 // By using these tags, we will start and end a "MailMergeRegion1", which will contain MERGEFIELDs for two columns
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.insertField(" MERGEFIELD Column1");
 builder.write(", ");
 builder.insertField(" MERGEFIELD Column2");
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // We can keep track of merge regions and their columns by looking at these collections
 ArrayList<MailMergeRegionInfo> regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 1);
 Assert.assertEquals(regions.get(0).getName(), "MailMergeRegion1");

 String[] mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1");
 Assert.assertEquals(mergeFieldNames[0], "Column1");
 Assert.assertEquals(mergeFieldNames[1], "Column2");

 // Insert a region with the same name inside the existing region, which will make it a parent.
 // Now a "Column2" field will be inside a new region.
 builder.moveToField(regions.get(0).getFields().get(1), false);
 builder.insertField(" MERGEFIELD TableStart:MailMergeRegion1");
 builder.moveToField(regions.get(0).getFields().get(1), true);
 builder.insertField(" MERGEFIELD TableEnd:MailMergeRegion1");

 // Regions that share the same name are still accounted for and can be accessed by index
 regions = doc.getMailMerge().getRegionsByName("MailMergeRegion1");
 Assert.assertEquals(regions.size(), 2);
 // Check that the second region now has a parent region.
 Assert.assertEquals("MailMergeRegion1", regions.get(1).getParentRegion().getName());

 mergeFieldNames = doc.getMailMerge().getFieldNamesForRegion("MailMergeRegion1", 1);
 Assert.assertEquals(mergeFieldNames[0], "Column2");
 
 

Parameters:

value - A mail merge region end tag.

getCleanupOptions

public int getCleanupOptions()

Gets a set of flags that specify what items should be removed during mail merge.

Examples:

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

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

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

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

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

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

Returns:

A set of flags that specify what items should be removed during mail merge. The returned value is a bitwise combination of MailMergeCleanupOptions constants.

setCleanupOptions

public void setCleanupOptions(int value)

Sets a set of flags that specify what items should be removed during mail merge.

Examples:

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

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

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

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

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

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

Parameters:

value - A set of flags that specify what items should be removed during mail merge. The value must be a bitwise combination of MailMergeCleanupOptions constants.

getCleanupParagraphsWithPunctuationMarks

public boolean getCleanupParagraphsWithPunctuationMarks()

Gets a value indicating whether paragraphs with punctuation marks are considered as empty and should be removed if the MailMergeCleanupOptions.REMOVE_EMPTY_PARAGRAPHS option is specified.

Remarks:

The default value is true.

Here is the complete list of cleanable punctuation marks:

• !
• ,
• .
• :
• ;
• ?
• ¡
• ¿

Examples:

Shows how to remove paragraphs with punctuation marks after mail merge operation.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 FieldMergeField mergeFieldOption1 = (FieldMergeField) builder.insertField("MERGEFIELD", "Option_1");
 mergeFieldOption1.setFieldName("Option_1");

 // Here is the complete list of cleanable punctuation marks:
 // !
 // ,
 // .
 // :
 // ;
 // ?
 // ¡
 // ¿
 builder.write(punctuationMark);

 FieldMergeField mergeFieldOption2 = (FieldMergeField) builder.insertField("MERGEFIELD", "Option_2");
 mergeFieldOption2.setFieldName("Option_2");

 doc.getMailMerge().setCleanupOptions(MailMergeCleanupOptions.REMOVE_EMPTY_PARAGRAPHS);
 // The default value of the option is true which means that the behavior was changed to mimic MS Word
 // If you rely on the old behavior are able to revert it by setting the option to false
 doc.getMailMerge().setCleanupParagraphsWithPunctuationMarks(isCleanupParagraphsWithPunctuationMarks);

 doc.getMailMerge().execute(new String[]{"Option_1", "Option_2"}, new Object[]{null, null});

 doc.save(getArtifactsDir() + "MailMerge.RemoveColonBetweenEmptyMergeFields.docx");
 
 

Returns:

A value indicating whether paragraphs with punctuation marks are considered as empty and should be removed if the MailMergeCleanupOptions.REMOVE_EMPTY_PARAGRAPHS option is specified.

setCleanupParagraphsWithPunctuationMarks

public void setCleanupParagraphsWithPunctuationMarks(boolean value)

Sets a value indicating whether paragraphs with punctuation marks are considered as empty and should be removed if the MailMergeCleanupOptions.REMOVE_EMPTY_PARAGRAPHS option is specified.

Remarks:

The default value is true.

Here is the complete list of cleanable punctuation marks:

• !
• ,
• .
• :
• ;
• ?
• ¡
• ¿

Examples:

Shows how to remove paragraphs with punctuation marks after mail merge operation.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 FieldMergeField mergeFieldOption1 = (FieldMergeField) builder.insertField("MERGEFIELD", "Option_1");
 mergeFieldOption1.setFieldName("Option_1");

 // Here is the complete list of cleanable punctuation marks:
 // !
 // ,
 // .
 // :
 // ;
 // ?
 // ¡
 // ¿
 builder.write(punctuationMark);

 FieldMergeField mergeFieldOption2 = (FieldMergeField) builder.insertField("MERGEFIELD", "Option_2");
 mergeFieldOption2.setFieldName("Option_2");

 doc.getMailMerge().setCleanupOptions(MailMergeCleanupOptions.REMOVE_EMPTY_PARAGRAPHS);
 // The default value of the option is true which means that the behavior was changed to mimic MS Word
 // If you rely on the old behavior are able to revert it by setting the option to false
 doc.getMailMerge().setCleanupParagraphsWithPunctuationMarks(isCleanupParagraphsWithPunctuationMarks);

 doc.getMailMerge().execute(new String[]{"Option_1", "Option_2"}, new Object[]{null, null});

 doc.save(getArtifactsDir() + "MailMerge.RemoveColonBetweenEmptyMergeFields.docx");
 
 

Parameters:

value - A value indicating whether paragraphs with punctuation marks are considered as empty and should be removed if the MailMergeCleanupOptions.REMOVE_EMPTY_PARAGRAPHS option is specified.

getUseNonMergeFields

public boolean getUseNonMergeFields()

When true, specifies that in addition to MERGEFIELD fields, mail merge is performed into some other types of fields and also into "{{fieldName}}" tags.

Remarks:

Normally, mail merge is only performed into MERGEFIELD fields, but several customers had their reporting built using other fields and had many documents created this way. To simplify migration (and because this approach was independently used by several customers) the ability to mail merge into other fields was introduced.

When getUseNonMergeFields() / setUseNonMergeFields(boolean) is set to true, Aspose.Words will perform mail merge into the following fields:

MERGEFIELD FieldName

MACROBUTTON NOMACRO FieldName

IF 0 = 0 "{FieldName}" ""

Also, when getUseNonMergeFields() / setUseNonMergeFields(boolean) is set to true, Aspose.Words will perform mail merge into text tags "{{fieldName}}". These are not fields, but just text tags.

Examples:

Shows how to perform mail merge into merge fields and into additional fields types.

 
 doc.getMailMerge().setUseNonMergeFields(true);
 
 

Returns:

The corresponding boolean value.

setUseNonMergeFields

public void setUseNonMergeFields(boolean value)

When true, specifies that in addition to MERGEFIELD fields, mail merge is performed into some other types of fields and also into "{{fieldName}}" tags.

Remarks:

Normally, mail merge is only performed into MERGEFIELD fields, but several customers had their reporting built using other fields and had many documents created this way. To simplify migration (and because this approach was independently used by several customers) the ability to mail merge into other fields was introduced.

When getUseNonMergeFields() / setUseNonMergeFields(boolean) is set to true, Aspose.Words will perform mail merge into the following fields:

MERGEFIELD FieldName

MACROBUTTON NOMACRO FieldName

IF 0 = 0 "{FieldName}" ""

Also, when getUseNonMergeFields() / setUseNonMergeFields(boolean) is set to true, Aspose.Words will perform mail merge into text tags "{{fieldName}}". These are not fields, but just text tags.

Examples:

Shows how to perform mail merge into merge fields and into additional fields types.

 
 doc.getMailMerge().setUseNonMergeFields(true);
 
 

Parameters:

value - The corresponding boolean value.

getPreserveUnusedTags

public boolean getPreserveUnusedTags()

Gets a value indicating whether the unused "mustache" tags should be preserved.

Remarks:

The default value is false.

Examples:

Shows how to preserve the appearance of alternative mail merge tags that go unused during a mail merge.

 
 public void preserveUnusedTags(boolean doPreserveUnusedTags) throws Exception {
     // Create a document and table that we will merge
     Document doc = createSourceDocWithAlternativeMergeFields();
     DataTable dataTable = createSourceTablePreserveUnusedTags();

     // By default, alternative merge tags that can't receive data because the data source has no columns with their name
     // are converted to and left on display as MERGEFIELDs after the mail merge
     // We can preserve their original appearance setting this attribute to true
     doc.getMailMerge().setPreserveUnusedTags(doPreserveUnusedTags);
     doc.getMailMerge().execute(dataTable);

     doc.save(getArtifactsDir() + "MailMerge.PreserveUnusedTags.docx");

     Assert.assertEquals(doc.getText().contains("{{ Column2 }}"), doPreserveUnusedTags);
 }

 public static Object[][] preserveUnusedTagsDataProvider() throws Exception {
     return new Object[][]
             {
                     {false},
                     {true},
             };
 }

 /// <summary>
 /// Create a document and add two tags that can accept mail merge data that are not the traditional MERGEFIELDs.
 /// </summary>
 private static Document createSourceDocWithAlternativeMergeFields() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.writeln("{{ Column1 }}");
     builder.writeln("{{ Column2 }}");

     // Our tags will only register as destinations for mail merge data if we set this to true
     doc.getMailMerge().setUseNonMergeFields(true);

     return doc;
 }

 /// <summary>
 /// Create a simple data table with one column.
 /// </summary>
 private static DataTable createSourceTablePreserveUnusedTags() {
     DataTable dataTable = new DataTable("MyTable");
     dataTable.getColumns().add("Column1");
     dataTable.getRows().add("Value1");

     return dataTable;
 }
 
 

Returns:

A value indicating whether the unused "mustache" tags should be preserved.

See Also:

getUseNonMergeFields(), setUseNonMergeFields(boolean)

setPreserveUnusedTags

public void setPreserveUnusedTags(boolean value)

Sets a value indicating whether the unused "mustache" tags should be preserved.

Remarks:

The default value is false.

Examples:

Shows how to preserve the appearance of alternative mail merge tags that go unused during a mail merge.

 
 public void preserveUnusedTags(boolean doPreserveUnusedTags) throws Exception {
     // Create a document and table that we will merge
     Document doc = createSourceDocWithAlternativeMergeFields();
     DataTable dataTable = createSourceTablePreserveUnusedTags();

     // By default, alternative merge tags that can't receive data because the data source has no columns with their name
     // are converted to and left on display as MERGEFIELDs after the mail merge
     // We can preserve their original appearance setting this attribute to true
     doc.getMailMerge().setPreserveUnusedTags(doPreserveUnusedTags);
     doc.getMailMerge().execute(dataTable);

     doc.save(getArtifactsDir() + "MailMerge.PreserveUnusedTags.docx");

     Assert.assertEquals(doc.getText().contains("{{ Column2 }}"), doPreserveUnusedTags);
 }

 public static Object[][] preserveUnusedTagsDataProvider() throws Exception {
     return new Object[][]
             {
                     {false},
                     {true},
             };
 }

 /// <summary>
 /// Create a document and add two tags that can accept mail merge data that are not the traditional MERGEFIELDs.
 /// </summary>
 private static Document createSourceDocWithAlternativeMergeFields() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.writeln("{{ Column1 }}");
     builder.writeln("{{ Column2 }}");

     // Our tags will only register as destinations for mail merge data if we set this to true
     doc.getMailMerge().setUseNonMergeFields(true);

     return doc;
 }

 /// <summary>
 /// Create a simple data table with one column.
 /// </summary>
 private static DataTable createSourceTablePreserveUnusedTags() {
     DataTable dataTable = new DataTable("MyTable");
     dataTable.getColumns().add("Column1");
     dataTable.getRows().add("Value1");

     return dataTable;
 }
 
 

Parameters:

value - A value indicating whether the unused "mustache" tags should be preserved.

See Also:

getUseNonMergeFields(), setUseNonMergeFields(boolean)

getMergeDuplicateRegions

public boolean getMergeDuplicateRegions()

Gets a value indicating whether all of the document mail merge regions with the name of a data source should be merged while executing of a mail merge with regions against the data source or just the first one.

Remarks:

The default value is false.

Examples:

Shows how to work with duplicate mail merge regions.

 
 public void mergeDuplicateRegions(boolean isMergeDuplicateRegions) throws Exception {
     // Create a document and table that we will merge
     Document doc = createSourceDocMergeDuplicateRegions();
     DataTable dataTable = createSourceTableMergeDuplicateRegions();

     // If this property is false, the first region will be merged
     // while the MERGEFIELDs of the second one will be left in the pre-merge state
     // To get both regions merged we would have to execute the mail merge twice, on a table of the same name
     // If this is set to true, both regions will be affected by the merge
     doc.getMailMerge().setMergeDuplicateRegions(isMergeDuplicateRegions);

     doc.getMailMerge().executeWithRegions(dataTable);
     doc.save(getArtifactsDir() + "MailMerge.MergeDuplicateRegions.docx");
 }

 public static Object[][] mergeDuplicateRegionsDataProvider() {
     return new Object[][]
             {
                     {true},
                     {false},
             };
 }

 /// <summary>
 /// Return a document that contains two duplicate mail merge regions (sharing the same name in the "TableStart/End" tags).
 /// </summary>
 private static Document createSourceDocMergeDuplicateRegions() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.insertField(" MERGEFIELD TableStart:MergeRegion");
     builder.insertField(" MERGEFIELD Column1");
     builder.insertField(" MERGEFIELD TableEnd:MergeRegion");
     builder.insertParagraph();

     builder.insertField(" MERGEFIELD TableStart:MergeRegion");
     builder.insertField(" MERGEFIELD Column2");
     builder.insertField(" MERGEFIELD TableEnd:MergeRegion");

     return doc;
 }

 /// <summary>
 /// Create a data table with one row and two columns.
 /// </summary>
 private static DataTable createSourceTableMergeDuplicateRegions() {
     DataTable dataTable = new DataTable("MergeRegion");
     dataTable.getColumns().add("Column1");
     dataTable.getColumns().add("Column2");
     dataTable.getRows().add("Value 1", "Value 2");

     return dataTable;
 }
 
 

Returns:

A value indicating whether all of the document mail merge regions with the name of a data source should be merged while executing of a mail merge with regions against the data source or just the first one.

setMergeDuplicateRegions

public void setMergeDuplicateRegions(boolean value)

Sets a value indicating whether all of the document mail merge regions with the name of a data source should be merged while executing of a mail merge with regions against the data source or just the first one.

Remarks:

The default value is false.

Examples:

Shows how to work with duplicate mail merge regions.

 
 public void mergeDuplicateRegions(boolean isMergeDuplicateRegions) throws Exception {
     // Create a document and table that we will merge
     Document doc = createSourceDocMergeDuplicateRegions();
     DataTable dataTable = createSourceTableMergeDuplicateRegions();

     // If this property is false, the first region will be merged
     // while the MERGEFIELDs of the second one will be left in the pre-merge state
     // To get both regions merged we would have to execute the mail merge twice, on a table of the same name
     // If this is set to true, both regions will be affected by the merge
     doc.getMailMerge().setMergeDuplicateRegions(isMergeDuplicateRegions);

     doc.getMailMerge().executeWithRegions(dataTable);
     doc.save(getArtifactsDir() + "MailMerge.MergeDuplicateRegions.docx");
 }

 public static Object[][] mergeDuplicateRegionsDataProvider() {
     return new Object[][]
             {
                     {true},
                     {false},
             };
 }

 /// <summary>
 /// Return a document that contains two duplicate mail merge regions (sharing the same name in the "TableStart/End" tags).
 /// </summary>
 private static Document createSourceDocMergeDuplicateRegions() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.insertField(" MERGEFIELD TableStart:MergeRegion");
     builder.insertField(" MERGEFIELD Column1");
     builder.insertField(" MERGEFIELD TableEnd:MergeRegion");
     builder.insertParagraph();

     builder.insertField(" MERGEFIELD TableStart:MergeRegion");
     builder.insertField(" MERGEFIELD Column2");
     builder.insertField(" MERGEFIELD TableEnd:MergeRegion");

     return doc;
 }

 /// <summary>
 /// Create a data table with one row and two columns.
 /// </summary>
 private static DataTable createSourceTableMergeDuplicateRegions() {
     DataTable dataTable = new DataTable("MergeRegion");
     dataTable.getColumns().add("Column1");
     dataTable.getColumns().add("Column2");
     dataTable.getRows().add("Value 1", "Value 2");

     return dataTable;
 }
 
 

Parameters:

value - A value indicating whether all of the document mail merge regions with the name of a data source should be merged while executing of a mail merge with regions against the data source or just the first one.

getMergeWholeDocument

public boolean getMergeWholeDocument()

Gets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.

Remarks:

The default value is false.

Examples:

Shows the relationship between mail merges with regions and field updating.

 
 public void mergeWholeDocument(boolean doMergeWholeDocument) throws Exception {
     // Create a document and data table that will both be merged
     Document doc = createSourceDocMergeWholeDocument();
     DataTable dataTable = createSourceTableMergeWholeDocument();

     // A regular mail merge will update all fields in the document as part of the procedure,
     // which will happen if this property is set to true
     // Otherwise, a mail merge with regions will only update fields
     // within a mail merge region which matches the name of the DataTable
     doc.getMailMerge().setMergeWholeDocument(doMergeWholeDocument);
     doc.getMailMerge().executeWithRegions(dataTable);

     // If true, all fields in the document will be updated upon merging
     // In this case that property is false, so the first QUOTE field will not be updated and will not show a value,
     // but the second one inside the region designated by the data table name will show the correct value
     doc.save(getArtifactsDir() + "MailMerge.MergeWholeDocument.docx");

     Assert.assertEquals(doMergeWholeDocument, doc.getText().contains("This QUOTE field is outside of the \"MyTable\" merge region."));
 }

 public static Object[][] mergeWholeDocumentDataProvider() throws Exception {
     return new Object[][]
             {
                     {false},
                     {true},
             };
 }

 /// <summary>
 /// Create a document with a QUOTE field outside and one more inside a mail merge region called "MyTable"
 /// </summary>
 private static Document createSourceDocMergeWholeDocument() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     // Insert QUOTE field outside of any mail merge regions
     FieldQuote field = (FieldQuote) builder.insertField(FieldType.FIELD_QUOTE, true);
     field.setText("This QUOTE field is outside of the \"MyTable\" merge region.");

     // Start "MyTable" merge region
     builder.insertParagraph();
     builder.insertField(" MERGEFIELD TableStart:MyTable");

     // Insert QUOTE field inside "MyTable" merge region
     field = (FieldQuote) builder.insertField(FieldType.FIELD_QUOTE, true);
     field.setText("This QUOTE field is inside the \"MyTable\" merge region.");
     builder.insertParagraph();

     // Add a MERGEFIELD for a column in the data table, end the "MyTable" region and return the document
     builder.insertField(" MERGEFIELD MyColumn");
     builder.insertField(" MERGEFIELD TableEnd:MyTable");

     return doc;
 }

 /// <summary>
 /// Create a simple data table that will be used in a mail merge.
 /// </summary>
 private static DataTable createSourceTableMergeWholeDocument() {
     DataTable dataTable = new DataTable("MyTable");
     dataTable.getColumns().add("MyColumn");
     dataTable.getRows().add("MyValue");

     return dataTable;
 }
 
 

Returns:

A value indicating whether fields in whole document are updated while executing of a mail merge with regions.

setMergeWholeDocument

public void setMergeWholeDocument(boolean value)

Sets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.

Remarks:

The default value is false.

Examples:

Shows the relationship between mail merges with regions and field updating.

 
 public void mergeWholeDocument(boolean doMergeWholeDocument) throws Exception {
     // Create a document and data table that will both be merged
     Document doc = createSourceDocMergeWholeDocument();
     DataTable dataTable = createSourceTableMergeWholeDocument();

     // A regular mail merge will update all fields in the document as part of the procedure,
     // which will happen if this property is set to true
     // Otherwise, a mail merge with regions will only update fields
     // within a mail merge region which matches the name of the DataTable
     doc.getMailMerge().setMergeWholeDocument(doMergeWholeDocument);
     doc.getMailMerge().executeWithRegions(dataTable);

     // If true, all fields in the document will be updated upon merging
     // In this case that property is false, so the first QUOTE field will not be updated and will not show a value,
     // but the second one inside the region designated by the data table name will show the correct value
     doc.save(getArtifactsDir() + "MailMerge.MergeWholeDocument.docx");

     Assert.assertEquals(doMergeWholeDocument, doc.getText().contains("This QUOTE field is outside of the \"MyTable\" merge region."));
 }

 public static Object[][] mergeWholeDocumentDataProvider() throws Exception {
     return new Object[][]
             {
                     {false},
                     {true},
             };
 }

 /// <summary>
 /// Create a document with a QUOTE field outside and one more inside a mail merge region called "MyTable"
 /// </summary>
 private static Document createSourceDocMergeWholeDocument() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     // Insert QUOTE field outside of any mail merge regions
     FieldQuote field = (FieldQuote) builder.insertField(FieldType.FIELD_QUOTE, true);
     field.setText("This QUOTE field is outside of the \"MyTable\" merge region.");

     // Start "MyTable" merge region
     builder.insertParagraph();
     builder.insertField(" MERGEFIELD TableStart:MyTable");

     // Insert QUOTE field inside "MyTable" merge region
     field = (FieldQuote) builder.insertField(FieldType.FIELD_QUOTE, true);
     field.setText("This QUOTE field is inside the \"MyTable\" merge region.");
     builder.insertParagraph();

     // Add a MERGEFIELD for a column in the data table, end the "MyTable" region and return the document
     builder.insertField(" MERGEFIELD MyColumn");
     builder.insertField(" MERGEFIELD TableEnd:MyTable");

     return doc;
 }

 /// <summary>
 /// Create a simple data table that will be used in a mail merge.
 /// </summary>
 private static DataTable createSourceTableMergeWholeDocument() {
     DataTable dataTable = new DataTable("MyTable");
     dataTable.getColumns().add("MyColumn");
     dataTable.getRows().add("MyValue");

     return dataTable;
 }
 
 

Parameters:

value - A value indicating whether fields in whole document are updated while executing of a mail merge with regions.

getUseWholeParagraphAsRegion

public boolean getUseWholeParagraphAsRegion()

Gets a value indicating whether whole paragraph with TableStart or TableEnd field or particular range between TableStart and TableEnd fields should be included into mail merge region.

Remarks:

The default value is true.

Examples:

Shows the relationship between mail merge regions and paragraphs.

 
 public void useWholeParagraphAsRegion() throws Exception {
     // Create a document with 2 mail merge regions in one paragraph and a table to which can fill one of the regions during a mail merge
     Document doc = createSourceDocWithNestedMergeRegions();
     DataTable dataTable = createSourceTableDataTableForOneRegion();

     // By default, a paragraph can belong to no more than one mail merge region
     // Our document breaks this rule so executing a mail merge with regions now will cause an exception to be thrown
     Assert.assertTrue(doc.getMailMerge().getUseWholeParagraphAsRegion());
     Assert.assertThrows(IllegalStateException.class, () -> doc.getMailMerge().executeWithRegions(dataTable));

     // If we set this variable to false, paragraphs and mail merge regions are independent so we can safely run our mail merge
     doc.getMailMerge().setUseWholeParagraphAsRegion(false);
     doc.getMailMerge().executeWithRegions(dataTable);

     // Our first region is populated, while our second is safely displayed as unused all across one paragraph
     doc.save(getArtifactsDir() + "MailMerge.UseWholeParagraphAsRegion.docx");
 }

 /// <summary>
 /// Create a document with two mail merge regions sharing one paragraph.
 /// </summary>
 private static Document createSourceDocWithNestedMergeRegions() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.write("Region 1: ");
     builder.insertField(" MERGEFIELD TableStart:MyTable");
     builder.insertField(" MERGEFIELD Column1");
     builder.write(", ");
     builder.insertField(" MERGEFIELD Column2");
     builder.insertField(" MERGEFIELD TableEnd:MyTable");

     builder.write(", Region 2: ");
     builder.insertField(" MERGEFIELD TableStart:MyOtherTable");
     builder.insertField(" MERGEFIELD TableEnd:MyOtherTable");

     return doc;
 }

 /// <summary>
 /// Create a data table that can populate one region during a mail merge.
 /// </summary>
 private static DataTable createSourceTableDataTableForOneRegion() {
     DataTable dataTable = new DataTable("MyTable");
     dataTable.getColumns().add("Column1");
     dataTable.getColumns().add("Column2");
     dataTable.getRows().add("Value 1", "Value 2");

     return dataTable;
 }
 
 

Returns:

A value indicating whether whole paragraph with TableStart or TableEnd field or particular range between TableStart and TableEnd fields should be included into mail merge region.

setUseWholeParagraphAsRegion

public void setUseWholeParagraphAsRegion(boolean value)

Sets a value indicating whether whole paragraph with TableStart or TableEnd field or particular range between TableStart and TableEnd fields should be included into mail merge region.

Remarks:

The default value is true.

Examples:

Shows the relationship between mail merge regions and paragraphs.

 
 public void useWholeParagraphAsRegion() throws Exception {
     // Create a document with 2 mail merge regions in one paragraph and a table to which can fill one of the regions during a mail merge
     Document doc = createSourceDocWithNestedMergeRegions();
     DataTable dataTable = createSourceTableDataTableForOneRegion();

     // By default, a paragraph can belong to no more than one mail merge region
     // Our document breaks this rule so executing a mail merge with regions now will cause an exception to be thrown
     Assert.assertTrue(doc.getMailMerge().getUseWholeParagraphAsRegion());
     Assert.assertThrows(IllegalStateException.class, () -> doc.getMailMerge().executeWithRegions(dataTable));

     // If we set this variable to false, paragraphs and mail merge regions are independent so we can safely run our mail merge
     doc.getMailMerge().setUseWholeParagraphAsRegion(false);
     doc.getMailMerge().executeWithRegions(dataTable);

     // Our first region is populated, while our second is safely displayed as unused all across one paragraph
     doc.save(getArtifactsDir() + "MailMerge.UseWholeParagraphAsRegion.docx");
 }

 /// <summary>
 /// Create a document with two mail merge regions sharing one paragraph.
 /// </summary>
 private static Document createSourceDocWithNestedMergeRegions() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.write("Region 1: ");
     builder.insertField(" MERGEFIELD TableStart:MyTable");
     builder.insertField(" MERGEFIELD Column1");
     builder.write(", ");
     builder.insertField(" MERGEFIELD Column2");
     builder.insertField(" MERGEFIELD TableEnd:MyTable");

     builder.write(", Region 2: ");
     builder.insertField(" MERGEFIELD TableStart:MyOtherTable");
     builder.insertField(" MERGEFIELD TableEnd:MyOtherTable");

     return doc;
 }

 /// <summary>
 /// Create a data table that can populate one region during a mail merge.
 /// </summary>
 private static DataTable createSourceTableDataTableForOneRegion() {
     DataTable dataTable = new DataTable("MyTable");
     dataTable.getColumns().add("Column1");
     dataTable.getColumns().add("Column2");
     dataTable.getRows().add("Value 1", "Value 2");

     return dataTable;
 }
 
 

Parameters:

value - A value indicating whether whole paragraph with TableStart or TableEnd field or particular range between TableStart and TableEnd fields should be included into mail merge region.

getRestartListsAtEachSection

public boolean getRestartListsAtEachSection()

Gets a value indicating whether lists are restarted at each section after executing of a mail merge.

Remarks:

The default value is true.

Examples:

Shows how to control whether or not list numbering is restarted at each section when mail merge is performed.

 
 Document doc = new Document(getMyDir() + "Section breaks with numbering.docx");

 doc.getMailMerge().setRestartListsAtEachSection(false);
 doc.getMailMerge().execute(new String[0], new Object[0]);

 doc.save(getArtifactsDir() + "MailMerge.RestartListsAtEachSection.pdf");
 
 

Returns:

A value indicating whether lists are restarted at each section after executing of a mail merge.

setRestartListsAtEachSection

public void setRestartListsAtEachSection(boolean value)

Sets a value indicating whether lists are restarted at each section after executing of a mail merge.

Remarks:

The default value is true.

Examples:

Shows how to control whether or not list numbering is restarted at each section when mail merge is performed.

 
 Document doc = new Document(getMyDir() + "Section breaks with numbering.docx");

 doc.getMailMerge().setRestartListsAtEachSection(false);
 doc.getMailMerge().execute(new String[0], new Object[0]);

 doc.save(getArtifactsDir() + "MailMerge.RestartListsAtEachSection.pdf");
 
 

Parameters:

value - A value indicating whether lists are restarted at each section after executing of a mail merge.

getMappedDataFields

public MappedDataFieldCollection getMappedDataFields()

Returns a collection that represents mapped data fields for the mail merge operation.

Remarks:

Mapped data fields allow to automatically map between names of fields in your data source and names of mail merge fields in the document.

Examples:

Shows how to map data columns and MERGEFIELDs with different names so the data is transferred between them during a mail merge.

 
 public void mappedDataFieldCollection() throws Exception {
     // Create a document and table that we will merge
     Document doc = createSourceDocMappedDataFields();
     DataTable dataTable = createSourceTableMappedDataFields();

     // We have a column "Column2" in the data table that doesn't have a respective MERGEFIELD in the document
     // Also, we have a MERGEFIELD named "Column3" that does not exist as a column in the data source
     // If data from "Column2" is suitable for the "Column3" MERGEFIELD,
     // we can map that column name to the MERGEFIELD in the "MappedDataFields" key/value pair
     MappedDataFieldCollection mappedDataFields = doc.getMailMerge().getMappedDataFields();

     // A data source column name is linked to a MERGEFIELD name by adding an element like this
     mappedDataFields.add("MergeFieldName", "DataSourceColumnName");

     // So, values from "Column2" will now go into MERGEFIELDs named "Column3" as well as "Column2", if there are any
     mappedDataFields.add("Column3", "Column2");

     // The MERGEFIELD name is the "key" to the respective data source column name "value"
     Assert.assertEquals(mappedDataFields.get("MergeFieldName"), "DataSourceColumnName");
     Assert.assertTrue(mappedDataFields.containsKey("MergeFieldName"));
     Assert.assertTrue(mappedDataFields.containsValue("DataSourceColumnName"));

     // Now if we run this mail merge, the "Column3" MERGEFIELDs will take data from "Column2" of the table
     doc.getMailMerge().execute(dataTable);

     // We can count and iterate over the mapped columns/fields
     Assert.assertEquals(mappedDataFields.getCount(), 2);

     Iterator<Map.Entry<String, String>> enumerator = mappedDataFields.iterator();
     try {
         while (enumerator.hasNext()) {
             Map.Entry<String, String> dataField = enumerator.next();
             System.out.println(MessageFormat.format("Column named {0} is mapped to MERGEFIELDs named {1}", dataField.getValue(), dataField.getKey()));
         }
     } finally {
         if (enumerator != null) enumerator.remove();
     }

     // We can also remove some or all of the elements
     mappedDataFields.remove("MergeFieldName");
     Assert.assertFalse(mappedDataFields.containsKey("MergeFieldName"));
     Assert.assertFalse(mappedDataFields.containsValue("DataSourceColumnName"));

     mappedDataFields.clear();
     Assert.assertEquals(mappedDataFields.getCount(), 0);

     // Removing the mapped key/value pairs has no effect on the document because the merge was already done with them in place
     doc.save(getArtifactsDir() + "MailMerge.MappedDataFieldCollection.docx");
 }

 /// <summary>
 /// Create a document with 2 MERGEFIELDs, one of which does not have a corresponding column in the data table.
 /// </summary>
 private static Document createSourceDocMappedDataFields() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     // Insert two MERGEFIELDs that will accept data from that table
     builder.insertField(" MERGEFIELD Column1");
     builder.write(", ");
     builder.insertField(" MERGEFIELD Column3");

     return doc;
 }

 /// <summary>
 /// Create a data table with 2 columns, one of which does not have a corresponding MERGEFIELD in our source document.
 /// </summary>
 private static DataTable createSourceTableMappedDataFields() {
     // Create a data table that will be used in a mail merge
     DataTable dataTable = new DataTable("MyTable");
     dataTable.getColumns().add("Column1");
     dataTable.getColumns().add("Column2");
     dataTable.getRows().add("Value1", "Value2");

     return dataTable;
 }
 
 

Returns:

A collection that represents mapped data fields for the mail merge operation.

getFieldMergingCallback

public IFieldMergingCallback getFieldMergingCallback()

Occurs during mail merge when a mail merge field is encountered in the document.

Examples:

Shows how to execute a mail merge with a custom callback that handles merge data in the form of HTML documents.

 
 public void insertHtml() throws Exception {
     Document doc = new Document(getMyDir() + "Field sample - MERGEFIELD.docx");

     // Add a handler for the MergeField event
     doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldInsertHtml());

     final String htmlText = "<html>\r\n<h1>Hello world!</h1>\r\n</html>";

     // Execute mail merge
     doc.getMailMerge().execute(new String[]{"htmlField1"}, new String[]{htmlText});

     // Save resulting document with a new name
     doc.save(getArtifactsDir() + "MailMergeEvent.InsertHtml.docx");
 }

 private class HandleMergeFieldInsertHtml implements IFieldMergingCallback {
     // This is called when merge field is actually merged with data in the document.
     public void fieldMerging(final FieldMergingArgs args) throws Exception {
         // All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'
         if (args.getDocumentFieldName().startsWith("html") && args.getField().getFieldCode().contains("\\b")) {
             FieldMergeField field = args.getField();

             // Insert the text for this merge field as HTML data, using DocumentBuilder
             DocumentBuilder builder = new DocumentBuilder(args.getDocument());
             builder.moveToMergeField(args.getDocumentFieldName());
             builder.write(field.getTextBefore());
             builder.insertHtml((String) args.getFieldValue());

             // The HTML text itself should not be inserted
             // We have already inserted it as an HTML
             args.setText("");
         }
     }

     public void imageFieldMerging(ImageFieldMergingArgs args) {
         // Do nothing
     }
 }
 
 

Shows how to insert images stored in a database BLOB field into a report.

 
 public void imageFromBlob() throws Exception {
     Document doc = new Document(getMyDir() + "Mail merge destination - Northwind employees.docx");

     // Set up the event handler for image fields
     doc.getMailMerge().setFieldMergingCallback(new HandleMergeImageFieldFromBlob());

     // Loads the driver
     Class.forName("net.ucanaccess.jdbc.UcanaccessDriver");

     // Open the database connection
     String connString = "jdbc:ucanaccess://" + getDatabaseDir() + "Northwind.accdb";

     // DSN-less DB connection
     java.sql.Connection conn = java.sql.DriverManager.getConnection(connString, "Admin", "");

     // Create and execute a command
     java.sql.Statement statement = conn.createStatement();
     java.sql.ResultSet resultSet = statement.executeQuery("SELECT * FROM Employees");

     DataTable table = new DataTable(resultSet, "Employees");

     // Perform mail merge
     doc.getMailMerge().executeWithRegions(table);

     // Close the database
     conn.close();

     doc.save(getArtifactsDir() + "MailMergeEvent.ImageFromBlob.docx");
 }

 private class HandleMergeImageFieldFromBlob implements IFieldMergingCallback {
     public void fieldMerging(final FieldMergingArgs args) {
         // Do nothing
     }

     // This is called when mail merge engine encounters Image:XXX merge field in the document.
     // You have a chance to return an Image object, file name or a stream that contains the image.
     public void imageFieldMerging(final ImageFieldMergingArgs e) {
         // The field value is a byte array, just cast it and create a stream on it
         ByteArrayInputStream imageStream = new ByteArrayInputStream((byte[]) e.getFieldValue());
         // Now the mail merge engine will retrieve the image from the stream
         e.setImageStream(imageStream);
     }
 }
 
 

Returns:

The corresponding IFieldMergingCallback value.

setFieldMergingCallback

public void setFieldMergingCallback(IFieldMergingCallback value)

Occurs during mail merge when a mail merge field is encountered in the document.

Examples:

Shows how to execute a mail merge with a custom callback that handles merge data in the form of HTML documents.

 
 public void insertHtml() throws Exception {
     Document doc = new Document(getMyDir() + "Field sample - MERGEFIELD.docx");

     // Add a handler for the MergeField event
     doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldInsertHtml());

     final String htmlText = "<html>\r\n<h1>Hello world!</h1>\r\n</html>";

     // Execute mail merge
     doc.getMailMerge().execute(new String[]{"htmlField1"}, new String[]{htmlText});

     // Save resulting document with a new name
     doc.save(getArtifactsDir() + "MailMergeEvent.InsertHtml.docx");
 }

 private class HandleMergeFieldInsertHtml implements IFieldMergingCallback {
     // This is called when merge field is actually merged with data in the document.
     public void fieldMerging(final FieldMergingArgs args) throws Exception {
         // All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'
         if (args.getDocumentFieldName().startsWith("html") && args.getField().getFieldCode().contains("\\b")) {
             FieldMergeField field = args.getField();

             // Insert the text for this merge field as HTML data, using DocumentBuilder
             DocumentBuilder builder = new DocumentBuilder(args.getDocument());
             builder.moveToMergeField(args.getDocumentFieldName());
             builder.write(field.getTextBefore());
             builder.insertHtml((String) args.getFieldValue());

             // The HTML text itself should not be inserted
             // We have already inserted it as an HTML
             args.setText("");
         }
     }

     public void imageFieldMerging(ImageFieldMergingArgs args) {
         // Do nothing
     }
 }
 
 

Shows how to insert images stored in a database BLOB field into a report.

 
 public void imageFromBlob() throws Exception {
     Document doc = new Document(getMyDir() + "Mail merge destination - Northwind employees.docx");

     // Set up the event handler for image fields
     doc.getMailMerge().setFieldMergingCallback(new HandleMergeImageFieldFromBlob());

     // Loads the driver
     Class.forName("net.ucanaccess.jdbc.UcanaccessDriver");

     // Open the database connection
     String connString = "jdbc:ucanaccess://" + getDatabaseDir() + "Northwind.accdb";

     // DSN-less DB connection
     java.sql.Connection conn = java.sql.DriverManager.getConnection(connString, "Admin", "");

     // Create and execute a command
     java.sql.Statement statement = conn.createStatement();
     java.sql.ResultSet resultSet = statement.executeQuery("SELECT * FROM Employees");

     DataTable table = new DataTable(resultSet, "Employees");

     // Perform mail merge
     doc.getMailMerge().executeWithRegions(table);

     // Close the database
     conn.close();

     doc.save(getArtifactsDir() + "MailMergeEvent.ImageFromBlob.docx");
 }

 private class HandleMergeImageFieldFromBlob implements IFieldMergingCallback {
     public void fieldMerging(final FieldMergingArgs args) {
         // Do nothing
     }

     // This is called when mail merge engine encounters Image:XXX merge field in the document.
     // You have a chance to return an Image object, file name or a stream that contains the image.
     public void imageFieldMerging(final ImageFieldMergingArgs e) {
         // The field value is a byte array, just cast it and create a stream on it
         ByteArrayInputStream imageStream = new ByteArrayInputStream((byte[]) e.getFieldValue());
         // Now the mail merge engine will retrieve the image from the stream
         e.setImageStream(imageStream);
     }
 }
 
 

Parameters:

value - The corresponding IFieldMergingCallback value.

getMailMergeCallback

public IMailMergeCallback getMailMergeCallback()

Allows to handle particular events during mail merge.

Examples:

Shows how to define custom logic for handling events during mail merge.

 
 public void testTagsReplacedEventShouldRisedWithUseNonMergeFieldsOption() throws Exception {
     Document document = new Document();
     document.getMailMerge().setUseNonMergeFields(true);

     MailMergeCallbackStub mailMergeCallbackStub = new MailMergeCallbackStub();
     document.getMailMerge().setMailMergeCallback(mailMergeCallbackStub);

     document.getMailMerge().execute(new String[0], new Object[0]);

     Assert.assertEquals(mailMergeCallbackStub.getTagsReplacedCounter(), 1);
 }

 private static class MailMergeCallbackStub implements IMailMergeCallback {
     public void tagsReplaced() {
         mTagsReplacedCounter++;
     }

     public int getTagsReplacedCounter() {
         return mTagsReplacedCounter;
     }

     private int mTagsReplacedCounter;
 }
 
 

Returns:

The corresponding IMailMergeCallback value.

setMailMergeCallback

public void setMailMergeCallback(IMailMergeCallback value)

Allows to handle particular events during mail merge.

Examples:

Shows how to define custom logic for handling events during mail merge.

 
 public void testTagsReplacedEventShouldRisedWithUseNonMergeFieldsOption() throws Exception {
     Document document = new Document();
     document.getMailMerge().setUseNonMergeFields(true);

     MailMergeCallbackStub mailMergeCallbackStub = new MailMergeCallbackStub();
     document.getMailMerge().setMailMergeCallback(mailMergeCallbackStub);

     document.getMailMerge().execute(new String[0], new Object[0]);

     Assert.assertEquals(mailMergeCallbackStub.getTagsReplacedCounter(), 1);
 }

 private static class MailMergeCallbackStub implements IMailMergeCallback {
     public void tagsReplaced() {
         mTagsReplacedCounter++;
     }

     public int getTagsReplacedCounter() {
         return mTagsReplacedCounter;
     }

     private int mTagsReplacedCounter;
 }
 
 

Parameters:

value - The corresponding IMailMergeCallback value.

getTrimWhitespaces

public boolean getTrimWhitespaces()

Gets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values.

Remarks:

The default value is true.

Examples:

Shows how to trimmed whitespaces from mail merge values.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 builder.insertField("MERGEFIELD myMergeField", null);

 doc.getMailMerge().setTrimWhitespaces(doTrimWhitespaces);
 doc.getMailMerge().execute(new String[]{"myMergeField"}, new Object[]{"\t hello world! "});

 if (doTrimWhitespaces)
     Assert.assertEquals("hello world!\f", doc.getText());
 else
     Assert.assertEquals("\t hello world! \f", doc.getText());
 
 

Returns:

A value indicating whether trailing and leading whitespaces are trimmed from mail merge values.

setTrimWhitespaces

public void setTrimWhitespaces(boolean value)

Sets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values.

Remarks:

The default value is true.

Examples:

Shows how to trimmed whitespaces from mail merge values.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 builder.insertField("MERGEFIELD myMergeField", null);

 doc.getMailMerge().setTrimWhitespaces(doTrimWhitespaces);
 doc.getMailMerge().execute(new String[]{"myMergeField"}, new Object[]{"\t hello world! "});

 if (doTrimWhitespaces)
     Assert.assertEquals("hello world!\f", doc.getText());
 else
     Assert.assertEquals("\t hello world! \f", doc.getText());
 
 

Parameters:

value - A value indicating whether trailing and leading whitespaces are trimmed from mail merge values.

getUnconditionalMergeFieldsAndRegions

public boolean getUnconditionalMergeFieldsAndRegions()

Gets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field's condition.

Remarks:

The default value is false.

Examples:

Shows how to merge fields or regions regardless of the parent IF field's condition.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Insert a MERGEFIELD nested inside an IF field
 // Since the statement of the IF field is false, the result of the inner MERGEFIELD will not be displayed
 // and the MERGEFIELD will not receive any data during a mail merge
 FieldIf fieldIf = (FieldIf) builder.insertField(" IF 1 = 2 ");
 builder.moveTo(fieldIf.getSeparator());
 builder.insertField(" MERGEFIELD  FullName ");

 // We can still count MERGEFIELDs inside false-statement IF fields if we set this flag to true
 doc.getMailMerge().setUnconditionalMergeFieldsAndRegions(doCountAllMergeFields);

 DataTable dataTable = new DataTable();
 dataTable.getColumns().add("FullName");
 dataTable.getRows().add("James Bond");

 // Execute the mail merge
 doc.getMailMerge().execute(dataTable);

 // The result will not be visible in the document because the IF field is false, but the inner MERGEFIELD did indeed receive data
 doc.save(getArtifactsDir() + "MailMerge.UnconditionalMergeFieldsAndRegions.docx");

 if (doCountAllMergeFields)
     Assert.assertEquals("IF 1 = 2 \"James Bond\"", doc.getText().trim());
 else
     Assert.assertEquals("IF 1 = 2  MERGEFIELD  FullName «FullName»", doc.getText().trim());
 
 

Returns:

A value indicating whether merge fields and merge regions are merged regardless of the parent IF field's condition.

setUnconditionalMergeFieldsAndRegions

public void setUnconditionalMergeFieldsAndRegions(boolean value)

Sets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field's condition.

Remarks:

The default value is false.

Examples:

Shows how to merge fields or regions regardless of the parent IF field's condition.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Insert a MERGEFIELD nested inside an IF field
 // Since the statement of the IF field is false, the result of the inner MERGEFIELD will not be displayed
 // and the MERGEFIELD will not receive any data during a mail merge
 FieldIf fieldIf = (FieldIf) builder.insertField(" IF 1 = 2 ");
 builder.moveTo(fieldIf.getSeparator());
 builder.insertField(" MERGEFIELD  FullName ");

 // We can still count MERGEFIELDs inside false-statement IF fields if we set this flag to true
 doc.getMailMerge().setUnconditionalMergeFieldsAndRegions(doCountAllMergeFields);

 DataTable dataTable = new DataTable();
 dataTable.getColumns().add("FullName");
 dataTable.getRows().add("James Bond");

 // Execute the mail merge
 doc.getMailMerge().execute(dataTable);

 // The result will not be visible in the document because the IF field is false, but the inner MERGEFIELD did indeed receive data
 doc.save(getArtifactsDir() + "MailMerge.UnconditionalMergeFieldsAndRegions.docx");

 if (doCountAllMergeFields)
     Assert.assertEquals("IF 1 = 2 \"James Bond\"", doc.getText().trim());
 else
     Assert.assertEquals("IF 1 = 2  MERGEFIELD  FullName «FullName»", doc.getText().trim());
 
 

Parameters:

value - A value indicating whether merge fields and merge regions are merged regardless of the parent IF field's condition.

getRetainFirstSectionStart

public boolean getRetainFirstSectionStart()

Gets a value indicating whether the PageSetup.getSectionStart() / PageSetup.setSectionStart(int) of the first document section and its copies for subsequent data source rows are retained during mail merge or updated according to MS Word behaviour.

Remarks:

The default value is true.

Returns:

A value indicating whether the PageSetup.getSectionStart() / PageSetup.setSectionStart(int) of the first document section and its copies for subsequent data source rows are retained during mail merge or updated according to MS Word behaviour.

setRetainFirstSectionStart

public void setRetainFirstSectionStart(boolean value)

Sets a value indicating whether the PageSetup.getSectionStart() / PageSetup.setSectionStart(int) of the first document section and its copies for subsequent data source rows are retained during mail merge or updated according to MS Word behaviour.

Remarks:

The default value is true.

Parameters:

value - A value indicating whether the PageSetup.getSectionStart() / PageSetup.setSectionStart(int) of the first document section and its copies for subsequent data source rows are retained during mail merge or updated according to MS Word behaviour.