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 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 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/MailMerging/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 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 a value indicating whether fields in whole document are updated while executing of a mail merge with regions. More...
 
bool get_PreserveUnusedTags () const
 Gets a value indicating whether the unused "mustache" tags should be preserved. More...
 
String get_RegionEndTag () const
 Gets or sets a mail merge region end tag. More...
 
String get_RegionStartTag () const
 Gets or sets a mail merge region start tag. More...
 
bool get_RestartListsAtEachSection () const
 Gets a value indicating whether lists are restarted at each section after executing of a mail merge. More...
 
bool get_RetainFirstSectionStart () const
 Gets a value indicating whether the SectionStart 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. 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 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 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...
 
virtual const TypeInfoGetType () const override
 
virtual bool Is (const TypeInfo &target) const override
 
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)
 Setter for get_FieldMergingCallback. More...
 
void set_MailMergeCallback (SharedPtr< IMailMergeCallback > value)
 Allows to handle particular events during mail merge. More...
 
void set_MergeDuplicateRegions (bool 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. More...
 
void set_MergeWholeDocument (bool value)
 Sets a value indicating whether fields in whole document are updated while executing of a mail merge with regions. More...
 
void set_PreserveUnusedTags (bool value)
 Sets a value indicating whether the unused "mustache" tags should be preserved. More...
 
void set_RegionEndTag (String value)
 Setter for get_RegionEndTag. More...
 
void set_RegionStartTag (String value)
 Setter for get_RegionStartTag. More...
 
void set_RestartListsAtEachSection (bool value)
 Sets a value indicating whether lists are restarted at each section after executing of a mail merge. More...
 
void set_RetainFirstSectionStart (bool value)
 Sets a value indicating whether the SectionStart 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. More...
 
void set_TrimWhitespaces (bool value)
 Setter for get_TrimWhitespaces. More...
 
void set_UnconditionalMergeFieldsAndRegions (bool value)
 Sets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field's condition. More...
 
void set_UseNonMergeFields (bool value)
 Setter for get_UseNonMergeFields. More...
 
void set_UseWholeParagraphAsRegion (bool 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. More...
 

Static Public Member Functions

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.

Examples

Shows how to delete all MERGEFIELDs from a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Write(u"Dear ");
builder->InsertField(u" MERGEFIELD FirstName ");
builder->Write(u" ");
builder->InsertField(u" MERGEFIELD LastName ");
builder->Writeln(u",");
builder->Writeln(u"Greetings!");
ASSERT_EQ(u"Dear \u0013 MERGEFIELD FirstName \u0014«FirstName»\u0015 \u0013 MERGEFIELD LastName \u0014«LastName»\u0015,\rGreetings!",
doc->GetText().Trim());
doc->get_MailMerge()->DeleteFields();
ASSERT_EQ(u"Dear ,\rGreetings!", doc->GetText().Trim());

◆ 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.
Examples

Shows how to merge an image from a URI as mail merge data into a MERGEFIELD.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// MERGEFIELDs with "Image:" tags will receive an image during a mail merge.
// The string after the colon in the "Image:" tag corresponds to a column name
// in the data source whose cells contain URIs of image files.
builder->InsertField(u"MERGEFIELD Image:logo_FromWeb ");
builder->InsertField(u"MERGEFIELD Image:logo_FromFileSystem ");
// Create a data source that contains URIs of images that we will merge.
// A URI can be a web URL that points to an image, or a local file system filename of an image file.
ArrayPtr<String> columns = MakeArray<String>({u"logo_FromWeb", u"logo_FromFileSystem"});
ArrayPtr<SharedPtr<System::Object>> URIs =
MakeArray<SharedPtr<System::Object>>({System::ObjectExt::Box<String>(AsposeLogoUrl), System::ObjectExt::Box<String>(ImageDir + u"Logo.jpg")});
// Execute a mail merge on a data source with one row.
doc->get_MailMerge()->Execute(columns, URIs);
doc->Save(ArtifactsDir + u"MailMergeEvent.ImageFromUrl.docx");

◆ 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.
Examples

Shows how to execute a mail merge with a data source in the form of a custom object.

void CustomDataSource()
{
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertField(u" MERGEFIELD FullName ");
builder->InsertParagraph();
builder->InsertField(u" MERGEFIELD Address ");
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Customer>>> customers =
MakeObject<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Customer>>>();
customers->Add(MakeObject<ExMailMergeCustom::Customer>(u"Thomas Hardy", u"120 Hanover Sq., London"));
customers->Add(MakeObject<ExMailMergeCustom::Customer>(u"Paolo Accorti", u"Via Monte Bianco 34, Torino"));
// To use a custom object as a data source, it must implement the IMailMergeDataSource interface.
auto dataSource = MakeObject<ExMailMergeCustom::CustomerMailMergeDataSource>(customers);
doc->get_MailMerge()->Execute(dataSource);
doc->Save(ArtifactsDir + u"MailMergeCustom.CustomDataSource.docx");
}
class Customer : public System::Object
{
public:
String get_FullName()
{
return pr_FullName;
}
void set_FullName(String value)
{
pr_FullName = value;
}
String get_Address()
{
return pr_Address;
}
void set_Address(String value)
{
pr_Address = value;
}
Customer(String aFullName, String anAddress)
{
set_FullName(aFullName);
set_Address(anAddress);
}
private:
String pr_FullName;
String pr_Address;
};
class CustomerMailMergeDataSource : public IMailMergeDataSource
{
public:
String get_TableName() override
{
return u"Customer";
}
CustomerMailMergeDataSource(SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Customer>>> customers) : mRecordIndex(0)
{
mCustomers = customers;
// When we initialize the data source, its position must be before the first record.
mRecordIndex = -1;
}
bool GetValue(String fieldName, SharedPtr<System::Object>& fieldValue) override
{
if (fieldName == u"FullName")
{
fieldValue = System::ObjectExt::Box<String>(mCustomers->idx_get(mRecordIndex)->get_FullName());
return true;
}
else if (fieldName == u"Address")
{
fieldValue = System::ObjectExt::Box<String>(mCustomers->idx_get(mRecordIndex)->get_Address());
return true;
}
else
{
fieldValue.reset();
return false;
}
}
bool MoveNext() override
{
if (!get_IsEof())
{
mRecordIndex++;
}
return !get_IsEof();
}
SharedPtr<IMailMergeDataSource> GetChildDataSource(String tableName) override
{
return nullptr;
}
private:
bool get_IsEof()
{
return mRecordIndex >= mCustomers->get_Count();
}
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Customer>>> mCustomers;
int mRecordIndex;
};

◆ 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.
Examples

Shows how to use mail merge regions to execute a nested mail merge.

void CustomDataSource()
{
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Normally, MERGEFIELDs contain the name of a column of a mail merge data source.
// Instead, we can use "TableStart:" and "TableEnd:" prefixes to begin/end a mail merge region.
// Each region will belong to a table with a name that matches the string immediately after the prefix's colon.
builder->InsertField(u" MERGEFIELD TableStart:Customers");
// These MERGEFIELDs are inside the mail merge region of the "Customers" table.
// When we execute the mail merge, this field will receive data from rows in a data source named "Customers".
builder->Write(u"Full name:\t");
builder->InsertField(u" MERGEFIELD FullName ");
builder->Write(u"\nAddress:\t");
builder->InsertField(u" MERGEFIELD Address ");
builder->Write(u"\nOrders:\n");
// Create a second mail merge region inside the outer region for a data source named "Orders".
// The "Orders" data entries have a many-to-one relationship with the "Customers" data source.
builder->InsertField(u" MERGEFIELD TableStart:Orders");
builder->Write(u"\tItem name:\t");
builder->InsertField(u" MERGEFIELD Name ");
builder->Write(u"\n\tQuantity:\t");
builder->InsertField(u" MERGEFIELD Quantity ");
builder->InsertParagraph();
builder->InsertField(u" MERGEFIELD TableEnd:Orders");
builder->InsertField(u" MERGEFIELD TableEnd:Customers");
// Create related data with names that match those of our mail merge regions.
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Customer>>> customers =
MakeObject<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Customer>>>();
customers->Add(MakeObject<ExMailMergeCustomNested::Customer>(u"Thomas Hardy", u"120 Hanover Sq., London"));
customers->Add(MakeObject<ExMailMergeCustomNested::Customer>(u"Paolo Accorti", u"Via Monte Bianco 34, Torino"));
customers->idx_get(0)->get_Orders()->Add(MakeObject<ExMailMergeCustomNested::Order>(u"Rugby World Cup Cap", 2));
customers->idx_get(0)->get_Orders()->Add(MakeObject<ExMailMergeCustomNested::Order>(u"Rugby World Cup Ball", 1));
customers->idx_get(1)->get_Orders()->Add(MakeObject<ExMailMergeCustomNested::Order>(u"Rugby World Cup Guide", 1));
// To mail merge from your data source, we must wrap it into an object that implements the IMailMergeDataSource interface.
auto customersDataSource = MakeObject<ExMailMergeCustomNested::CustomerMailMergeDataSource>(customers);
doc->get_MailMerge()->ExecuteWithRegions(customersDataSource);
doc->Save(ArtifactsDir + u"NestedMailMergeCustom.CustomDataSource.docx");
}
class Customer : public System::Object
{
public:
String get_FullName()
{
return pr_FullName;
}
void set_FullName(String value)
{
pr_FullName = value;
}
String get_Address()
{
return pr_Address;
}
void set_Address(String value)
{
pr_Address = value;
}
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Order>>> get_Orders()
{
return pr_Orders;
}
void set_Orders(SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Order>>> value)
{
pr_Orders = value;
}
Customer(String aFullName, String anAddress)
{
set_FullName(aFullName);
set_Address(anAddress);
set_Orders(MakeObject<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Order>>>());
}
private:
String pr_FullName;
String pr_Address;
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Order>>> pr_Orders;
};
class Order : public System::Object
{
public:
String get_Name()
{
return pr_Name;
}
void set_Name(String value)
{
pr_Name = value;
}
int get_Quantity()
{
return pr_Quantity;
}
void set_Quantity(int value)
{
pr_Quantity = value;
}
Order(String oName, int oQuantity) : pr_Quantity(0)
{
set_Name(oName);
set_Quantity(oQuantity);
}
private:
String pr_Name;
int pr_Quantity;
};
class CustomerMailMergeDataSource : public IMailMergeDataSource
{
public:
String get_TableName() override
{
return u"Customers";
}
CustomerMailMergeDataSource(SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Customer>>> customers) : mRecordIndex(0)
{
mCustomers = customers;
// When we initialize the data source, its position must be before the first record.
mRecordIndex = -1;
}
bool GetValue(String fieldName, SharedPtr<System::Object>& fieldValue) override
{
if (fieldName == u"FullName")
{
fieldValue = System::ObjectExt::Box<String>(mCustomers->idx_get(mRecordIndex)->get_FullName());
return true;
}
else if (fieldName == u"Address")
{
fieldValue = System::ObjectExt::Box<String>(mCustomers->idx_get(mRecordIndex)->get_Address());
return true;
}
else if (fieldName == u"Order")
{
fieldValue = mCustomers->idx_get(mRecordIndex)->get_Orders();
return true;
}
else
{
fieldValue.reset();
return false;
}
}
bool MoveNext() override
{
if (!get_IsEof())
{
mRecordIndex++;
}
return !get_IsEof();
}
SharedPtr<IMailMergeDataSource> GetChildDataSource(String tableName) override
{
if (tableName == u"Orders")
{
return MakeObject<ExMailMergeCustomNested::OrderMailMergeDataSource>(mCustomers->idx_get(mRecordIndex)->get_Orders());
}
else
{
return nullptr;
}
}
private:
bool get_IsEof()
{
return mRecordIndex >= mCustomers->get_Count();
}
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Customer>>> mCustomers;
int mRecordIndex;
};
class OrderMailMergeDataSource : public IMailMergeDataSource
{
public:
String get_TableName() override
{
return u"Orders";
}
OrderMailMergeDataSource(SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Order>>> orders) : mRecordIndex(0)
{
mOrders = orders;
// When we initialize the data source, its position must be before the first record.
mRecordIndex = -1;
}
bool GetValue(String fieldName, SharedPtr<System::Object>& fieldValue) override
{
if (fieldName == u"Name")
{
fieldValue = System::ObjectExt::Box<String>(mOrders->idx_get(mRecordIndex)->get_Name());
return true;
}
else if (fieldName == u"Quantity")
{
fieldValue = System::ObjectExt::Box<int>(mOrders->idx_get(mRecordIndex)->get_Quantity());
return true;
}
else
{
fieldValue.reset();
return false;
}
}
bool MoveNext() override
{
if (!get_IsEof())
{
mRecordIndex++;
}
return !get_IsEof();
}
SharedPtr<IMailMergeDataSource> GetChildDataSource(String tableName) override
{
return nullptr;
}
private:
bool get_IsEof()
{
return mRecordIndex >= mOrders->get_Count();
}
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustomNested::Order>>> mOrders;
int mRecordIndex;
};

◆ 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.
Examples

Performs mail merge from a custom data source with master-detail data.

void CustomDataSourceRoot()
{
// Create a document with two mail merge regions named "Washington" and "Seattle".
ArrayPtr<String> mailMergeRegions = MakeArray<String>({u"Vancouver", u"Seattle"});
SharedPtr<Document> doc = CreateSourceDocumentWithMailMergeRegions(mailMergeRegions);
// Create two data sources for the mail merge.
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Employee>>> employeesWashingtonBranch =
MakeObject<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Employee>>>();
employeesWashingtonBranch->Add(MakeObject<ExMailMergeCustom::Employee>(u"John Doe", u"Sales"));
employeesWashingtonBranch->Add(MakeObject<ExMailMergeCustom::Employee>(u"Jane Doe", u"Management"));
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Employee>>> employeesSeattleBranch =
MakeObject<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Employee>>>();
employeesSeattleBranch->Add(MakeObject<ExMailMergeCustom::Employee>(u"John Cardholder", u"Management"));
employeesSeattleBranch->Add(MakeObject<ExMailMergeCustom::Employee>(u"Joe Bloggs", u"Sales"));
// Register our data sources by name in a data source root.
// If we are about to use this data source root in a mail merge with regions,
// each source's registered name must match the name of an existing mail merge region in the mail merge source document.
auto sourceRoot = MakeObject<ExMailMergeCustom::DataSourceRoot>();
sourceRoot->RegisterSource(mailMergeRegions[0], MakeObject<ExMailMergeCustom::EmployeeListMailMergeSource>(employeesWashingtonBranch));
sourceRoot->RegisterSource(mailMergeRegions[1], MakeObject<ExMailMergeCustom::EmployeeListMailMergeSource>(employeesSeattleBranch));
// Since we have consecutive mail merge regions, we would normally have to perform two mail merges.
// However, one mail merge source with a data root can fill in multiple regions
// if the root contains tables with corresponding names/column names.
doc->get_MailMerge()->ExecuteWithRegions(sourceRoot);
doc->Save(ArtifactsDir + u"MailMergeCustom.CustomDataSourceRoot.docx");
}
static SharedPtr<Document> CreateSourceDocumentWithMailMergeRegions(ArrayPtr<String> regions)
{
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
for (String s : regions)
{
builder->Writeln(String(u"\n") + s + u" branch: ");
builder->InsertField(String(u" MERGEFIELD TableStart:") + s);
builder->InsertField(u" MERGEFIELD FullName");
builder->Write(u", ");
builder->InsertField(u" MERGEFIELD Department");
builder->InsertField(String(u" MERGEFIELD TableEnd:") + s);
}
return doc;
}
class Employee : public System::Object
{
public:
String get_FullName()
{
return pr_FullName;
}
String get_Department()
{
return pr_Department;
}
Employee(String aFullName, String aDepartment)
{
pr_FullName = aFullName;
pr_Department = aDepartment;
}
private:
String pr_FullName;
String pr_Department;
};
class DataSourceRoot : public IMailMergeDataSourceRoot
{
public:
SharedPtr<IMailMergeDataSource> GetDataSource(String tableName) override
{
SharedPtr<ExMailMergeCustom::EmployeeListMailMergeSource> source = mSources->idx_get(tableName);
source->Reset();
return mSources->idx_get(tableName);
}
void RegisterSource(String sourceName, SharedPtr<ExMailMergeCustom::EmployeeListMailMergeSource> source)
{
mSources->Add(sourceName, source);
}
DataSourceRoot() : mSources(MakeObject<System::Collections::Generic::Dictionary<String, SharedPtr<ExMailMergeCustom::EmployeeListMailMergeSource>>>())
{
}
private:
SharedPtr<System::Collections::Generic::Dictionary<String, SharedPtr<ExMailMergeCustom::EmployeeListMailMergeSource>>> mSources;
};
class EmployeeListMailMergeSource : public IMailMergeDataSource
{
public:
String get_TableName() override
{
return u"Employees";
}
EmployeeListMailMergeSource(SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Employee>>> employees) : mRecordIndex(0)
{
mEmployees = employees;
mRecordIndex = -1;
}
bool MoveNext() override
{
if (!get_IsEof())
{
mRecordIndex++;
}
return !get_IsEof();
}
void Reset()
{
mRecordIndex = -1;
}
bool GetValue(String fieldName, SharedPtr<System::Object>& fieldValue) override
{
if (fieldName == u"FullName")
{
fieldValue = System::ObjectExt::Box<String>(mEmployees->idx_get(mRecordIndex)->get_FullName());
return true;
}
else if (fieldName == u"Department")
{
fieldValue = System::ObjectExt::Box<String>(mEmployees->idx_get(mRecordIndex)->get_Department());
return true;
}
else
{
fieldValue.reset();
return false;
}
}
SharedPtr<IMailMergeDataSource> GetChildDataSource(String tableName) override
{
}
private:
bool get_IsEof()
{
return mRecordIndex >= mEmployees->get_Count();
}
SharedPtr<System::Collections::Generic::List<SharedPtr<ExMailMergeCustom::Employee>>> mEmployees;
int mRecordIndex;
};

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

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

Shows how to remove paragraphs with punctuation marks after a mail merge operation.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
auto mergeFieldOption1 = System::DynamicCast<FieldMergeField>(builder->InsertField(u"MERGEFIELD", u"Option_1"));
mergeFieldOption1->set_FieldName(u"Option_1");
builder->Write(punctuationMark);
auto mergeFieldOption2 = System::DynamicCast<FieldMergeField>(builder->InsertField(u"MERGEFIELD", u"Option_2"));
mergeFieldOption2->set_FieldName(u"Option_2");
// Configure the "CleanupOptions" property to remove any empty paragraphs that this mail merge would create.
doc->get_MailMerge()->set_CleanupOptions(MailMergeCleanupOptions::RemoveEmptyParagraphs);
// Setting the "CleanupParagraphsWithPunctuationMarks" property to "true" will also count paragraphs
// with punctuation marks as empty and will get the mail merge operation to remove them as well.
// Setting the "CleanupParagraphsWithPunctuationMarks" property to "false"
// will remove empty paragraphs, but not ones with punctuation marks.
// This is a list of punctuation marks that this property concerns: "!", ",", ".", ":", ";", "?", "¡", "¿".
doc->get_MailMerge()->set_CleanupParagraphsWithPunctuationMarks(cleanupParagraphsWithPunctuationMarks);
doc->get_MailMerge()->Execute(MakeArray<String>({u"Option_1", u"Option_2"}), MakeArray<SharedPtr<System::Object>>({nullptr, nullptr}));
doc->Save(ArtifactsDir + u"MailMerge.RemoveColonBetweenEmptyMergeFields.docx");

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

Examples

Shows how to execute a mail merge with a custom callback that handles merge data in the form of HTML documents.

void MergeHtml()
{
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertField(u"MERGEFIELD html_Title \\b Content");
builder->InsertField(u"MERGEFIELD html_Body \\b Content");
ArrayPtr<SharedPtr<System::Object>> mergeData = MakeArray<SharedPtr<System::Object>>(
{System::ObjectExt::Box<String>(String(u"<html>") + u"<h1>" + u"<span style=\"color: #0000ff; font-family: Arial;\">Hello World!</span>" +
u"</h1>" + u"</html>"),
System::ObjectExt::Box<String>(
String(u"<html>") + u"<blockquote>" +
u"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>" +
u"</blockquote>" + u"</html>")});
doc->get_MailMerge()->set_FieldMergingCallback(MakeObject<ExMailMergeEvent::HandleMergeFieldInsertHtml>());
doc->get_MailMerge()->Execute(MakeArray<String>({u"html_Title", u"html_Body"}), mergeData);
doc->Save(ArtifactsDir + u"MailMergeEvent.MergeHtml.docx");
}
class HandleMergeFieldInsertHtml : public IFieldMergingCallback
{
public:
void FieldMerging(SharedPtr<FieldMergingArgs> args) override
{
if (args->get_DocumentFieldName().StartsWith(u"html_") && args->get_Field()->GetFieldCode().Contains(u"\\b"))
{
// Add parsed HTML data to the document's body.
auto builder = MakeObject<DocumentBuilder>(args->get_Document());
builder->MoveToMergeField(args->get_DocumentFieldName());
builder->InsertHtml(System::ObjectExt::Unbox<String>(args->get_FieldValue()));
// Since we have already inserted the merged content manually,
// we will not need to respond to this event by returning content via the "Text" property.
args->set_Text(String::Empty);
}
}
void ImageFieldMerging(SharedPtr<ImageFieldMergingArgs> args) override
{
// Do nothing.
}
};

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

◆ get_MergeWholeDocument()

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

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

◆ get_PreserveUnusedTags()

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

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

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.

Examples

Shows how to create, list, and read mail merge regions.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// "TableStart" and "TableEnd" tags, which go inside MERGEFIELDs,
// denote the strings that signify the starts and ends of mail merge regions.
ASSERT_EQ(u"TableStart", doc->get_MailMerge()->get_RegionStartTag());
ASSERT_EQ(u"TableEnd", doc->get_MailMerge()->get_RegionEndTag());
// Use these tags to start and end a mail merge region named "MailMergeRegion1",
// which will contain MERGEFIELDs for two columns.
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column1");
builder->Write(u", ");
builder->InsertField(u" MERGEFIELD Column2");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// We can keep track of merge regions and their columns by looking at these collections.
SharedPtr<System::Collections::Generic::IList<SharedPtr<MailMergeRegionInfo>>> regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(1, regions->get_Count());
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(0)->get_Name());
ArrayPtr<String> mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1");
ASSERT_EQ(u"Column1", mergeFieldNames[0]);
ASSERT_EQ(u"Column2", mergeFieldNames[1]);
// Insert a region with the same name as an existing region, which will make it a duplicate.
// Multiple mail merge regions cannot share a single row/paragraph.
builder->InsertParagraph();
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column3");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// If we look up the name of duplicate regions using the "GetRegionsByName" method,
// it will return all such regions in a collection.
regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(2, regions->get_Count());
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
ASSERT_EQ(u"Column3", mergeFieldNames[0]);

◆ get_RegionStartTag()

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

Gets or sets a mail merge region start tag.

Examples

Shows how to create, list, and read mail merge regions.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// "TableStart" and "TableEnd" tags, which go inside MERGEFIELDs,
// denote the strings that signify the starts and ends of mail merge regions.
ASSERT_EQ(u"TableStart", doc->get_MailMerge()->get_RegionStartTag());
ASSERT_EQ(u"TableEnd", doc->get_MailMerge()->get_RegionEndTag());
// Use these tags to start and end a mail merge region named "MailMergeRegion1",
// which will contain MERGEFIELDs for two columns.
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column1");
builder->Write(u", ");
builder->InsertField(u" MERGEFIELD Column2");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// We can keep track of merge regions and their columns by looking at these collections.
SharedPtr<System::Collections::Generic::IList<SharedPtr<MailMergeRegionInfo>>> regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(1, regions->get_Count());
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(0)->get_Name());
ArrayPtr<String> mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1");
ASSERT_EQ(u"Column1", mergeFieldNames[0]);
ASSERT_EQ(u"Column2", mergeFieldNames[1]);
// Insert a region with the same name as an existing region, which will make it a duplicate.
// Multiple mail merge regions cannot share a single row/paragraph.
builder->InsertParagraph();
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column3");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// If we look up the name of duplicate regions using the "GetRegionsByName" method,
// it will return all such regions in a collection.
regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(2, regions->get_Count());
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
ASSERT_EQ(u"Column3", mergeFieldNames[0]);

