MailMergeOptions (Aspose.Words for Java API Reference)

java.lang.Object
- com.aspose.words.MailMergeOptions

public class MailMergeOptions
extends java.lang.Object

Represents options for the mail merge functionality.

Examples:

Shows how to do mail merge operation for a single record.

 
 // There is a several ways to do mail merge operation:
 String doc = getMyDir() + "Mail merge.doc";

 String[] fieldNames = new String[]{"FirstName", "Location", "SpecialCharsInName()"};
 String[] fieldValues = new String[]{"James Bond", "London", "Classified"};

 MailMerger.execute(doc, getArtifactsDir() + "LowCode.MailMerge.1.docx", fieldNames, fieldValues);
 MailMerger.execute(doc, getArtifactsDir() + "LowCode.MailMerge.2.docx", SaveFormat.DOCX, fieldNames, fieldValues);
 MailMergeOptions options = new MailMergeOptions();
 options.setTrimWhitespaces(true);
 MailMerger.execute(doc, getArtifactsDir() + "LowCode.MailMerge.3.docx", SaveFormat.DOCX, fieldNames, fieldValues, options);

Constructor Summary

Constructors
Constructor and Description

MailMergeOptions()
Initializes a new instance of this class.

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

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`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.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 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.
`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`	`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 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.
`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

- Constructor Detail
  - MailMergeOptions
```
public MailMergeOptions()
```
    Initializes a new instance of this class.
- Method Detail
  - getRegionStartTag
```
public java.lang.String getRegionStartTag()
```
    Gets a mail merge region start tag.
    
    Returns:
    
    A mail merge region start tag.
  - setRegionStartTag
```
public void setRegionStartTag(java.lang.String value)
```
    Sets a mail merge region start tag.
    
    Parameters:
    
    value - A mail merge region start tag.
  - getRegionEndTag
```
public java.lang.String getRegionEndTag()
```
    Gets a mail merge region end tag.
    
    Returns:
    
    A mail merge region end tag.
  - setRegionEndTag
```
public void setRegionEndTag(java.lang.String value)
```
    Sets a mail merge region end tag.
    
    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.
    
    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.
    
    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:
    - !
    - ,
    - .
    - :
    - ;
    - ?
    - ¡
    - ¿
    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:
    - !
    - ,
    - .
    - :
    - ;
    - ?
    - ¡
    - ¿
    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.
    
    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.
    
    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.
    
    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.
    
    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.
    
    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.
    
    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.
    
    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.
    
    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.
    
    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.
    
    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.
    
    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.
    
    Parameters:
    
    value - A value indicating whether lists are restarted at each section after executing of a mail merge.
  - 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 do mail merge operation for a single record.
```
 
 // There is a several ways to do mail merge operation:
 String doc = getMyDir() + "Mail merge.doc";

 String[] fieldNames = new String[]{"FirstName", "Location", "SpecialCharsInName()"};
 String[] fieldValues = new String[]{"James Bond", "London", "Classified"};

 MailMerger.execute(doc, getArtifactsDir() + "LowCode.MailMerge.1.docx", fieldNames, fieldValues);
 MailMerger.execute(doc, getArtifactsDir() + "LowCode.MailMerge.2.docx", SaveFormat.DOCX, fieldNames, fieldValues);
 MailMergeOptions options = new MailMergeOptions();
 options.setTrimWhitespaces(true);
 MailMerger.execute(doc, getArtifactsDir() + "LowCode.MailMerge.3.docx", SaveFormat.DOCX, fieldNames, fieldValues, options);
 
 
```
    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 do mail merge operation for a single record.
```
 
 // There is a several ways to do mail merge operation:
 String doc = getMyDir() + "Mail merge.doc";

 String[] fieldNames = new String[]{"FirstName", "Location", "SpecialCharsInName()"};
 String[] fieldValues = new String[]{"James Bond", "London", "Classified"};

 MailMerger.execute(doc, getArtifactsDir() + "LowCode.MailMerge.1.docx", fieldNames, fieldValues);
 MailMerger.execute(doc, getArtifactsDir() + "LowCode.MailMerge.2.docx", SaveFormat.DOCX, fieldNames, fieldValues);
 MailMergeOptions options = new MailMergeOptions();
 options.setTrimWhitespaces(true);
 MailMerger.execute(doc, getArtifactsDir() + "LowCode.MailMerge.3.docx", SaveFormat.DOCX, fieldNames, fieldValues, options);
 
 
```
    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.
    
    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.
    
    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 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:
    
    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.
  - setRetainFirstSectionStart
```
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:
    
    value - 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.

Class MailMergeOptions

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MailMergeOptions

Method Detail

getRegionStartTag

setRegionStartTag

getRegionEndTag

setRegionEndTag

getCleanupOptions

setCleanupOptions

getCleanupParagraphsWithPunctuationMarks

setCleanupParagraphsWithPunctuationMarks

getUseNonMergeFields

setUseNonMergeFields

getPreserveUnusedTags

setPreserveUnusedTags

getMergeDuplicateRegions

setMergeDuplicateRegions

getMergeWholeDocument

setMergeWholeDocument

getUseWholeParagraphAsRegion

setUseWholeParagraphAsRegion

getRestartListsAtEachSection

setRestartListsAtEachSection

getTrimWhitespaces

setTrimWhitespaces

getUnconditionalMergeFieldsAndRegions

setUnconditionalMergeFieldsAndRegions

getRetainFirstSectionStart

setRetainFirstSectionStart