{menu:item_ids:code:relation_field:sort_string:type}

Description

Renders a nested HTML navigation menu as a ul of li elements from a tree of items, designed for the Site module Pages slice. Pass the first-level item ids and a code template (usually a link such as _#MENULINK); menu builds the sub-levels by following a parent relation field. Each li gets id="menu-itemid" plus CSS classes inpath (an ancestor of the current page), active (the nearest such ancestor) and xidmatch (the current page itself), so you can style the open branch and the current item. The code is expanded per item with that item bound as the current context; if it resolves to an empty string the item and its whole submenu are skipped, which lets you hide items conditionally. Returns an empty string when code is empty or no valid item id is given. By default only the branch on the path to the current page is expanded; type all expands every level (use all+ to also emit a toggle button on items that have a submenu).

Parameters

item_ids required default (none)

Dash- or space-separated long ids of the items on the first (top) menu level. Usually produced by an {ids:...} lookup that selects the root items of the tree (those whose parent relation is empty). With no valid id the result is an empty string.

code required default (none)

Template printed inside each li, with the menu item bound as the current context. Normally a link such as _#MENULINK or _#HEADLINK. It is fully expanded per item, so you can use field-getters and conditions; if the expansion is an empty string, that item and its whole submenu are skipped, which lets you hide items.

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

Id of the parent relation field that defines the tree: each item points through it to its parent item. menu follows this field downward to build the sub-levels. In the Site module Pages slice this is the Subpage of field.

sort_string optional default (empty - natural order)

Sort order for items within each level, using the same syntax as the sort parameter of {ids:...} (for example number.......... or headline........ , a trailing minus reverses). When empty the items keep their natural order.

type optional default (empty - only the active branch)

Controls how deep the menu is expanded. When empty, only the branch leading to the current page is expanded (the rest stay collapsed). all expands every level. all+ expands every level and adds a toggle button on items that have a submenu, for a click-to-open dynamic menu.

Examples

virtual{menu:{ids:18a352366ea922738348478463536ea5:d-relation........-ISNULL-1:number..........}:_#MENULINK:relation........:number..........:all+}
Expected(the full Pages tree as a nested, collapsible bullet list, roots first)
The typical whole-site menu. {ids:...:d-relation........-ISNULL-1:...} finds the root items (those whose parent relation is empty) and sorts them; menu then builds the rest of the tree from the relation........ field, sorted by number.......... , fully expanded with toggle buttons (all+). Replace the placeholder slice id and the _#MENULINK link alias with your own.
virtual{menu:9e1d2b9f88e3d6c3bf0eb967378610d6:{ifeq:_#HIGHLIGHT:1:_#MENULINK:}:relation........:number..........}
Expected(menu containing only the items where _#HIGHLIGHT is 1)
Because the code is expanded per item and an empty result drops that item (and its submenu), you can hide items from the menu with a condition. Here only items whose highlight field equals 1 are shown; for the rest the code resolves to an empty string and they are skipped.
test[{menu:5726c2c6b035d7aab450d1794e9e90d7:}]
Expected[]
Actual[]
With no code template (the second parameter empty) menu returns an empty string. The code is what fills each li, so without it there is nothing to print.
test[{menu:nosuchitem0000000000000000000000:Home}]
Expected[]
Actual[]
When none of the first-level ids resolve to a real item, menu returns an empty string. Here the id does not exist, so the menu is empty.
virtual{menu:5726c2c6b035d7aab450d1794e9e90d7:Home}
Expected(a bullet list with one item, id menu-5726c2c6..., labelled Home)
Actual
The minimal real menu: one first-level item id and a literal text. menu wraps it in a ul and a li carrying id="menu-<item_id>". The output is HTML, so this example is illustrative.
virtual{menu:5726c2c6b035d7aab450d1794e9e90d7-a65d19971986e750761f0efcd9a16b1b:Page}
Expected(a bullet list with two items, each carrying an id of menu- plus the item id)
Actual
Pass several first-level ids dash-separated. Each becomes its own li at the top level, in the order given (unless you set a sort). Illustrative because the output is HTML.
virtual{menu:5726c2c6b035d7aab450d1794e9e90d7-a65d19971986e750761f0efcd9a16b1b:_#MENULINK}
Expected(a bullet list where each item holds that row's menu-link anchor)
Actual
In a real menu the code is a link. _#MENULINK is the usual alias on a Pages slice that renders an anchor to the item; menu expands it per item with that item bound, so each li holds its own link. Items whose link alias resolves empty are skipped.
virtual{menu:5726c2c6b035d7aab450d1794e9e90d7:_#MENULINK:relation........}
Expected(same menu, sub-levels followed via relation........)
Actual
The third parameter names the parent relation field that defines the tree. Default is relation........ (used here explicitly). On a Pages slice this is the Subpage of field; menu follows it downward to build the sub-levels.
virtual{menu:5726c2c6b035d7aab450d1794e9e90d7:_#MENULINK:relation........:number..........}
Expected(menu with each level ordered by number..........)
Actual
The fourth parameter orders items inside every level, with the same syntax as the sort of {ids:...}. Here number.......... sorts by a numeric ordering field; a trailing minus would reverse it.
virtual{menu:{ids:18a352366ea922738348478463536ea5}:_#MENULINK:relation........:number..........:all}
Expected(a fully expanded nested bullet-list tree, all sub-levels present)
By default only the branch on the path to the current page is expanded. type all renders every level fully, so all sub-menus are present in the HTML. This is the form used for CSS dropdown menus shown or hidden by styling. The slice id here is a placeholder Pages slice.
virtual{menu:{ids:18a352366ea922738348478463536ea5}:_#MENULINK:relation........:number..........:all+}
Expected(fully expanded tree, with an expand toggle on items that have children)
all+ is like all but also adds a toggle button (i.aa-ico-expand) on every item that has a submenu, so visitors can open and close branches by clicking. Use it for an interactive collapsible menu. The slice id here is a placeholder Pages slice.
← All expressions