◆ get_RestartListsAtEachSection()

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

Gets a value indicating whether lists are restarted at each section after executing of a mail merge.

◆ get_RetainFirstSectionStart()

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

Gets a value indicating whether the SectionStart 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.

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

Examples

Shows how to trim whitespaces from values of a data source while executing a mail merge.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertField(u"MERGEFIELD myMergeField", nullptr);
doc->get_MailMerge()->set_TrimWhitespaces(trimWhitespaces);
doc->get_MailMerge()->Execute(MakeArray<String>({u"myMergeField"}),
MakeArray<SharedPtr<System::Object>>({System::ObjectExt::Box<String>(u"\t hello world! ")}));
ASSERT_EQ(trimWhitespaces ? String(u"hello world!\f") : String(u"\t hello world! \f"), doc->GetText());

◆ get_UnconditionalMergeFieldsAndRegions()

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

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

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

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

Shows how to create, list, and read mail merge regions.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// "TableStart" and "TableEnd" tags, which go inside MERGEFIELDs,
// denote the strings that signify the starts and ends of mail merge regions.
ASSERT_EQ(u"TableStart", doc->get_MailMerge()->get_RegionStartTag());
ASSERT_EQ(u"TableEnd", doc->get_MailMerge()->get_RegionEndTag());
// Use these tags to start and end a mail merge region named "MailMergeRegion1",
// which will contain MERGEFIELDs for two columns.
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column1");
builder->Write(u", ");
builder->InsertField(u" MERGEFIELD Column2");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// We can keep track of merge regions and their columns by looking at these collections.
SharedPtr<System::Collections::Generic::IList<SharedPtr<MailMergeRegionInfo>>> regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(1, regions->get_Count());
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(0)->get_Name());
ArrayPtr<String> mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1");
ASSERT_EQ(u"Column1", mergeFieldNames[0]);
ASSERT_EQ(u"Column2", mergeFieldNames[1]);
// Insert a region with the same name as an existing region, which will make it a duplicate.
// Multiple mail merge regions cannot share a single row/paragraph.
builder->InsertParagraph();
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column3");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// If we look up the name of duplicate regions using the "GetRegionsByName" method,
// it will return all such regions in a collection.
regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(2, regions->get_Count());
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
ASSERT_EQ(u"Column3", mergeFieldNames[0]);

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

