|
ASPOSE home |
java.lang.Objectcom.aspose.words.MailMerge
public class MailMerge
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 java.sql.ResultSet 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 methods to merge information into a
document with mail merge regions defined. You can use
java.sql.ResultSet, array of ResultSets or 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.
Property Getters/Setters Summary | ||
---|---|---|
MappedDataFields | getMappedDataFields() | |
Returns a collection that represents mapped data fields for the mail merge operation. | ||
boolean | getRemoveEmptyParagraphs() | |
void | setRemoveEmptyParagraphs(boolean value) | |
Specifies whether paragraphs that contained mail merge fields with no data should be removed from the document. | ||
boolean | getUseNonMergeFields() | |
void | setUseNonMergeFields(boolean value) | |
When true, specifies that in addition to MERGEFIELD fields, mail merge is performed into some other types of fields. |
Method Summary | ||
---|---|---|
void | addMergeFieldEventHandler(MergeFieldEventHandler newListener) | |
Adds the MergeFieldEventHandler to the list of subscribed listeners of MergeField event. | ||
void | addMergeImageFieldEventHandler(MergeImageFieldEventHandler newListener) | |
Adds the MergeImageFieldEventHandler to the list of subscribed listeners of MergeImageField event. | ||
void | deleteFields() | |
Removes mail merge related fields from 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 for a single record. | ||
void | execute(java.sql.ResultSet table) | |
Performs mail merge from a java.sql.ResultSet into the document. | ||
void | executeWithRegions(IMailMergeDataSource dataSource) | |
Performs a mail merge from a custom data source with mail merge regions. | ||
void | executeWithRegions(ResultSetHashMap resultSetHashMap) | |
Performs mail merge from |
||
void | executeWithRegions(java.lang.String tableName, java.sql.ResultSet resultSet) | |
Performs mail merge from a java.sql.ResultSet into the document with mail merge regions. | ||
void | executeWithRegions(java.sql.ResultSet dataTable) | |
Performs mail merge from a java.sql.ResultSet into the document with mail merge regions. | ||
void | executeWithRegions(java.sql.ResultSet[] dataSet) | |
Performs mail merge from an array of java.sql.Resultsets into a document with mail merge regions. | ||
java.lang.String[] | getFieldNames() | |
Returns a collection of mail merge field names available in the document. | ||
void | removeMergeFieldEventHandler(MergeFieldEventHandler oldListener) | |
Removes the MergeFieldEventHandler from the list of subscribed listeners of MergeField event. | ||
void | removeMergeImageFieldEventHandler(MergeImageFieldEventHandler oldListener) | |
Removes the MergeImageFieldEventHandler from the list of subscribed listeners of MergeImageField event. |
Property Getters/Setters Detail |
---|
getRemoveEmptyParagraphs/setRemoveEmptyParagraphs | |
public boolean getRemoveEmptyParagraphs() public void setRemoveEmptyParagraphs(boolean value) |
getUseNonMergeFields/setUseNonMergeFields | |
public boolean getUseNonMergeFields() public void setUseNonMergeFields(boolean value) |
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 independetly used by several customers) the ability to mail merge into other fields was introduced.
When UseNonMergeFields is set to true, mail merge will be performed into the following fields:
MERGEFIELD FieldName
MACROBUTTON NOMACRO FieldName
IF 0 = 0 "{FieldName}" ""
getMappedDataFields | |
public MappedDataFields getMappedDataFields() |
Mapped data fields allow to automatically map between names of fields in your data source and names of mail merge fields in the document.
Method Detail |
---|
execute | |
public void execute(IMailMergeDataSource dataSource) throws java.lang.Exception |
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
dataSource
- An object that implements the custom mail merge data source interface.execute | |
public void execute(java.lang.String[] fieldNames, java.lang.Object[] values) throws java.lang.Exception |
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.
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.execute | |
public void execute(java.sql.ResultSet table) throws java.lang.Exception |
Use this method to fill mail merge fields in the document with values from a ResultSet.
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 ResultSet 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 ResultSet, 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.
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.executeWithRegions | |
public void executeWithRegions(IMailMergeDataSource dataSource) throws java.lang.Exception |
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
dataSource
- An object that implements the custom mail merge data source interface.executeWithRegions | |
public void executeWithRegions(ResultSetHashMap resultSetHashMap) throws java.lang.Exception |
Used for cases when ResultSets can't correctly return its table names or when table name don't match mail merge region name but that names can't be changed.
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 accomodate records in the corresponding tables.
The document must have mail merge regions defined with names that refer to the tables
in the
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 ResultSet.
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
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.
Note that 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.
Note that mail merge regions cannot be nested inside each other and they should be well formed (there is always a pair of matching TableStart and TableEnd with the same table name).
resultSetHashMap
- executeWithRegions | |
public void executeWithRegions(java.sql.ResultSet[] dataSet) throws java.lang.Exception |
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 accomodate records in the corresponding tables.
The table name for every table (ResultSet) in ResulSets array is taken implicitly
from the first column of the ResultSet. If you want explicitly name tables, you should use
The document must have mail merge regions defined with names that refer to the tables in the ResulSets array.
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 ResulSets array.
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.
Note that 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.
Note that mail merge regions cannot be nested inside each other and they should be well formed (there is always a pair of matching TableStart and TableEnd with the same table name).
dataSet
- ResulSets array that contains data to be
inserted into mail merge fields.executeWithRegions | |
public void executeWithRegions(java.lang.String tableName, java.sql.ResultSet resultSet) throws java.lang.Exception |
Used for resultsets that can't correctly return its table name or for cases when table name don't match mail merge region name but that names can't be changed.
The document must have a mail merge region defined with name that matches tableName parameter.
If there are other mail merge regions defined in the document they are left intact. This allows to perform several mail merge operations.
tableName
- Name used for the data source.dataTable
- Data source for the mail merge operation.executeWithRegions | |
public void executeWithRegions(java.sql.ResultSet dataTable) throws java.lang.Exception |
The document must have a mail merge region defined with name that matches
table name taken implicitly from the first column of the ResultSet.
To explicitly specify another name for the table you can use
If there are other mail merge regions defined in the document they are left intact. This allows to perform several mail merge operations.
dataTable
- Data source for the mail merge operation. getFieldNames | |
public java.lang.String[] getFieldNames() throws java.lang.Exception |
Returns full merge field names including optional prefix. Does not eliminate duplicate field names.
A new string[] array is created on every call.
deleteFields | |
public void deleteFields() throws java.lang.Exception |
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.
addMergeFieldEventHandler | |
public void addMergeFieldEventHandler(MergeFieldEventHandler newListener) |
removeMergeFieldEventHandler | |
public void removeMergeFieldEventHandler(MergeFieldEventHandler oldListener) |
addMergeImageFieldEventHandler | |
public void addMergeImageFieldEventHandler(MergeImageFieldEventHandler newListener) |
removeMergeImageFieldEventHandler | |
public void removeMergeImageFieldEventHandler(MergeImageFieldEventHandler oldListener) |
|
ASPOSE home |