{treestring:item_ids:relation_field:reverse:sort_string:slices}

Description

Builds a text representation of an item tree rooted at the given item and returns it as a string of long item IDs. Children are wrapped in parentheses after their parent and siblings are joined with a hyphen, so a parent A with children B and C prints as A(B-C), and nesting deepens with each level: A(B(D)-C). An item with no children prints as just its own ID. The tree is walked through a relation field: each item points (by default through the relation........ field) at its child items; set reverse to 1 to walk the opposite direction (each item points at its parent), which builds the subtree of descendants under the starting item. The output is not meant to be read directly - it is the tree string that {itree:...} consumes to render a nested menu, breadcrumb, or sitemap. Pass several root IDs joined with a hyphen to get several trees in one string. Only active items in the listed slices are included; IDs that match no active item are echoed back unchanged. treestring is cacheable, so its output is deterministic for a given tree.

Parameters

item_ids required default (none)

Long ID (or several IDs joined with a hyphen) of the item(s) at the root of the tree. Short IDs work only inside an item context; in a standalone expression use full 32-character long IDs. With no value the result is empty.

relation_field optional default relation........

The relation field whose values link an item to the next level of the tree. By default each item points at its child items through this field.

reverse optional default (empty - forward tree)

Set to 1 to walk the tree in the opposite direction: each item points at its parent, so the result is the subtree of descendants under item_ids. A reverse tree is limited to the slice of the starting item. Leave empty for a normal parent-to-child tree.

sort_string optional default (empty - default order)

Orders the tree leaves. Either a single field ID, or a sort string such as sort[0][headline........]=a&sort[1][publish_date....]=d (a = ascending, d = descending). Currently takes effect only for reverse trees.

slices optional default (empty - all slices)

Restrict the walk to the listed slice IDs (joined with a hyphen). Items in any other slice are skipped, which is useful when a tree spans several slices and you want only one subtree. Empty means all slices are followed.

Examples

test{treestring:5726c2c6b035d7aab450d1794e9e90d7}
Expected5726c2c6b035d7aab450d1794e9e90d7
Actual5726c2c6b035d7aab450d1794e9e90d7
An item with no children in the relation field is its own one-node tree, so treestring returns just that long ID. This Stable fixture item has no child relations.
test{treestring:5726c2c6b035d7aab450d1794e9e90d7-4f3362a62847fe1f8c59ba28a92d42c0}
Expected5726c2c6b035d7aab450d1794e9e90d7-4f3362a62847fe1f8c59ba28a92d42c0
Actual5726c2c6b035d7aab450d1794e9e90d7-4f3362a62847fe1f8c59ba28a92d42c0
Join several root IDs with a hyphen to get several trees in one call. Each root that has no children contributes only its own ID, so the result is the two IDs joined by a hyphen.
test{treestring:5726c2c6b035d7aab450d1794e9e90d7:relation.......1}
Expected5726c2c6b035d7aab450d1794e9e90d7
Actual5726c2c6b035d7aab450d1794e9e90d7
The second argument names the relation field to walk. Here the item has no value in relation.......1, so the tree is just the root.
test[{treestring:}]
Expected[]
Actual[]
With no item ID the result is the empty string (shown here between brackets). treestring guards the empty case and does not error.
test{treestring:c0ffeec0ffeec0ffeec0ffeec0ffee00}
Expectedc0ffeec0ffeec0ffeec0ffeec0ffee00
Actualc0ffeec0ffeec0ffeec0ffeec0ffee00
treestring does not check that the root exists. An ID with no matching active item is echoed back unchanged as a single-node tree.
test{treestring:c0ffeec0ffeec0ffeec0ffeec0ffee00:relation........:1}
Expectedc0ffeec0ffeec0ffeec0ffeec0ffee00
Actualc0ffeec0ffeec0ffeec0ffeec0ffee00
Set the third argument to 1 to walk the tree from child to parent and collect the descendants under the root. A reverse tree is limited to the slice of the starting item. Here the root ID matches no item, so the result is just that ID and nothing is walked.
test{itree:{treestring:5726c2c6b035d7aab450d1794e9e90d7}::_#HEADLINE::}
ExpectedGamma
ActualGamma
The usual job of treestring is to hand a tree to itree, which renders each node. Here the one-node tree of the fixture item is rendered as its headline. Note: itree reads the node fields with the _#ALIAS form, not field getters.
test{itree:{treestring:5726c2c6b035d7aab450d1794e9e90d7-4f3362a62847fe1f8c59ba28a92d42c0-ae1da231f3e5bc16496834a0711aa042}::_#HEADLINE:, :}
ExpectedGamma, Beta, Kappa
ActualGamma, Beta, Kappa
The everyday job of treestring is to hand a tree to itree, which renders each node. Three root IDs joined with hyphens become three one-node trees and itree prints each headline, joined by the delimiter. In a real site the roots come from a query and the relation field gives the menu its nesting - see the itree page for the breadcrumb and nested-menu patterns.
← All expressions