Aspose::Words::MailMerging::MailMerge Class Reference

Detailed Description

Represents the mail merge functionality.

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, DataView, IDataReader 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 DataSet, DataTable, DataView or IDataReader 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.

See also
Aspose::Words::Document, Aspose::Words::Document::get_MailMerge

#include <Aspose.Words.Cpp/Model/MailMerge/MailMerge.h>

+ Inheritance diagram for Aspose::Words::MailMerging::MailMerge:

Public Member Functions

void DeleteFields ()
 Removes mail merge related fields from the document. More...
 
void Execute (ArrayPtr< String > fieldNames, ArrayPtr< SharedPtr< Object >> values)
 Performs a mail merge operation for a single record. More...
 
void Execute (SharedPtr< IMailMergeDataSource > dataSource)
 Performs a mail merge from a custom data source. More...
 
void ExecuteWithRegions (SharedPtr< IMailMergeDataSource > dataSource)
 Performs a mail merge from a custom data source with mail merge regions. More...
 
void ExecuteWithRegions (SharedPtr< IMailMergeDataSourceRoot > dataSourceRoot)
 Performs a mail merge from a custom data source with mail merge regions. More...
 
MailMergeCleanupOptions get_CleanupOptions () const
 Gets a set of flags that specify what items should be removed during mail merge. More...
 
bool get_CleanupParagraphsWithPunctuationMarks () const
 Gets or sets a value indicating whether paragraphs with punctuation marks are considered as empty and should be removed if the RemoveEmptyParagraphs option is specified. More...
 
SharedPtr< IFieldMergingCallbackget_FieldMergingCallback () const
 Occurs during mail merge when a mail merge field is encountered in the document. More...
 
SharedPtr< IMailMergeCallbackget_MailMergeCallback () const
 Allows to handle particular events during mail merge. More...
 
SharedPtr< MappedDataFieldCollectionget_MappedDataFields ()
 Returns a collection that represents mapped data fields for the mail merge operation. More...
 
bool get_MergeDuplicateRegions () const
 Gets or 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. More...
 
bool get_MergeWholeDocument () const
 Gets or sets a value indicating whether fields in whole document is updated while executing of a mail merge with regions. More...
 
bool get_PreserveUnusedTags () const
 Gets or sets a value indicating whether the unused "mustache" tags should be preserved. More...
 
String get_RegionEndTag () const
 Gets a mail merge region end tag. More...
 
String get_RegionStartTag () const
 Gets a mail merge region start tag. More...
 
bool get_TrimWhitespaces () const
 Gets or sets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values. More...
 
bool get_UnconditionalMergeFieldsAndRegions () const
 Gets or sets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field's condition. More...
 
bool get_UseNonMergeFields () const
 When true, specifies that in addition to MERGEFIELD fields, mail merge is performed into some other types of fields and also into "{{fieldName}}" tags. More...
 
bool get_UseWholeParagraphAsRegion () const
 Gets or 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. More...
 
ArrayPtr< StringGetFieldNames ()
 Returns a collection of mail merge field names available in the document. More...
 
ArrayPtr< StringGetFieldNamesForRegion (String regionName)
 Returns a collection of mail merge field names available in the region. More...
 
ArrayPtr< StringGetFieldNamesForRegion (String regionName, int32_t regionIndex)
 Returns a collection of mail merge field names available in the region. More...
 
SharedPtr< IList< SharedPtr< MailMergeRegionInfo > > > GetRegionsByName (String regionName)
 Returns a collection of mail merge regions with the specified name. More...
 
SharedPtr< MailMergeRegionInfoGetRegionsHierarchy ()
 Returns a full hierarchy of regions (with fields) available in the document. More...
 
void set_CleanupOptions (MailMergeCleanupOptions value)
 Sets a set of flags that specify what items should be removed during mail merge. More...
 
void set_CleanupParagraphsWithPunctuationMarks (bool value)
 Setter for get_CleanupParagraphsWithPunctuationMarks. More...
 
