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

Represents the mail merge functionality. More...

#include "Aspose.Words.Cpp/Model/MailMerge/MailMerge.h"

Inherits System::Object.

Public Member Functions

System::String get_RegionStartTag () const
 Gets or sets a mail merge region start tag. More...
 
void set_RegionStartTag (System::String value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_RegionStartTag. More...
 
System::String get_RegionEndTag () const
 Gets or sets a mail merge region end tag. More...
 
void set_RegionEndTag (System::String value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_RegionEndTag. More...
 
Aspose::Words::MailMerging::MailMergeCleanupOptions get_CleanupOptions () const
 Gets or sets a set of flags that specify what items should be removed during mail merge. More...
 
void set_CleanupOptions (Aspose::Words::MailMerging::MailMergeCleanupOptions value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_CleanupOptions. 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 Aspose::Words::MailMerging::MailMergeCleanupOptions::RemoveEmptyParagraphs option is specified. More...
 
void set_CleanupParagraphsWithPunctuationMarks (bool value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_CleanupParagraphsWithPunctuationMarks. 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...
 
void set_UseNonMergeFields (bool value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_UseNonMergeFields. More...
 
bool get_PreserveUnusedTags () const
 Gets or sets a value indicating whether the unused "mustache" tags should be preserved. More...
 
void set_PreserveUnusedTags (bool value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_PreserveUnusedTags. 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...
 
void set_MergeDuplicateRegions (bool value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_MergeDuplicateRegions. 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...
 
void set_MergeWholeDocument (bool value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_MergeWholeDocument. 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...
 
void set_UseWholeParagraphAsRegion (bool value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_UseWholeParagraphAsRegion. More...
 
System::SharedPtr< Aspose::Words::MailMerging::MappedDataFieldCollectionget_MappedDataFields ()
 Returns a collection that represents mapped data fields for the mail merge operation. More...
 
System::SharedPtr< Aspose::Words::MailMerging::IFieldMergingCallback > get_FieldMergingCallback () const
 Occurs during mail merge when a mail merge field is encountered in the document. More...
 
void set_FieldMergingCallback (System::SharedPtr< Aspose::Words::MailMerging::IFieldMergingCallback > value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_FieldMergingCallback. More...
 
System::SharedPtr< Aspose::Words::MailMerging::IMailMergeCallback > get_MailMergeCallback () const
 Allows to handle particular events during mail merge. More...
 
void set_MailMergeCallback (System::SharedPtr< Aspose::Words::MailMerging::IMailMergeCallback > value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_MailMergeCallback. More...
 
bool get_TrimWhitespaces () const
 Gets or sets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values. More...
 
void set_TrimWhitespaces (bool value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_TrimWhitespaces. 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...
 
void set_UnconditionalMergeFieldsAndRegions (bool value)
 Setter for Aspose::Words::MailMerging::MailMerge::get_UnconditionalMergeFieldsAndRegions. More...
 
void Execute (System::SharedPtr< Aspose::Words::MailMerging::IMailMergeDataSource > dataSource)
 Performs a mail merge from a custom data source. More...
 
void Execute (System::ArrayPtr< System::String > fieldNames, System::ArrayPtr< System::SharedPtr< System::Object >> values)
 Performs a mail merge operation for a single record. More...
 
void ExecuteWithRegions (System::SharedPtr< Aspose::Words::MailMerging::IMailMergeDataSource > dataSource)
 Performs a mail merge from a custom data source with mail merge regions. More...
 
void ExecuteWithRegions (System::SharedPtr< Aspose::Words::MailMerging::IMailMergeDataSourceRoot > dataSourceRoot)
 Performs a mail merge from a custom data source with mail merge regions. More...
 
System::ArrayPtr< System::StringGetFieldNames ()
 Returns a collection of mail merge field names available in the document. More...
 
System::ArrayPtr< System::StringGetFieldNamesForRegion (System::String regionName)
 Returns a collection of mail merge field names available in the region. More...
 
System::ArrayPtr< System::StringGetFieldNamesForRegion (System::String regionName, int32_t regionIndex)
 Returns a collection of mail merge field names available in the region. More...
 
System::SharedPtr< System::Collections::Generic::IList< System::SharedPtr< Aspose::Words::MailMerging::MailMergeRegionInfo > > > GetRegionsByName (System::String regionName)
 Returns a collection of mail merge regions with the specified name. More...
 
System::SharedPtr< Aspose::Words::MailMerging::MailMergeRegionInfoGetRegionsHierarchy ()
 Returns a full hierarchy of regions (with fields) available in the document. More...
 
void DeleteFields ()
 Removes mail merge related fields from the document. More...
 
- Public Member Functions inherited from System::Object
 Object ()
 Creates object. Initializes all internal data structures. More...
 
virtual ~Object ()
 Destroys object. Frees all internal data structures. More...
 
 Object (Object const &x)
 Copy constructor. Doesn't copy anything, really, just initializes new object and enables copy constructing subclasses. More...
 
Objectoperator= (Object const &x)
 Assignment operator. Doesn't copy anything, really, just initializes new object and enables copy constructing subclasses. More...
 
ObjectSharedRefAdded ()
 Increments shared reference count. Shouldn't be called directly; instead, use smart pointers or ThisProtector. More...
 
int SharedRefRemovedSafe ()
 Decrements and returns shared reference count. Shouldn't be called directly; instead, use smart pointers or ThisProtector. More...
 
int RemovedSharedRefs (int count)
 Decreases shared reference count by specified value. More...
 
Detail::SmartPtrCounter * WeakRefAdded ()
 Increments weak reference count. Shouldn't be called directly; instead, use smart pointers or ThisProtector. More...
 
void WeakRefRemoved ()
 Decrements weak reference count. Shouldn't be called directly; instead, use smart pointers or ThisProtector. More...
 
Detail::SmartPtrCounter * GetCounter ()
 Gets reference counter data structure associated with the object. More...
 
int SharedCount () const
 Gets current value of shared refernce counter. More...
 
void Lock ()
 Implements C# lock() statement locking. Call directly or use LockContext sentry object. More...
 
void Unlock ()
 Implements C# lock() statement unlocking. Call directly or use LockContext sentry object. More...
 
virtual bool Equals (ptr obj)
 Compares objects using C# Object.Equals semantics. More...
 
virtual int GetHashCode () const
 Analog of C# Object.GetHashCode() method. Enables hashing of custom objects. More...
 
virtual String ToString () ASPOSE_CONST
 Analog of C# Object.ToString() method. Enables converting custom objects to string. More...
 
virtual ptr MemberwiseClone () const
 Analog of C# Object.MemberwiseClone() method. Enables cloning custom types. More...
 
virtual const TypeInfoGetType () const
 Gets actual type of object. Analog of C# System.Object.GetType() call. More...
 
virtual bool Is (const TypeInfo &targetType) const
 Check if object represents an instance of type described by targetType. Analog of C# 'is' operator. More...
 
virtual void SetTemplateWeakPtr (unsigned int argument)
 Set n'th template argument a weak pointer (rather than shared). Allows switching pointers in containers to weak mode. More...
 

Additional Inherited Members

- Public Types inherited from System::Object
typedef SmartPtr< Objectptr
 Alias for smart pointer type. More...
 
typedef System::Details::SharedMembersType shared_members_type
 structure to keep list of shared pointers contained in object. More...
 
- Static Public Member Functions inherited from System::Object
static bool ReferenceEquals (ptr const &objA, ptr const &objB)
 Compares objects by reference. More...
 
template<typename T >
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, T const &objB)
 Compares objects by reference. More...
 
template<typename T >
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, std::nullptr_t)
 Reference-compares value type object with nullptr. More...
 
template<typename T1 , typename T2 >
static std::enable_if< IsSmartPtr< T1 >::value &&IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 Compares reference type objects in C# style. More...
 
template<typename T1 , typename T2 >
static std::enable_if<!IsSmartPtr< T1 >::value &&!IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 Compares value type objects in C# style. More...
 
static const TypeInfoType ()
 Impleemnts C# typeof(System.Object) construct. More...
 
template<>
bool Equals (float const &objA, float const &objB)
 
template<>
bool Equals (double const &objA, double const &objB)
 
template<>
bool ReferenceEquals (String const &str, std::nullptr_t)
 
template<>
bool ReferenceEquals (String const &str1, String const &str2)
 

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

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 Aspose::Words::MailMerging::MailMergeCleanupOptions::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 Aspose::Words::MailMerging::IMailMergeDataSource interface.

You can use this method only when Aspose::Words::Fields::FieldOptions::get_IsBidiTextSupportedOnUpdate is false, that is you do not need Right-To-Left language (such as Arabic or Hebrew) compatibility.

This method ignores the Aspose::Words::MailMerging::MailMergeCleanupOptions::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 Aspose::Words::MailMerging::IMailMergeDataSource interface.

You can use this method only when Aspose::Words::Fields::FieldOptions::get_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 Aspose::Words::MailMerging::IMailMergeDataSourceRoot and Aspose::Words::MailMerging::IMailMergeDataSource interfaces.

You can use this method only when Aspose::Words::Fields::FieldOptions::get_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 or sets 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 Aspose::Words::MailMerging::MailMergeCleanupOptions::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 or sets a mail merge region end tag.

◆ get_RegionStartTag()

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

Gets or sets 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 Aspose::Words::MailMerging::MailMerge::get_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 Aspose::Words::MailMerging::MailMergeRegionInfo class.

Returns
Regions' hierarchy.

◆ set_CleanupOptions()

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

◆ 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)

◆ set_MailMergeCallback()

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

◆ 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)

◆ set_RegionStartTag()

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

◆ 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)