Sort by Reference Node (Shapes > Sort)

What it does

This node sorts items based on their position relative to a reference item or group of reference items, or based on a custom criterion such as the page number. It enables flexible and context-aware sorting.

Use it for

• Sorting items by their spatial relationship to a reference.
• Common use cases include:
  • Sorting content by page in multi-page documents, for example before sorting multi-column content within each page.
  • Sorting multi-column content by reference items such as headings or separating lines.
  • Sorting table content by column lines or header shapes that define column boundaries.

How to use it

1. Drag and drop the node from the Node Library into your template:
   Node Library > Folder Shapes > Folder Sort
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 outputs the items you want to sort.
• Ranges (Optional): If you're using another sort node before this one, you can connect its Equality Ranges output to preserve existing groupings into ranges during sorting.
• References (Optional): Connect a node that provides the reference items used to determine the sorting order. If you sort items using only the Criterion Expression, you don't need to connect reference items.

Node Output

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

• Sorted Items: Outputs the list of items sorted according to their position relative to the reference items.
• Equality Ranges: Outputs the ranges used during sorting. These ranges help identify items that are close to the same reference point. You can view the output in the Node Result task pane:
  • Start column: Index of the first item in the range.
  • Length column: Number of items in the range.

You can connect the Equality Ranges output port to the Ranges input port of another sort node. This ensures that items already grouped into ranges are not re-sorted globally.

Node Properties

Node Name

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

Criterion Expression

Defines the value used to compare items during sorting. It is possible to sort items using this expression alone—without connecting reference items or using a Reference Match Expression. See the Example 1: sorting items by page below.

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: double

Reference Match Expression

Indicates which properties of the reference items are relevant for each item being sorted. Connecting reference items to the Reference input is optional, so this expression is also optional. You can sort items using only the Criterion Expression if desired.

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

Equality Threshold

Sets the maximum distance (in points) between items for them to be considered part of the same range.
This helps preserve relative positioning when sorting items that are visually aligned.

Default: 0,200

Examples

Example 1: sorting items by page

You have a multi-page document with a multi-column layout. To get the correct reading order, you first sort all shape trees by the page they're on, then sort the shape trees within each page. Otherwise, shape trees from different pages could be mixed together.

For this, you use the Sort by Reference node with a Criterion Expression only. No reference items are needed.

Criterion Expression

item.pages[0].index

This expression uses the page index of each shape tree as the sorting criterion. The index of the first page the shape tree appears on is used. All shape trees are sorted by page.

Reference Match Expression

Leave this expression empty.

Example 2: sorting table text by column backgrounds

You want to sort the text items in a table by their corresponding columns. Each column is visually defined by a rectangular background shape (e.g., a shaded header cell). These rectangles serve as reference items, and you use a node containing all the horizontally sorted column background rectangles as input.

Criterion Expression

reference.left

This expression uses the left edge of each reference item (in this case, the rectangles) as the sorting criterion.

Reference Match Expression

item.left > reference.left and
item.left < reference.right

An item is matched to a reference when its left edge lies between the left and right edges of the reference rectangle. This means the item is located within the horizontal bounds of a column and will be sorted accordingly.