...
Introducedin | ||
---|---|---|
|
...
|
Note |
---|
Grouping and Nesting is only available in WordWriter EE. |
Excerpt |
---|
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. h3. |
The
...
Grouping
...
Repeat
...
Block
...
Grouping
...
and
...
Nesting
...
with
...
the
...
WordTemplate
...
object
...
is
...
a
...
modification
...
of
...
existing
...
Repeat
...
Block
...
and
...
...
Merge
...
functionality
...
used
...
to
...
...
...
...
.
...
Standard
...
repeat
...
blocks
...
and
...
...
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
...
...
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:
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 | ||||
---|---|---|---|---|
| ||||
wt.SetRepeatBlock("repeat", data);
{code}
|
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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:
...
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.
Scrollbar |
---|