MailMergeOptions

Inheritance: java.lang.Object

public class MailMergeOptions

Represents options for the mail merge functionality.

Constructors

Constructor	Description
MailMergeOptions()	Initializes a new instance of this class.

Methods

Method	Description
getCleanupOptions()	Gets a set of flags that specify what items should be removed during mail merge.
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.
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.
getMergeWholeDocument()	Gets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.
getPreserveUnusedTags()	Gets a value indicating whether the unused “mustache” tags should be preserved.
getRegionEndTag()	Gets a mail merge region end tag.
getRegionStartTag()	Gets a mail merge region start tag.
getRestartListsAtEachSection()	Gets a value indicating whether lists are restarted at each section after executing of a mail merge.
getRetainFirstSectionStart()	Gets a value indicating whether the section start 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.
getTrimWhitespaces()	Gets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values.
getUnconditionalMergeFieldsAndRegions()	Gets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field’s condition.
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.
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.
setCleanupOptions(int value)	Sets a set of flags that specify what items should be removed during mail merge.
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.
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.
setMergeWholeDocument(boolean value)	Sets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.
setPreserveUnusedTags(boolean value)	Sets a value indicating whether the unused “mustache” tags should be preserved.
setRegionEndTag(String value)	Sets a mail merge region end tag.
setRegionStartTag(String value)	Sets a mail merge region start tag.
setRestartListsAtEachSection(boolean value)	Sets a value indicating whether lists are restarted at each section after executing of a mail merge.
setRetainFirstSectionStart(boolean value)	Sets a value indicating whether the section start 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.
setTrimWhitespaces(boolean value)	Sets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values.
setUnconditionalMergeFieldsAndRegions(boolean value)	Sets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field’s condition.
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.
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.

MailMergeOptions()

public MailMergeOptions()

Initializes a new instance of this class.

getCleanupOptions()

public int getCleanupOptions()

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

Returns: int - A set of flags that specify what items should be removed during mail merge. The returned value is 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:

• !
• ,
• .
• :
• ;
• ?
• �
• �

Returns: boolean - 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.

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 .

Returns: boolean - 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 .

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

getPreserveUnusedTags()

public boolean getPreserveUnusedTags()

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

Remarks:

The default value is false .

Returns: boolean - A value indicating whether the unused “mustache” tags should be preserved.

getRegionEndTag()

public String getRegionEndTag()

Gets a mail merge region end tag.

Returns: java.lang.String - A mail merge region end tag.

getRegionStartTag()

public String getRegionStartTag()

Gets a mail merge region start tag.

Returns: java.lang.String - A mail merge region start tag.

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 .

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

getRetainFirstSectionStart()

public boolean getRetainFirstSectionStart()

Gets a value indicating whether the section start 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: boolean - A value indicating whether the section start 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.

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 .

Returns: boolean - 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 .

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

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.

Returns: boolean - The corresponding boolean value.

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 .

Returns: boolean - 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.

setCleanupOptions(int value)

public void setCleanupOptions(int value)

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

Parameters:

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

setCleanupParagraphsWithPunctuationMarks(boolean value)

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:

• !
• ,
• .
• :
• ;
• ?
• �
• �

Parameters:

Parameter	Type	Description
value	boolean	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.

setMergeDuplicateRegions(boolean value)

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 .

Parameters:

Parameter	Type	Description
value	boolean	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.

setMergeWholeDocument(boolean value)

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 .

Parameters:

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

setPreserveUnusedTags(boolean value)

public void setPreserveUnusedTags(boolean value)

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

Remarks:

The default value is false .

Parameters:

Parameter	Type	Description
value	boolean	A value indicating whether the unused “mustache” tags should be preserved.

setRegionEndTag(String value)

public void setRegionEndTag(String value)

Sets a mail merge region end tag.

Parameters:

Parameter	Type	Description
value	java.lang.String	A mail merge region end tag.

setRegionStartTag(String value)

public void setRegionStartTag(String value)

Sets a mail merge region start tag.

Parameters:

Parameter	Type	Description
value	java.lang.String	A mail merge region start tag.

setRestartListsAtEachSection(boolean value)

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 .

Parameters:

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

setRetainFirstSectionStart(boolean value)

public void setRetainFirstSectionStart(boolean value)

Sets a value indicating whether the section start 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:

Parameter	Type	Description
value	boolean	A value indicating whether the section start 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.

setTrimWhitespaces(boolean value)

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 .

Parameters:

Parameter	Type	Description
value	boolean	A value indicating whether trailing and leading whitespaces are trimmed from mail merge values.

setUnconditionalMergeFieldsAndRegions(boolean value)

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 .

Parameters:

Parameter	Type	Description
value	boolean	A value indicating whether merge fields and merge regions are merged regardless of the parent IF field’s condition.

setUseNonMergeFields(boolean value)

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.

Parameters:

Parameter	Type	Description
value	boolean	The corresponding boolean value.

setUseWholeParagraphAsRegion(boolean value)

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 .

Parameters:

Parameter	Type	Description
value	boolean	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.