Merge Adjacent Containers Node (Shapes > Merge)

What it does

This node merges adjacent containers within a shape tree into a single container.  It also allows you to explicitly define which child containers are included in the merge operation.

In a shape tree, shapes are the individual content elements, while containers are hierarchical groupings that organize shapes and other containers.

Use it for

• Merging adjacent structure elements that belong to the same visual or logical structure but are split across multiple containers.
• Merging adjacent structure elements that span multiple pages but represent a single logical unit (for example, tables or lists).

How to use it

1. Drag and drop the node from the Node Library into your template:
   Node Library > Folder Shapes > Folder Merge
2. Connect the node with other nodes in the Data Flow of your template.
3. Specify the settings in the Node Properties task pane.

Node Input

Items: Connect a node that provides the shape trees containing the containers to be merged. The node evaluates whether the containers appear in consecutive order in the sequence and merges them according to the defined expressions.

Node Output

Items: Outputs the input items, but with adjacent containers merged when they match the defined expressions.

Node Properties

Node Name

You can assign a custom name to the node to help identify its purpose within your template.

Name Expression

Defines which containers (by name) within the shape trees should be considered for merging. Pre-filtering containers by name improves performance. Additional filtering logic can be defined using the Condition Expression below.

Available variable: 

containerName: name of each container

Expected return type: boolean

Example: 

containerName = "Table"

Only containers named "Table" will be considered for merging.

Condition Expression

Specifies the condition under which two or more containers are considered adjacent and eligible for merging.

Available variables: 

The following variables describe containers within the shape trees of the input list:

• containerName: name of each container
• containerLevel: depth level of the container within the shape trees (zero-based)
• firstContainer: first container at each level within a shape tree (shape items are excluded)
• lastContainer: last container at each level within a shape tree (shape items are excluded)
• containerIndex: zero-based index of the container within its level (shape items are excluded)
• containerCount: total number of containers at the same level within a shape tree (shape items are excluded)

Expected return type: boolean

Example 1: Merge all adjacent containers that match the Name Expression

true

All adjacent containers that also match the Name Expression will be merged into a single container.

Example 2: Merge all adjacent containers on a specific level that match the Name Expression

For example, if you want to merge table containers at level 1 while excluding nested table containers at deeper levels, you can constrain the level within the shape tree.

containerLevel = 1

Only the adjacent containers on level 1 within the shape trees that also match the Name Expression will be merged into a single container.

Example 3: Merge adjacent containers at a specific level and within a defined index range that match the Name Expression

If you want to merge containers with a specific index, it might be useful to also define the level. Otherwise, containers with that index will be merged at each level across the shape tree.

containerLevel = 2 and containerIndex < 4

Only adjacent containers at level 2 with indexes 0 to 3 that also match the Name Expression will be merged into a single container.

Merge Child Expression

Defines which child containers within the containers, as identified by the Name Expression and Condition Expression, should be merged. 

Available variables: 

• containerLevel: depth level of the parent container being merged (zero-based)

These variables describe the direct child containers of the containers being merged:

• childName: name of a direct child container
• firstChild: first direct child container (shape items are excluded)
• lastChild: last direct child container (shape items are excluded)
• childIndex: zero-based index of a direct child container among its siblings (shape items are excluded)
• childCount: total number of direct child containers (shape items are excluded)

Expected return type: boolean

Example 1: Merging several tables with repeating table headers into one

A table is split across several pages, resulting in separate tables that need to be merged into a single table. Each table repeats the header in its first row, but only one header should be retained in the final merged result. 

In the Name Expression and Condition Expression, you have already specified which tables should be merged. The next step is to define which direct children— in this case, the table rows —should be included in the merge.

To exclude the repeated headers from the second and third tables, use the following expression:

firstChild = false

This merges all child containers except the first one. In this example, only the first row (the header row in this example) from the first table will be included in the final result.

Example 2: Merging multiple tables with repeating two-level headers

A table is split across multiple pages, resulting in several separate tables that need to be merged into a single table. Each table contains a two-level header in its first two rows. However, only the header from the first table should be retained in the final merged table.  

In the Name Expression and Condition Expression, you have already specified which tables should be merged. The next step is to define which direct children— in this case, the table rows —should be included in the merge.

To exclude the repeated two-level headers from the subsequent tables, use the following expression:

childIndex < 2 ? false : true

This merges all child containers except the first and second. In this example, only the two-level header from the first table is included in the final merged output.

Max. Depth

Specifies the maximum level (zero-based) within the shape tree hierarchy that the merge operation will traverse. Limiting the traversal depth can improve performance.

Example: 

4

Traverses levels 0 through 4 (inclusive).