Shows how to create, list, and read mail merge regions.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// "TableStart" and "TableEnd" tags, which go inside MERGEFIELDs,
// denote the strings that signify the starts and ends of mail merge regions.
ASSERT_EQ(u"TableStart", doc->get_MailMerge()->get_RegionStartTag());
ASSERT_EQ(u"TableEnd", doc->get_MailMerge()->get_RegionEndTag());
// Use these tags to start and end a mail merge region named "MailMergeRegion1",
// which will contain MERGEFIELDs for two columns.
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column1");
builder->Write(u", ");
builder->InsertField(u" MERGEFIELD Column2");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// We can keep track of merge regions and their columns by looking at these collections.
SharedPtr<System::Collections::Generic::IList<SharedPtr<MailMergeRegionInfo>>> regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(1, regions->get_Count());
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(0)->get_Name());
ArrayPtr<String> mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1");
ASSERT_EQ(u"Column1", mergeFieldNames[0]);
ASSERT_EQ(u"Column2", mergeFieldNames[1]);
// Insert a region with the same name as an existing region, which will make it a duplicate.
// Multiple mail merge regions cannot share a single row/paragraph.
builder->InsertParagraph();
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column3");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// If we look up the name of duplicate regions using the "GetRegionsByName" method,
// it will return all such regions in a collection.
regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(2, regions->get_Count());
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
ASSERT_EQ(u"Column3", mergeFieldNames[0]);

