Represents the mail merge functionality. More...

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

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::MappedDataFieldCollection >	get_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::String >	GetFieldNames ()
	Returns a collection of mail merge field names available in the document. More...

System::ArrayPtr< System::String >	GetFieldNamesForRegion (System::String regionName)
	Returns a collection of mail merge field names available in the region. More...

System::ArrayPtr< System::String >	GetFieldNamesForRegion (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::MailMergeRegionInfo >	GetRegionsHierarchy ()
	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...

Object &	operator= (Object const &x)
	Assignment operator. Doesn't copy anything, really, just initializes new object and enables copy constructing subclasses. More...

Object *	SharedRefAdded ()
	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 TypeInfo &	GetType () 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< Object >	ptr
	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 TypeInfo &	Type ()
	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

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() [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

dataSource An 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

dataSource An 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

dataSourceRoot An 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

regionName Region 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

regionName	Region name (case-insensitive).
regionIndex	Region index (zero-based).

◆ GetRegionsByName()

System::SharedPtr<System::Collections::Generic::IList<System::SharedPtr<Aspose::Words::MailMerging::MailMergeRegionInfo> > > Aspose::Words::MailMerging::MailMerge::GetRegionsByName ( System::String regionName )

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

Parameters

regionName Region 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 )

Setter for Aspose::Words::MailMerging::MailMerge::get_CleanupOptions.

◆ set_CleanupParagraphsWithPunctuationMarks()

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

Setter for Aspose::Words::MailMerging::MailMerge::get_CleanupParagraphsWithPunctuationMarks.

◆ set_FieldMergingCallback()

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

Setter for Aspose::Words::MailMerging::MailMerge::get_FieldMergingCallback.