void set_FieldMergingCallback (SharedPtr< IFieldMergingCallback > value)
 Occurs during mail merge when a mail merge field is encountered in the document. More...
 
void set_MailMergeCallback (SharedPtr< IMailMergeCallback > value)
 Allows to handle particular events during mail merge. More...
 
void set_MergeDuplicateRegions (bool value)
 Setter for get_MergeDuplicateRegions. More...
 
void set_MergeWholeDocument (bool value)
 Setter for get_MergeWholeDocument. More...
 
void set_PreserveUnusedTags (bool value)
 Setter for get_PreserveUnusedTags. More...
 
void set_RegionEndTag (String value)
 Sets a mail merge region end tag. More...
 
void set_RegionStartTag (String value)
 Sets a mail merge region start tag. More...
 
void set_TrimWhitespaces (bool value)
 Setter for get_TrimWhitespaces. More...
 
void set_UnconditionalMergeFieldsAndRegions (bool value)
 Setter for get_UnconditionalMergeFieldsAndRegions. More...
 
void set_UseNonMergeFields (bool value)
 Setter for get_UseNonMergeFields. More...
 
void set_UseWholeParagraphAsRegion (bool value)
 Setter for get_UseWholeParagraphAsRegion. More...
 
- Public Member Functions inherited from Object
ASPOSECPP_SHARED_API Object ()
 
ASPOSECPP_SHARED_API Object (Object const &x)
 
virtual ASPOSECPP_SHARED_API ~Object ()
 
virtual ASPOSECPP_SHARED_API bool Equals (ptr obj)
 
Detail::SmartPtrCounter * GetCounter ()
 
virtual ASPOSECPP_SHARED_API int GetHashCode () const
 
virtual ASPOSECPP_SHARED_API const TypeInfoGetType () const
 
virtual ASPOSECPP_SHARED_API bool Is (const TypeInfo &targetType) const
 
ASPOSECPP_SHARED_API void Lock ()
 
virtual ASPOSECPP_SHARED_API ptr MemberwiseClone () const
 
Objectoperator= (Object const &x)
 
bool ReferenceEquals (String const &str, std::nullptr_t)
 
bool ReferenceEquals (String const &str1, String const &str2)
 
int RemovedSharedRefs (int count)
 
virtual ASPOSECPP_SHARED_API void SetTemplateWeakPtr (unsigned int argument)
 
int SharedCount () const
 
ObjectSharedRefAdded ()
 
int SharedRefRemovedSafe ()
 
virtual ASPOSECPP_SHARED_API String ToString () const
 
ASPOSECPP_SHARED_API void Unlock ()
 
Detail::SmartPtrCounter * WeakRefAdded ()
 
void WeakRefRemoved ()
 

Additional Inherited Members

- Public Types inherited from Object
typedef SmartPtr< Objectptr
 
typedef System::Details::SharedMembersType shared_members_type
 
- Static Public Member Functions inherited from Object
bool Equals (double const &objA, double const &objB)
 
bool Equals (float const &objA, float const &objB)
 
static std::enable_if<!IsSmartPtr< T1 >::value &&!IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static std::enable_if< IsSmartPtr< T1 >::value &&IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static bool ReferenceEquals (ptr const &objA, ptr const &objB)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, std::nullptr_t)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, T const &objB)
 
static const TypeInfoType ()
 

Member Function Documentation

◆ DeleteFields()

void Aspose::Words::MailMerging::MailMerge::DeleteFields ( )

Removes mail merge related fields from the document.

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.

◆ Execute() [1/2]

void Aspose::Words::MailMerging::MailMerge::Execute ( System::ArrayPtr< System::String fieldNames,
System::ArrayPtr< System::SharedPtr< System::Object >>  values 
)

Performs a mail merge operation for a single record.

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 RemoveUnusedRegions option.

Parameters
fieldNamesArray 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.
valuesArray 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() [2/2]

