Merging Table Cells Dynamically

You can merge table cells with equal textual contents within your reports dynamically using cellMerge tags. 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	...
...		...
...	...	...

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 getNumber() { ... }
	public Iterable<InvoiceItem> getItems() { ... }
	...
}
public class InvoiceItem
{
	public String getWare() { ... }
	public String getPack() { ... }
	public int getQuantity() { ... }
	...
}

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.getItems()]>><<[invoice.getNumber()]>><<cellMerge>>	<<[item.getWare()]>><<cellMerge>>	<<[item.getPack()]>>	<<[item.getQuantity()]>><</foreach>><</foreach>>

A result document would look as follows then.

#	Ware	Pack	Quantity
11342	Natural Mineral Water	Bottle 1.0 L	30
		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.getItems()]>><<[invoice.getNumber()]>><<cellMerge>>	<<[item.getWare()]>><<cellMerge [invoice.indexOf()]>>	<<[item.getPack()]>>	<<[item.getQuantity()]>><</foreach>><</foreach>>

Then, a result document looks as follows.

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

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

---

FAQ

1. Q: How do I merge cells only horizontally with a cellMerge tag?
   A: Add the -horz switch to the tag: <<cellMerge -horz>>. This tells the engine to merge successive cells in the same row when their textual contents match.

2. Q: Can a single cellMerge tag merge cells both vertically and horizontally?
   A: Yes. Use the -both switch: <<cellMerge -both>>. The engine will attempt to merge cells in both directions, provided all merging requirements are satisfied.

3. Q: What conditions must be met for cells to merge dynamically?
   A: (a) Each cell must contain a cellMerge tag with the same direction switch. (b) Cells must not already be part of another merge in a conflicting direction (unless -both is used). (c) The textual content of the cells must be identical after trimming leading/trailing whitespace.

4. Q: How can I prevent cells from merging across different data items, such as different invoices?
   A: Supply an expression to the cellMerge tag that evaluates differently for each data group, e.g., <<cellMerge [invoice.indexOf()]>>. The engine will only merge cells when the expression returns equal values.

5. Q: Is it safe to use cellMerge tags inside a table data band?
   A: Yes. cellMerge tags are designed to work inside table data bands and will be processed during the rendering of each band iteration.