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 (const ArrayPtr< String > &fieldNames, const ArrayPtr< SharedPtr< Object > > &values)
	Performs a mail merge operation for a single record. More...

void	Execute (const SharedPtr< IMailMergeDataSource > &dataSource)
	Performs a mail merge from a custom data source. More...

void	ExecuteWithRegions (const SharedPtr< IMailMergeDataSource > &dataSource)
	Performs a mail merge from a custom data source with mail merge regions. More...

void	ExecuteWithRegions (const 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...

const SharedPtr< IFieldMergingCallback > &	get_FieldMergingCallback () const
	Occurs during mail merge when a mail merge field is encountered in the document. More...

const SharedPtr< IMailMergeCallback > &	get_MailMergeCallback () const
	Allows to handle particular events during mail merge. More...

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

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

ArrayPtr< String >	GetFieldNamesForRegion (const String &regionName, int32_t regionIndex)
	Returns a collection of mail merge field names available in the region. More...

SharedPtr< IList< SharedPtr< MailMergeRegionInfo > > >	GetRegionsByName (const String &regionName)
	Returns a collection of mail merge regions with the specified name. More...

SharedPtr< MailMergeRegionInfo >	GetRegionsHierarchy ()
	Returns a full hierarchy of regions (with fields) available in the document. More...

virtual const TypeInfo &	GetType () 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 (const SharedPtr< IFieldMergingCallback > &value)
	Setter for get_FieldMergingCallback. More...

void	set_MailMergeCallback (const 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 (const String &value)
	Setter for get_RegionEndTag. More...

void	set_RegionStartTag (const String &value)
	Setter for get_RegionStartTag. More...

void	set_RestartListsAtEachSection (bool value)
	Setter for get_RestartListsAtEachSection. 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 TypeInfo &	Type ()

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	(	const System::ArrayPtr< System::String > &	fieldNames,
		const 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

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.

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>(get_ImageUrl()), 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 ( const 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

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

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

dataSourceRoot An 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
    {
        throw System::NotImplementedException();
    }
 
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()

const 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
{
private:
    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()

const 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 inside the existing region, which will make it a parent.
// Now a "Column2" field will be inside a new region.
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), false);
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), true);
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());
// Check that the second region now has a parent region.
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(1)->get_ParentRegion()->get_Name());
 
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
 
ASSERT_EQ(u"Column2", 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 inside the existing region, which will make it a parent.
// Now a "Column2" field will be inside a new region.
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), false);
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), true);
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());
// Check that the second region now has a parent region.
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(1)->get_ParentRegion()->get_Name());
 
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
 
ASSERT_EQ(u"Column2", mergeFieldNames[0]);

◆ get_RestartListsAtEachSection()

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

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

Examples

Shows how to control whether or not list numbering is restarted at each section when mail merge is performed.

auto doc = MakeObject<Document>(MyDir + u"Section breaks with numbering.docx");
 
doc->get_MailMerge()->set_RestartListsAtEachSection(false);
doc->get_MailMerge()->Execute(MakeArray<String>(0), MakeArray<SharedPtr<System::Object>>(0));
 
doc->Save(ArtifactsDir + u"MailMerge.RestartListsAtEachSection.pdf");

◆ 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 ( const 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).

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 inside the existing region, which will make it a parent.
// Now a "Column2" field will be inside a new region.
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), false);
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), true);
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());
// Check that the second region now has a parent region.
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(1)->get_ParentRegion()->get_Name());
 
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
 
ASSERT_EQ(u"Column2", mergeFieldNames[0]);

◆ GetFieldNamesForRegion() [2/2]

System::ArrayPtr< System::String > Aspose::Words::MailMerging::MailMerge::GetFieldNamesForRegion	(	const 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).

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 inside the existing region, which will make it a parent.
// Now a "Column2" field will be inside a new region.
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), false);
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), true);
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());
// Check that the second region now has a parent region.
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(1)->get_ParentRegion()->get_Name());
 
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
 
ASSERT_EQ(u"Column2", mergeFieldNames[0]);

◆ GetRegionsByName()

System::SharedPtr< System::Collections::Generic::IList< System::SharedPtr< Aspose::Words::MailMerging::MailMergeRegionInfo > > > Aspose::Words::MailMerging::MailMerge::GetRegionsByName ( const 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.

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 inside the existing region, which will make it a parent.
// Now a "Column2" field will be inside a new region.
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), false);
builder->InsertField(u" MERGEFIELD TableStart:MailMergeRegion1");
builder->MoveToField(regions->idx_get(0)->get_Fields()->idx_get(1), true);
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());
// Check that the second region now has a parent region.
ASSERT_EQ(u"MailMergeRegion1", regions->idx_get(1)->get_ParentRegion()->get_Name());
 
mergeFieldNames = doc->get_MailMerge()->GetFieldNamesForRegion(u"MailMergeRegion1", 1);
 
ASSERT_EQ(u"Column2", 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 )

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

◆ set_FieldMergingCallback()

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

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

◆ set_MailMergeCallback()

void Aspose::Words::MailMerging::MailMerge::set_MailMergeCallback ( const 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 ( const System::String & value )

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

◆ set_RegionStartTag()

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

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

◆ set_RestartListsAtEachSection()

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

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

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

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

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

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

◆ 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

Detailed Description

Public Member Functions

Static Public Member Functions

Member Function Documentation

◆ DeleteFields()

◆ Execute() [1/2]

◆ Execute() [2/2]

◆ ExecuteWithRegions() [1/2]

◆ ExecuteWithRegions() [2/2]

◆ get_CleanupOptions()

◆ get_CleanupParagraphsWithPunctuationMarks()

◆ get_FieldMergingCallback()

◆ get_MailMergeCallback()

◆ get_MappedDataFields()

◆ get_MergeDuplicateRegions()

◆ get_MergeWholeDocument()

◆ get_PreserveUnusedTags()

◆ get_RegionEndTag()

◆ get_RegionStartTag()

◆ get_RestartListsAtEachSection()

◆ get_RetainFirstSectionStart()

◆ get_TrimWhitespaces()

◆ get_UnconditionalMergeFieldsAndRegions()

◆ get_UseNonMergeFields()

◆ get_UseWholeParagraphAsRegion()

◆ GetFieldNames()

◆ GetFieldNamesForRegion() [1/2]

◆ GetFieldNamesForRegion() [2/2]

◆ GetRegionsByName()

◆ GetRegionsHierarchy()

◆ GetType()

◆ Is()

◆ set_CleanupOptions()

◆ set_CleanupParagraphsWithPunctuationMarks()

◆ set_FieldMergingCallback()

◆ set_MailMergeCallback()

◆ set_MergeDuplicateRegions()

◆ set_MergeWholeDocument()

◆ set_PreserveUnusedTags()

◆ set_RegionEndTag()

◆ set_RegionStartTag()

◆ set_RestartListsAtEachSection()

◆ set_RetainFirstSectionStart()

◆ set_TrimWhitespaces()

◆ set_UnconditionalMergeFieldsAndRegions()

◆ set_UseNonMergeFields()

◆ set_UseWholeParagraphAsRegion()

◆ Type()