Skip to main content

Combine Node (Shapes > Grouping)

Janne Brönner
  • Updated

What it does

This node combines items into pairs by matching elements from two different input lists based on defined conditions.

The items connected to the Items input port serve as the primary elements. For each of these, the node evaluates whether a suitable match exists in the Candidates input list. If a candidate meets the defined conditions, it is combined with the item to form a group of two. If no suitable match is found, the item remains uncombined.

Use it for

  • Combining items into pairs based on spatial or logical relationships
  • Matching elements across two lists using configurable conditions
  • Creating structured groups (e.g., label + value, icon + text)

How to use it

  1. Drag and drop the node from the Node Library into your template:
    Node Library > Folder Shapes > Folder Grouping
  2. Connect the node with other nodes in the Data Flow of your template. Connect the base items to the Items input port and the potential matches to the Candidates input port.
  3. Specify the settings in the Node Properties task pane.

Node Input

  • Items: Connect a node from the Data Flow containing the base items (shapes or shape trees). These items will be evaluated against candidates based on the defined conditions.
  • Candidates: Connect a node from the Data Flow potential matching items (shapes or shape trees). These will be evaluated for possible combination with the base items.

Node Output

This node provides three outputs, visible in the Node Result task pane:

  • Combined: A list of shape trees, each representing a group of two successfully matched items (one from Items, one from Candidates).
  • Remainder Items: Items from the Items input that could not be matched with any candidate.
  • Remainder Candidates: Candidates that were not matched with any item.

Node Properties

Node Name

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

Group Name

Assign a name to each created group for easier reference in further processing.

Mode

Select how candidate items are processed. This affects performance:

  • Check all combinations
    • Each item is compared with all candidates (top to bottom).
    • The first matching candidate is used.
    • More thorough but slower for large datasets.
  • Check only forward
    • Once a candidate is matched, it is not considered again for previous items.
    • Subsequent items only check candidates further down the list.
    • Significantly improves performance for large lists.
Tip

Use the Sort Horizontally and Sort Vertically nodes to order your items (e.g, top to bottom) before processing. Otherwise, using Check only forward is not recommended.

Search Rectangle Expression

This optional property restricts the search area for Candidates relative to each Item. Limiting the search region can significantly improve performance and is recommended.

You can define one or more rectangles (as a sequence) that specify where candidates should be located relative to the item. Only candidates within these regions will be considered.

Available variables:

  • item: the current item being processed from the Items input list. item has the same properties as a shape tree object.
  • index: the zero-based index of the item in the input list
  • first: the first item in the input list
  • last: the last item in the input list
  • count: the total number of items in the input list

Expected return type: Sequence of rectangles

Example: 

[Rectangle(item.right, item.bottom - 50, item.right + 200, item.top + 2)]

This limits the search area to a rectangle positioned to the right of the item, within a defined vertical range.

Condition Expression

Define the conditions that must be met for a Candidate to be combined with an Item. If no matching candidate is found, the item is added to the Remainder Items output.

Available variables:

  • item: the current item being processed from the Items input list. item has the same properties as a shape tree object.
  • candidate: the current item being processed from the Candidates input list. candidate has the same properties as a shape tree object.
  • index: the zero-based index of the item in the input list
  • first: the first item in the input list
  • last: the last item in the input list
  • count: the total number of items in the input list

Expected return type: boolean

Example: 

item.top = candidate.top

This matches the first candidate whose top coordinate equals that of the item.