Merging Table Cells Dynamically

What is this page about?

This page explains how to merge table cells dynamically during document generation using template logic.

You can merge table cells with equal textual contents within your reports dynamically using cellMerge tags. The syntax of a cellMerge tag is defined as follows.

<<cellMerge>>

By default, a cellMerge tag causes a cell merging operation only in a vertical direction during runtime. However, you can alter this behavior in the following ways:

To merge cells only in a horizontal direction, use the horz switch as follows.
```
<<cellMerge -horz>>
```
To merge cells in both – vertical and horizontal – directions, use the both switch as follows.
```
<<cellMerge -both>>
```

For two or more successive table cells to be merged dynamically in either direction by the engine, the following requirements must be met:

Each of the cells must contain a cellMerge tag denoting a cell merging operation in the same direction.
Each of the cells must not be already merged in another direction. This requirement does not apply when a both switch is used.
The cells must have equal textual contents ignoring leading and trailing whitespaces.

Consider the following template.

...	...	...
...	<<cellMerge>><<[value1]>>	...
...	<<cellMerge>><<[value2]>>	...
...	...	...

If value1 and value2 have the same value, say “Hello”, table cells containing cellMerge tags are successfully merged during runtime and a result report looks as follows then.

...	...	...
...	Hello	...
...	Hello	...
...	...	...

If value1 and value2 have different values, say “Hello” and “World”, table cells containing cellMerge tags are not merged during runtime and a result report looks as follows then.

...	...	...
...	Hello	...
...	World	...
...	...	...

Note – A cellMerge tag can be normally used within a table data band.

You can define an additional restriction on dynamic merging of table cells by providing an expression for a cellMerge tag using the following syntax.

<<cellMerge [expression]>>

During runtime, expressions defined for cellMerge tags are evaluated and dynamic cell merging is discarded for those tags, which expressions return unequal values, even if all other conditions for merging such as equal cell textual contents are met. In particular, this feature is useful when cells corresponding to different data band sequence elements should not be merged as shown in the following example.

Assume that you have the Invoice and InvoiceItem classes defined in your application as follows.

public class Invoice
{
	public int Number { get { ... } }
	public IEnumerable<InvoiceItem> Items { get { ... } }
	...
}

public class InvoiceItem
{
	public String Ware { get { ... } }
	public String Pack { get { ... } }
	public int Quantity { get { ... } }
	...
}

Given that invoices is an enumeration of Invoice instances, you could use the following template to output information on several invoices in one table.

#	Ware	Pack	Quantity
<<foreach [invoice in invoices]>><<foreach [item in invoice.Items]>><<[invoice.Number]>><<cellMerge>>	<<[item.Ware]>><<cellMerge>>	<<[item.Pack]>>	<<[item.Quantity]>><</foreach>><</foreach>>

A result document would look as follows then.

#	Ware	Pack	Quantity
11342	Natural Mineral Water	Bottle 1.0 L	30
11342		Bottle 0.5 L	50
15385		Bottle 1.0 L	110

That is, cells corresponding to the same wares at different invoices would be merged, which is unwanted. To prevent this from happening, you can use the following template instead.

#	Ware	Pack	Quantity
<<foreach [invoice in invoices]>><<foreach [item in invoice.Items]>><<[invoice.Number]>><<cellMerge>>	<<[item.Ware]>><<cellMerge [invoice.IndexOf()]>>	<<[item.Pack]>>	<<[item.Quantity]>><</foreach>><</foreach>>

Then, a result document looks as follows.

#	Ware	Pack	Quantity
11342	Natural Mineral Water	Bottle 1.0 L	30
11342	Natural Mineral Water	Bottle 0.5 L	50
15385	Natural Mineral Water	Bottle 1.0 L	110

Note – You could use <<cellMerge [invoice.Number]>> instead of <<cellMerge [invoice.IndexOf()]>> to get the same effect, but using of IndexOf() is a more generic approach.

FAQ

Q: How do I merge table cells horizontally using the cellMerge tag?
A: Place the <<cellMerge -horz>> tag in each cell that should be merged horizontally. All involved cells must contain the tag, have the same text (ignoring surrounding whitespace), and must not be merged in another direction already.
Q: Which tag should I use to merge cells both vertically and horizontally?
A: Use the <<cellMerge -both>> switch. This tells the engine to consider merging in both directions, provided the usual content‑equality rules are satisfied.
Q: What are the mandatory conditions for dynamic cell merging to occur?
A: The cells must (a) contain a cellMerge tag with the same direction, (b) not be pre‑merged in a conflicting direction (unless the -both switch is used), and (c) have identical textual content after trimming leading and trailing spaces.
Q: How can I prevent cells with identical text from merging when they belong to different data groups?
A: Add an expression to the tag, e.g., <<cellMerge [invoice.IndexOf()]>>. The expression evaluates to a different value for each group, causing the engine to skip merging even if the visible text matches.
Q: Can the cellMerge tag be used inside a table data band?
A: Yes. The tag works normally within a data band; the engine evaluates it at runtime for each row generated by the band.

Setting Background Color Dynamically in C# Restarting List Numbering Dynamically in C#