◆ GetRegionsByName()

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

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

Shows how to create, list, and read mail merge regions.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// "TableStart" and "TableEnd" tags, which go inside MERGEFIELDs,
// denote the strings that signify the starts and ends of mail merge regions.
ASSERT_EQ(u"TableStart", doc->get_MailMerge()->get_RegionStartTag());
ASSERT_EQ(u"TableEnd", doc->get_MailMerge()->get_RegionEndTag());
// Use these tags to start and end a mail merge region named "MailMergeRegion1",
// which will contain MERGEFIELDs for two columns.
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column1");
builder->Write(u", ");
builder->InsertField(u" MERGEFIELD Column2");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// We can keep track of merge regions and their columns by looking at these collections.
SharedPtr<System::Collections::Generic::IList<SharedPtr<MailMergeRegionInfo>>> regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(1, regions->get_Count());
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(0)->get_Name());
ArrayPtr<String> mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1");
ASSERT_EQ(u"Column1", mergeFieldNames[0]);
ASSERT_EQ(u"Column2", mergeFieldNames[1]);
// Insert a region with the same name as an existing region, which will make it a duplicate.
// Multiple mail merge regions cannot share a single row/paragraph.
builder->InsertParagraph();
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->InsertField(u" MERGEFIELD Column3");
builder->InsertField(u" MERGEFIELD TableEnd:MailMergeRegion1");
// If we look up the name of duplicate regions using the "GetRegionsByName" method,
// it will return all such regions in a collection.
regions = doc->get_MailMerge()->GetRegionsByName(u"MailMergeRegion1");
ASSERT_EQ(2, regions->get_Count());
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
ASSERT_EQ(u"Column3", mergeFieldNames[0]);

