What it does
This node groups items by using reference elements to determine group boundaries.
Use it for
- Grouping items based on layout references.
- Common use case: Grouping lines of list items using list bullets as reference points. Especially useful when list items are not visually separated by spacing.
How to use it
- Drag and drop the node from the Node Library into your template:
Node Library > Folder Shapes > Folder Grouping - Connect the node with other nodes in the Data Flow of your template. Connect the items you want to group to the Items input port and the reference items to the Reference input port.
- Specify the settings in the Node Properties task pane.
Node Input
- Items: Connect a node from the Data Flow containing the items (shapes or shape trees) to be grouped. These are analyzed based on the configured expressions.
- Reference: Connect a node from the Data Flow containing reference items (shapes or shape trees), such as layout elements that define group boundaries.
Node Output
This node provides two outputs, visible in the Node Result task pane:
- Groups: A list of shape trees, each representing a detected group containing grouped items.
- Remainder: A list of items that were not grouped because they didn’t 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.
Group Name
Assign a name to each generated group for easier reference in further processing.
Match Expression
Defines the condition under which an item is considered part of a group relative to a reference item.
Available variables:
-
item: the current item being processed from the input list.itemhas the same properties as a shape tree object. -
reference: the reference item from the References input list.referencehas 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: Grouping lines of list items based on bullet points
When grouping lines of list items based on bullet points, lines are considered part of a list item if they are positioned below the bullet and within approximately 12 points horizontally:
item.left _ reference.right inside 12.0 ~ 0.1 and item.top < reference.top
Checks if the left edge of the item (line) is within 12 points (±0.1 tolerance) of the right edge of the reference item (bullet point). Also ensures the item (line) is positioned above the reference item (bullet point).
Weight Expression
Defines the priority of a match between an item and a reference. Used to resolve ambiguities when multiple matches are possible.
The expression must evaluate to a double value. Lower values indicate higher priority, and the match with the smallest value is selected.
Available variables:
-
item: the current item being processed from the Item input list.itemhas the same properties as a shape tree object. -
reference: the reference item from the References input list.referencehas 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: double
Example: Grouping lines of list items based on bullet points
When grouping lines of list items based on bullet points, each line is assigned to the group of the nearest bullet. Only the closest lines below each bullet are grouped, ensuring that lines belonging to other bullets are not incorrectly included:
item.top - reference.top
Calculates the vertical distance between the top edge of the item (line) and the top edge of the reference (bullet point). Smaller values indicate closer alignment, which may be preferred for grouping.