void Aspose::Words::MailMerging::MailMerge::Execute ( System::SharedPtr< Aspose::Words::MailMerging::IMailMergeDataSource dataSource)

Performs a mail merge from a custom data source.

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 IsBidiTextSupportedOnUpdate is false, that is you do not need Right-To-Left language (such as Arabic or Hebrew) compatibility.

This method ignores the RemoveUnusedRegions option.

Parameters
dataSourceAn object that implements the custom mail merge data source interface.

◆ ExecuteWithRegions() [1/2]

void Aspose::Words::MailMerging::MailMerge::ExecuteWithRegions ( System::SharedPtr< Aspose::Words::MailMerging::IMailMergeDataSource dataSource)

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

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 IsBidiTextSupportedOnUpdate is false, that is you do not need Right-To-Left language (such as Arabic or Hebrew) compatibility.

Parameters
dataSourceAn object that implements the custom mail merge data source interface.

◆ ExecuteWithRegions() [2/2]

void Aspose::Words::MailMerging::MailMerge::ExecuteWithRegions ( System::SharedPtr< Aspose::Words::MailMerging::IMailMergeDataSourceRoot dataSourceRoot)

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

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 IsBidiTextSupportedOnUpdate is false, that is you do not need Right-To-Left language (such as Arabic or Hebrew) compatibility.

Parameters
dataSourceRootAn object that implements the custom mail merge data source root interface.

◆ get_CleanupOptions()

Aspose::Words::MailMerging::MailMergeCleanupOptions Aspose::Words::MailMerging::MailMerge::get_CleanupOptions ( ) const

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

◆ get_CleanupParagraphsWithPunctuationMarks()

bool Aspose::Words::MailMerging::MailMerge::get_CleanupParagraphsWithPunctuationMarks ( ) const

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

The default value is true.

Here is the complete list of cleanable punctuation marks:

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

◆ get_FieldMergingCallback()

System::SharedPtr<Aspose::Words::MailMerging::IFieldMergingCallback> Aspose::Words::MailMerging::MailMerge::get_FieldMergingCallback ( ) const

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

◆ get_MailMergeCallback()

System::SharedPtr<Aspose::Words::MailMerging::IMailMergeCallback> Aspose::Words::MailMerging::MailMerge::get_MailMergeCallback ( ) const

Allows to handle particular events during mail merge.

◆ get_MappedDataFields()

System::SharedPtr<Aspose::Words::MailMerging::MappedDataFieldCollection> Aspose::Words::MailMerging::MailMerge::get_MappedDataFields ( )

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

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

◆ get_MergeDuplicateRegions()

bool Aspose::Words::MailMerging::MailMerge::get_MergeDuplicateRegions ( ) const

Gets or 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.

The default value is false.

◆ get_MergeWholeDocument()

bool Aspose::Words::MailMerging::MailMerge::get_MergeWholeDocument ( ) const

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

The default value is false.

◆ get_PreserveUnusedTags()

bool Aspose::Words::MailMerging::MailMerge::get_PreserveUnusedTags ( ) const

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

The default value is false.

See also
Aspose::Words::MailMerging::MailMerge::get_UseNonMergeFields

◆ get_RegionEndTag()

System::String Aspose::Words::MailMerging::MailMerge::get_RegionEndTag ( ) const

Gets a mail merge region end tag.

◆ get_RegionStartTag()

System::String Aspose::Words::MailMerging::MailMerge::get_RegionStartTag ( ) const

Gets a mail merge region start tag.

◆ get_TrimWhitespaces()

bool Aspose::Words::MailMerging::MailMerge::get_TrimWhitespaces ( ) const

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

The default value is true.

◆ get_UnconditionalMergeFieldsAndRegions()

bool Aspose::Words::MailMerging::MailMerge::get_UnconditionalMergeFieldsAndRegions ( ) const

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

The default value is false.

◆ get_UseNonMergeFields()

