Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

Introducedin
4.5

...

4.5
Note

Grouping and Nesting is only available in WordWriter EE.

Beginning in version 4.5,

...

the

...

WordTemplate

...

object

...

includes

...

support

...

for

...

nested

...

bookmarks

...

with

...

Office

...

Open

...

XML

...

documents

...

(.docx,

...

.docm,

...

.dotx,

...

and

...

.dotm)

...

in

...

WordWriter

...

Enterprise

...

Edition.

...

Nested

...

bookmarks

...

can

...

be

...

used

...

to

...

format

...

and

...

display

...

hierarchical

...

data.

...

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:

Name

Purchase

Quantity

Frank

Football

3

Frank

Basketball

3

Frank

Athletic Shorts

2

Frank

Athletic Shirt

2

Frank

Football Cleats

1

Frank

Basketball Hi-Tops

1

Stephanie

Basketball

2

Stephanie

Athletic Shorts

2

Stephanie

Athletic Shirt

1

Stephanie

Basketball Hi-Tops

1

Ian

Football

3

Ian

Basketball

3

Ian

Athletic Shorts

2

Ian

Athletic Shirt

2

Ian

Football Cleats

1

Ian

Basketball Hi-Tops

1

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

Image Added

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:

Code Block
csharp
csharp
wt.SetRepeatBlock("repeat", data);
{code}

The

...

resulting

...

document

...

will

...

look

...

like

...

this:

...

Image Added

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:

Code Block
csharp
csharp
wt.SetMailMerge(data);
{code}

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:

...

Image Added

The output file will look like this:

Image Added

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:

...

Image Added

When processed using WordTemplate's

...

SetRepeatBlock

...

method,

...

the

...

follow

...

document

...

results:

...

Image Added

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.

...

Image Added

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

Image Added

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

Scrollbar