Mail Merge with Regions

You can create different regions in your template to have special areas that you can simply fill with your data. Use the Mail Merge with regions if you want to insert tables, rows with repeating data to make your documents dynamically grow by specifying those regions within your template.

You can create nested (child) regions as well as merge regions. The main advantage of using this type is to dynamically increase parts inside a document. See more details in the next article “Nested Mail Merge with Regions”.

How to Execute Mail Merge with Regions

A Mail Merge region is a specific part inside a document that has a start point and an end point. Both points are represented as Mail Merge fields that have specific names “TableStart:XXX” and “TableEnd:XXX”. All content that is included in a Mail Merge region will automatically be repeated for every record in the data source.

Aspose.Words allows you to execute Mail Merge with regions using one of the ExecuteWithRegions methods that accept IMailMergeDataSource custom data source.

The following code example shows how to execute Mail Merge with regions from sqlite database with SQLiteCpp:

You can notice the difference between the document before executing Mail Merge with regions:

mail_merge_with_regions_template

And after executing Mail Merge with regions:

mail_merge_with_regions_execute

Limitations of Mail Merge with Regions

There are some important points that you need to consider when performing a Mail Merge with regions:

  • The start point TableStart:Orders and the end point TableEnd:Orders both need to be in the same row or cell. For example, if you start a merge region in a cell of a table, you must end the merge region in the same row as the first cell.
    The merge field name must match the column name in your DataTable. Unless you specify mapped fields, Mail Merge with regions will not succeed for any merge field that has a name other than the column name.
  • Aspose.Words for C++ only supports IMailMergeDataSource and IMailMergeDataSourceRoot based data sources. Unlike .NET and Java, C++ does not have a generally accepted cross‑platform API for working with databases (like ADODB, ODBC, or JDBC). In order to work with a specific data source, you have to implement IMailMergeDataSource or IMailMergeDataSourceRoot interface.

If one of these rules is broken, you will get unexpected results or an exception may be thrown.

FAQ

  1. Q: How do I implement a custom IMailMergeDataSource in C++?
    A: Create a class that inherits from Aspose::Words::MailMerging::IMailMergeDataSource and implement the required members: GetValue, MoveNext, GetChildDataSource, and GetRecordCount. In GetValue return the field value for the current record, and in MoveNext advance to the next record. Register the data source with MailMerge::ExecuteWithRegions.

  2. Q: Can I use nested mail‑merge regions, and how are they defined?
    A: Yes. Define inner regions with their own TableStart:ChildRegion and TableEnd:ChildRegion fields inside the outer region. When executing, the outer region’s data source must provide a child data source (via GetChildDataSource) for each record to populate the inner region.

  3. Q: What happens if the start and end merge fields of a region are not in the same row or cell?
    A: Aspose.Words will throw an ArgumentException or produce malformed output because the region boundaries must be within a single row or cell. Ensure both TableStart and TableEnd tags are placed in the same table row or cell.

  4. Q: Do the merge field names have to match the column names in my data source?
    A: By default, yes. The field name in the document must exactly match a column name returned by GetValue. If you need different names, use MailMerge::ExecuteWithRegions overload that accepts a field‑mapping dictionary.

  5. Q: Is it possible to use a DataTable directly with ExecuteWithRegions in C++?
    A: No. Unlike .NET, the C++ API does not provide a built‑in DataTable implementation. You must wrap your tabular data in a custom class that implements IMailMergeDataSource (or use IMailMergeDataSourceRoot for hierarchical data).

Simple Mail Merge Operation in C++ Nested Mail Merge with Regions in C++