{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 (the current page and its ancestors), xidmatch (the current page) and active (the deepest inpath entry - the current page when it is listed, otherwise its nearest listed ancestor), so you can style the open branch and the current item. Aliases in the code are expanded per item with that item bound as the current context (a brace command must be deferred to run per item, see the hiding example); 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-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. Aliases such as _#MENULINK are expanded per item; wrap any brace command (a field-getter or a condition) in the curly-brace-plus-parenthesis deferral, as in the hiding example, or it runs once for the whole page; 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.
test{safe:{menu:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-5726c2c6b035d7aab450d1794e9e90d7:{({ifeq:{headline........}:Beta::{headline........}})}}}
Expected<ul> <li id="menu-a65d19971986e750761f0efcd9a16b1b">Alpha</li> <li id="menu-5726c2c6b035d7aab450d1794e9e90d7">Gamma</li> </ul>
Actual<ul> <li id="menu-a65d19971986e750761f0efcd9a16b1b">Alpha</li> <li id="menu-5726c2c6b035d7aab450d1794e9e90d7">Gamma</li> </ul>
An item whose code expands to nothing gets no li, so a condition in the code hides items. The condition must be deferred (the curly brace plus parenthesis wrapper in the code) so it runs once per menu item: here ifeq returns nothing for Beta, so only Alpha and Gamma are listed. Without the deferral ifeq would run once in the page context, before menu starts, and hide nothing. In a Pages slice the same pattern hides items whose highlight flag is off: ifeq on _#HIGHLIGHT returning _#MENULINK.
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.
test{safe:{menu:5726c2c6b035d7aab450d1794e9e90d7:Home}}
Expected<ul> <li id="menu-5726c2c6b035d7aab450d1794e9e90d7">Home</li> </ul>
Actual<ul> <li id="menu-5726c2c6b035d7aab450d1794e9e90d7">Home</li> </ul>
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>". Wrapped in safe so the page shows the generated markup as text; in a template write just the menu command.
test{safe:{menu:5726c2c6b035d7aab450d1794e9e90d7-a65d19971986e750761f0efcd9a16b1b:Page}}
Expected<ul> <li id="menu-5726c2c6b035d7aab450d1794e9e90d7">Page</li> <li id="menu-a65d19971986e750761f0efcd9a16b1b">Page</li> </ul>
Actual<ul> <li id="menu-5726c2c6b035d7aab450d1794e9e90d7">Page</li> <li id="menu-a65d19971986e750761f0efcd9a16b1b">Page</li> </ul>
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). Wrapped in safe so the page shows the generated markup as text.
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.