Sorting hierarchy nodes

By default, nodes in a hierarchy will be shown in the order in which they are added, but you can choose between two ways of sorting your hierarchies:

• Let your users drag and drop nodes to change their location

or

• Specify your own property that will be used for sorting

Hierarchy drag and drop

If you enable the hierarchy drag and drop feature, users will be able to drag nodes to move them within a hierarchy. Without the feature enabled, users will only be able to drag nodes between branches of a hierarchy, not within the same branch.

Archived and unsupported node types

Archived or unsupported nodes will prevent other nodes in the same branch from being reordered with drag and drop. For more information see the User guide - Reordering nodes in the same branch.

In order to enable drag and drop within the same branch, you'll need to add a sort trait to your content type schema with a key of default and a sort path using the new position field in the content item metadata. position will be calculated automatically when the user drags a node to a new position. You cannot combine "/_meta/hierarchy/position" with any other sort paths.

"trait:sortable": {
    "sortBy": [
      {
        "key": "default",
        "paths": ["/_meta/hierarchy/position"]
      }
    ]
  }

The site menu schema example shows how to enable hierarchy drag and drop.

Multiple content types in a hierarchy

The content type schema for each node specified in the childContentTypes array in trait:hierarchy must be enabled for drag and drop.

Hierarchy drag and drop example

The example below shows a hierarchy that has been updated to support the feature. The "Womens" node is dragged to a new position on the same branch, together with its child nodes. The position of the other nodes in the branch (its siblings) is also updated.

Updating your content type schemas

If you have existing content type schemas that you use to create hierarchies and want to update your hierarchies to support drag and drop, you will need to update the schemas as follows:

• Update each schema to include a sort trait and default sort key with the "/_meta/hierarchy/position" sort path.
• Save and sync your updated schemas.
• Once your schemas are updated and you first open a hierarchy, nodes will be initially be sorted in the order that you previously set up, but users will be able to drag and drop nodes to change their position.

The position field for each node in a branch will be initialized the first time you add or drag a node within that branch. Note initialization of a very large branch might take a while.

Updating existing sort keys

If you are using an existing sort trait with the default sort key to sort content using the Filter API, you will need to change the sort to use another key and update your Filter API requests.

Maximum nodes in a hierarchy branch

Note that hierarchy drag and drop is currently supported for branches containing up to 200 nodes.

Defining a custom sort

To define a custom sort order, include trait:sortable in your schema and specify one or more properties to use for sorting in the paths array. The sort order is specified in JSON pointer format.

In this example we will sort the hierarchy tree using the title of each content item. The children of a node will be sorted in ascending order by the title property.

"trait:sortable": {
    "sortBy": [
      {
        "key": "default",
        "paths": ["/title"]
      }
    ]
  }

In the page-hierarchy schema we've included a ranking property that allows the user to control the order in which nodes are sorted. The ranking is included in the sort, so nodes will be sorted in ascending order of ranking and, if the ranking is equal, the title will be used.

"trait:sortable":{
      "sortBy":[
         {
            "key":"default",
            "paths":[
               "/ranking",
               "/title"
            ]
         }
      ]
   }

Related pages

Introducing hierarchies

Creating content type schemas for hierarchies

Working with hierarchies

List, filter and sort content

Hierarchy API

Hierarchies limits