Filter by Reference Node (Shapes > Filter)

What it does

This node filters shape trees by evaluating them against conditions that can include comparisons with reference items. You can define filters based on properties such as Unicode text, position, item name, or index, and compare each item with one or more reference items. By using reference items as context, the node enables filtering decisions based not only on an item’s own properties but also on how it relates to other elements.

Items that match the filter expression are sent to one output, while non-matching items are sent to a separate output.

Use it for

• Comparing shape trees with other shape trees (reference items) to identify matches or relationships.
• Filtering specific shape trees that cannot be selected using the Select Shapes or Select Shapes by Reference nodes due to lack of distinctive formatting.
• Filtering based on relative properties, such as position or text, including support for regular expressions.
• Performing layout-aware filtering where the spatial or structural context is important.
• Identifying text shapes that can only be distinguished dynamically through surrounding layout elements, such as text within tables or text boxes.

How to use it

1. Drag and drop the node from the Node Library into your template:
   Node Library > Folder Shapes > Folder Filter
2. Connect the node with other nodes in the Data Flow of your template. Connect the items you want to filter to the Items input port and the reference elements to the Reference input port.
3. 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 filtered. These are analyzed based on the configured expressions.
• Reference: Connect a node from the Data Flow containing reference items (shapes or shape trees). These reference items can be used in the filter expression to compare and distinguish which items should be filtered.

Node Output

• Filtered Items: Shape trees that match the filter expression.
• Unfiltered Items: Shape trees that do not match the filter expression.

Node Properties

Node Name

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

Filter matches

Specify whether the Filter Expression must match at least one reference or all references in the input list for the filter to apply.

• At least one reference: the Filter Expression must match any reference
• All references – the Filter Expression must match every reference

Filter Expression

Define the condition used to filter shape trees. The expression is evaluated for each item and can include comparisons with reference items.

Available variables:

• item: the current item being processed from the input list. item has the same properties as a shape tree object.
• reference: the reference item from the References input list. reference 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 1: Filtering items inside the coordinates of reference items

item.docBBox inside reference.docBBox

Filters shape trees that are positioned inside the reference items. Useful for example, for filtering text inside a table or a text box. The layout structure of the tables or text boxes would be connected to the reference port.

Example 2: Filtering items outside the coordinates of reference items

item.docBBox not inside reference.docBBox

Filters shape trees that are located outside the boundaries of the reference items. This is useful, for example, for extracting text that lies outside elements such as tables or text boxes, where the layout structure is provided via the References input.

Example 3: Filtering items that overlap reference items

item.docBBox intersects reference.docBBox

Filters shape trees that are overlapping the rectangle of the reference items.

Example 4: Filtering items below a reference element

item.top > reference.bottom

Filters all items that are positioned below a reference item on the page.