bool Aspose::Words::MailMerging::MailMerge::get_UseNonMergeFields ( ) const

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

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 UseNonMergeFields 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 UserNonMergeFields is set to true, Aspose.Words will perform mail merge into text tags "{{fieldName}}". These are not fields, but just text tags.

◆ get_UseWholeParagraphAsRegion()

bool Aspose::Words::MailMerging::MailMerge::get_UseWholeParagraphAsRegion ( ) const

Gets or 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.

The default value is true.

◆ GetFieldNames()

System::ArrayPtr<System::String> Aspose::Words::MailMerging::MailMerge::GetFieldNames ( )

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

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 UseNonMergeFields is true.

◆ GetFieldNamesForRegion() [1/2]

System::ArrayPtr<System::String> Aspose::Words::MailMerging::MailMerge::GetFieldNamesForRegion ( System::String  regionName)

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

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.

Parameters
regionNameRegion name (case-insensitive).

◆ GetFieldNamesForRegion() [2/2]

System::ArrayPtr<System::String> Aspose::Words::MailMerging::MailMerge::GetFieldNamesForRegion ( System::String  regionName,
int32_t  regionIndex 
)

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

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.

Parameters
regionNameRegion name (case-insensitive).
regionIndexRegion index (zero-based).

◆ GetRegionsByName()

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

Parameters
regionNameRegion name (case-insensitive).
Returns
The list of regions.

◆ GetRegionsHierarchy()

System::SharedPtr<Aspose::Words::MailMerging::MailMergeRegionInfo> Aspose::Words::MailMerging::MailMerge::GetRegionsHierarchy ( )

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

Hierarchy is returned in the form of the MailMergeRegionInfo class.

Returns
Regions' hierarchy.

◆ set_CleanupOptions()

void Aspose::Words::MailMerging::MailMerge::set_CleanupOptions ( Aspose::Words::MailMerging::MailMergeCleanupOptions  value)

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

◆ set_CleanupParagraphsWithPunctuationMarks()

void Aspose::Words::MailMerging::MailMerge::set_CleanupParagraphsWithPunctuationMarks ( bool  value)

◆ set_FieldMergingCallback()

void Aspose::Words::MailMerging::MailMerge::set_FieldMergingCallback ( System::SharedPtr< Aspose::Words::MailMerging::IFieldMergingCallback value)

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

◆ set_MailMergeCallback()

void Aspose::Words::MailMerging::MailMerge::set_MailMergeCallback ( System::SharedPtr< Aspose::Words::MailMerging::IMailMergeCallback value)

Allows to handle particular events during mail merge.

◆ set_MergeDuplicateRegions()

void Aspose::Words::MailMerging::MailMerge::set_MergeDuplicateRegions ( bool  value)

◆ set_MergeWholeDocument()

void Aspose::Words::MailMerging::MailMerge::set_MergeWholeDocument ( bool  value)

◆ set_PreserveUnusedTags()

void Aspose::Words::MailMerging::MailMerge::set_PreserveUnusedTags ( bool  value)

◆ set_RegionEndTag()

void Aspose::Words::MailMerging::MailMerge::set_RegionEndTag ( System::String  value)

Sets a mail merge region end tag.

◆ set_RegionStartTag()

void Aspose::Words::MailMerging::MailMerge::set_RegionStartTag ( System::String  value)

Sets a mail merge region start tag.

◆ set_TrimWhitespaces()

void Aspose::Words::MailMerging::MailMerge::set_TrimWhitespaces ( bool  value)

◆ set_UnconditionalMergeFieldsAndRegions()

void Aspose::Words::MailMerging::MailMerge::set_UnconditionalMergeFieldsAndRegions ( bool  value)

◆ set_UseNonMergeFields()

void Aspose::Words::MailMerging::MailMerge::set_UseNonMergeFields ( bool  value)

◆ set_UseWholeParagraphAsRegion()

void Aspose::Words::MailMerging::MailMerge::set_UseWholeParagraphAsRegion ( bool  value)