Creating a Grouped and Nested Document

Introduced in build 4.5

The Grouping Repeat Block

Grouping and Nesting with the WordTemplate object is a modification of existing Repeat Block and Mail Merge functionality used to import multiple rows. Standard repeat blocks and mail merges are not able to display data hierarchically because they cannot be nested. Grouping blocks resolve this problem by allowing you to nest a grouping block within a repeat block or a mail merge document, controlling which data will be repeated for each primary value.

A Grouping block is denoted by a bookmark with a name of the format "group_fieldname" if you use field names in your
merge fields or "groupcolumn_1" if you use ordinal values in your merge fields.

Below is an example of how a repeat block A would look with a grouping block B within it. The repeat block A is a bookmark that can have any name, for example "Repeat". The grouping block B is a bookmark within the "Repeat" bookmark, which has the name "group_primary". When SetRepeatBlock is called on "Repeat", it will be grouped by the field «primary». The header and footer, here colored red, will be repeated for every different value in the field, while the grouping block, here colored black, will be repeated for every row in the data source.

A: [Header «primary»
B: [«first» «second»]
footer]

If you have multiple grouping blocks that group by the same field, you can use a number before the underscore, for example "group1_fieldname" and "group2_fieldname".

Bookmark names are limited in Microsoft Word to fewer than 40 characters and cannot contain special characters – that is, bookmarks can only contain letters, numbers or underscores. If your grouping field name is too long or has ampersands or other special characters, you can use a grouping alias merge field modifier to give your fields nicknames for grouping purposes. For instance, if you want to group by a field called «[Bob&Alice]», you can add a modifier with a new name to be used in grouping: «[Bob&Alice](groupAlias(alias))». You can then group by that column by using a bookmark with the name "group_alias".

How to Group using the Grouping Block

The Grouping block is used to separate headers and footers, which are only repeated for every primary field value, from the parts of the document that are repeated for each row. The header is the section within the repeat block or mail merge before the grouping repeat block, which will be repeated for every value in the primary (grouping) field. The footer is the section within the repeat block or mail merge after the repeat block, which will also be repeated only for each new value in the primary field. Everything within the grouping block, then, is repeated for each new row in the data source. For example, use the following data source:

The following grouping block will group on the first column, including a header for each different value of the first column:

Note that you can only see three bookmark indicators ([ or ]). In Word, if two bookmarks end at the same place, only a single bookmark closed indicator will be shown.

With the outer bookmark named "Repeat" and the inner bookmark named "Groupcolumn_1", the following code can be used to bind data to the grouping block:

The resulting document will look like this:

Grouping with Mail Merges

Hierarchical data can be grouped and nested within Mail Merges as well as Repeat Blocks. The above sample could be created with a Mail Merge by simply deleting the "repeat" bookmark and using the following code to bind data:

The resulting document will be the same, as SetMailMerge will treat the content of the page as if it were a repeat block.

Grouping with the NEXT field

Additionally, NEXT fields are evaluated sequentially within and between grouping blocks. A NEXT field tells WordWriter to move to the next row of the data source, which can be helpful if you wish to use alternating styles using either SetMailMerge or SetRepeatBlock. If you want to alternate styles within a group, place a NEXT field within the grouping block. If you want to alternate styles for each value in the grouped column, you will need to use multiple groups (with names such as group1_Field and group2_Field) with a NEXT block between them.

For example, if I want to add a little color to the previous example, I can add another row to the grouping block, separated by a NEXT field, that is colored blue. If I want to add even more color, I can add another grouping block in red, separated from the first by a NEXT field. The template is shown below with the "Show codes" feature activated so that you can see the NEXT fields:

The output file will look like this:

Grouping in Tables

One common use of Grouping and Nesting functionality is in tables in a Word document. Grouping and Nesting functionality can be used to create a variety of different tables, but two examples are featured below: creating a single table that removes repeated values and creating a new table for each value in a column.

The first example uses the data set above with a template that has a single grouping bookmark, "group_Name", on a row in a table, with the repeat block "repeat" covering the entire row. There is an important distinction to how you create a group on a row, as opposed to a repeat block on a row: to create the group on the row, select all the cells of the row and create the bookmark; to create the repeat block on the row, select the row itself and create the bookmark. Below is a picture of the template, which has a grouping block on all the cells of the row, which ends within the last cell, and a repeat block over the entire row, which ends outside of the table boundary:

When processed using WordTemplate's SetRepeatBlock method, the follow document results:

The next sample uses data derived from the AdventureWorks database. For more details, see the Nested Mail Merge sample.

The following template is used to compose a letter to customers with a new table for each new purchase. The header includes the logo, an address to the customer, and a paragraph explaining the summary of purchases. There are actually two grouping repeat blocks. The first, "group_CustomerId", includes the entire table and the label, "Purchased on «orderdate»", and will be repeated for each value of the CustomerId field. The second, "group_SalesOrderId", includes the inner content of the table and will be repeated for each value of the SalesOrderId field. The outer repeat block, "repeat", includes the entire page.

After binding the template with data, the following document is the result:

Of course, further pages will continue the orders, and a new letter is composed for each customer.