◆ 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.
Examples

Shows how to verify mail merge regions.

auto doc = MakeObject<Document>(MyDir + u"Mail merge regions.docx");
// Returns a full hierarchy of merge regions that contain MERGEFIELDs available in the document.
SharedPtr<MailMergeRegionInfo> regionInfo = doc->get_MailMerge()->GetRegionsHierarchy();
// Get top regions in the document.
SharedPtr<System::Collections::Generic::IList<SharedPtr<MailMergeRegionInfo>>> topRegions = regionInfo->get_Regions();
ASSERT_EQ(2, topRegions->get_Count());
ASSERT_EQ(u"Region1", topRegions->idx_get(0)->get_Name());
ASSERT_EQ(u"Region2", topRegions->idx_get(1)->get_Name());
ASSERT_EQ(1, topRegions->idx_get(0)->get_Level());
ASSERT_EQ(1, topRegions->idx_get(1)->get_Level());
// Get nested region in first top region.
SharedPtr<System::Collections::Generic::IList<SharedPtr<MailMergeRegionInfo>>> nestedRegions = topRegions->idx_get(0)->get_Regions();
ASSERT_EQ(2, nestedRegions->get_Count());
ASSERT_EQ(u"NestedRegion1", nestedRegions->idx_get(0)->get_Name());
ASSERT_EQ(u"NestedRegion2", nestedRegions->idx_get(1)->get_Name());
ASSERT_EQ(2, nestedRegions->idx_get(0)->get_Level());
ASSERT_EQ(2, nestedRegions->idx_get(1)->get_Level());
// Get list of fields inside the first top region.
SharedPtr<System::Collections::Generic::IList<SharedPtr<Field>>> fieldList = topRegions->idx_get(0)->get_Fields();
ASSERT_EQ(4, fieldList->get_Count());
SharedPtr<FieldMergeField> startFieldMergeField = nestedRegions->idx_get(0)->get_StartField();
ASSERT_EQ(u"TableStart:NestedRegion1", startFieldMergeField->get_FieldName());
SharedPtr<FieldMergeField> endFieldMergeField = nestedRegions->idx_get(0)->get_EndField();
ASSERT_EQ(u"TableEnd:NestedRegion1", endFieldMergeField->get_FieldName());

◆ GetType()

virtual const System::TypeInfo& Aspose::Words::MailMerging::MailMerge::GetType ( ) const
overridevirtual

Reimplemented from System::Object.

◆ Is()

virtual bool Aspose::Words::MailMerging::MailMerge::Is ( const System::TypeInfo target) const
overridevirtual

Reimplemented from System::Object.

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

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

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.

◆ set_MergeWholeDocument()

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

Sets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.

◆ set_PreserveUnusedTags()

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

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

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

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

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

Sets a value indicating whether lists are restarted at each section after executing of a mail merge.

◆ set_RetainFirstSectionStart()

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

Sets a value indicating whether the SectionStart 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.

◆ set_TrimWhitespaces()

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

◆ set_UnconditionalMergeFieldsAndRegions()

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

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

◆ set_UseNonMergeFields()

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

◆ set_UseWholeParagraphAsRegion()

void Aspose::Words::MailMerging::MailMerge::set_UseWholeParagraphAsRegion ( bool  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.

◆ Type()

static const System::TypeInfo& Aspose::Words::MailMerging::MailMerge::Type ( )
static