{sortstring:item_id:relation_field:expression}

Description

Builds a single, lexically sortable key for an item within its relation tree. It walks the branch from the item up to the tree root (via the relation field, same traversal as path and tree), reverses it to root-first order, takes each step ordering value (the short item id by default, or the value of the expression you supply), and encodes each value with the sortid scheme - a length-prefix letter (A for 0 chars, B for 1, C for 2, ...) followed by the value - then concatenates them. Because the prefix encodes length first, the resulting strings sort the same way the numbers/values would sort numerically, so ordering rows by this key reproduces the tree order. An unresolved or empty id yields the bare prefix A (sortid of an empty string). The default relation field is relation........ . Source: AA_Stringexpand_Sortstring in stringexpand.php; cacheable (deterministic).

Parameters

item_id required default (none - required)

Long id of the item whose sort key you want; the key spans from this item up to its tree root. Must be a single, resolvable long id - an empty value raises a fatal error, and an id that matches no active item yields just the bare prefix A. Short ids and dash-joined id lists are not supported here.

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

Field that links each item to its parent, defining the tree to walk. Use the field id, for example relation.......1 for a second relation field.

expression optional default (empty - uses the short item id)

Template evaluated on each item in the branch to produce that step ordering value before it is sortid-encoded; for example a field-getter like {headline........} or an alias. When omitted, the item short id is used. Do not put a literal colon in the expression - it is read as the next parameter separator.

Examples

test{sortstring:5726c2c6b035d7aab450d1794e9e90d7:relation........:_#HEADLINE}

ExpectedFGamma

ActualFGamma

Spelling out the default relation........ alongside the expression. Same result as leaving it empty: FGamma.

test{sortstring:5726c2c6b035d7aab450d1794e9e90d7:relation.......1}

ExpectedF23254

ActualF23254

The second parameter names the parent-link field to walk. Gamma has no value in relation.......1, so the branch is just Gamma itself and the key is unchanged.

virtual{sortstring:c0ffee00000000000000000000000003:relation........:headline........}

Expected(root-first concatenation, e.g. Eintro EguideEpage)

On a real tree where item C0FFEE...03 sits under section ...02 under root ...01, the branch is walked root-first and each headline is sortid-encoded and concatenated - for example Eintro EguideEpage. The key is built so that sibling order on every level is preserved when you sort rows by it. This example is illustrative: the Stable test slice has no parent-link field, so a genuine multi-level key cannot be computed deterministically here. Trap: an empty first parameter ({sortstring:} with no id) raises a fatal error - always pass a resolvable long id. Also avoid a literal colon inside the expression; it is read as the next parameter separator.

test{sortstring:5726c2c6b035d7aab450d1794e9e90d7::_#HEADLINE}

ExpectedFGamma

ActualFGamma

Leave the relation field empty to keep the default relation........, then pass an expression as the third parameter. Here the ordering value is each item headline (alias _#HEADLINE). Gamma headline is Gamma, so the key is sortid of Gamma = FGamma.

test{sortstring:5726c2c6b035d7aab450d1794e9e90d7::headline........}

ExpectedFGamma

ActualFGamma

The expression can be any template. A field-getter headline........ reads the headline of each item in the branch, producing the same FGamma key as the _#HEADLINE alias.

test{sortstring:5726c2c6b035d7aab450d1794e9e90d7}

ExpectedF23254

ActualF23254

With no expression, the ordering value of each step is the item short id. The fixture item Gamma has short id 23254, and sortid encodes a 5-character value with the prefix F, giving F23254. A standalone item with no parent is its own one-step branch.

test{sortstring:00000000000000000000000000000bad}

ExpectedA

ActualA

A long id that matches no active item resolves to an empty short id, and sortid of an empty string is just the length prefix A (zero characters). No fatal, no error - useful to know the command never throws on a missing id.

← All expressions