menu
Audit
- Macro ID
- menu
- Source
- XS
- Type
- Wrapper
- Classification reason
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-19
- Auditor
- Compared macros
- container gallery
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | "Menu" is the user's word for what the macro produces. |
| D2 summary | OK | the description "Displays a menu created using simple wiki syntax (nested lists and links)." says what the macro adds to the page, in 13 words. |
| D3 category | OK | the macro is in Navigation, like tree, the other macro that turns a nested list into a navigation structure, and like toc and children. The compared macros, container and gallery, are in Layout, but a menu is navigation first, so Navigation is where users would look. |
| D4 quick-action | KO | Quick Actions finds the macro first for "menu" and for the German name "Menü"; the French name "Menu" is the English one, which is OK since the German one finds it. The synonyms "navigation" and "nav" rank it 4th, after Table of Contents, Children and Id. The synonyms "navbar" and "dropdown" give no result. |
| L1 consistency | OK | compared with container and gallery, and with tree, not audited yet, which also builds a navigation structure from a nested list. Like gallery, the content is mandatory, so the generic Quick Action opens the Edit Macro dialog, see I3; container and tree have an optional content and are inserted right away. An empty menu would not be a sensible result, so the mandatory content is by design. Unlike gallery, the content is a regular nested list of links, which the editor can create, not a format of its own. The default type, horizontal, is declared, like the defaults of the compared macros. |
| L2 doc-parameters | KO | the parameters are documented only on the legacy page Menu Application, not in the new documentation. That page does not document label nor the content, and documents the modifiers fixedWidth, collapsible and open of type, which the descriptor does not mention. |
| L3 doc-example | OK | the Horizontal Menu example of the documentation, a nested list of links with icons and separators in {{menu type="horizontal fixedWidth"}} , shows the most common use and renders without error. It links to Blog.WebHome, which XWiki Standard does not have, which only gives a link to a missing page. |
| I1 pattern | KO | the reference wrapper, warning, is inserted by its Quick Action without a dialog; the menu Quick Action opens the Edit Macro dialog, see I3. It follows the generic behavior of macros with a mandatory content and no dedicated Quick Action, like gallery. |
| I2 zero-config | OK | the Edit Macro dialog cannot be submitted with the default values, since the content is mandatory and empty: it stays open, with no message, the generic behavior of the dialog. An empty menu would not be a sensible result, so the mandatory content is OK. |
| I3 instant | KO | inserting from the Quick Actions menu with "/menu" and Enter opens the Edit Macro dialog with an empty Content text area, where the menu has to be typed in wiki syntax, like * [[Home>>Main.WebHome]] , before the macro is inserted. |
| I4 cursor | OK | after submitting the dialog with a content, typed text goes into the macro content. The content still has to be typed first in the dialog, see I3. |
| I5 focus | N/A | not a generator. |
| E1 wysiwyg | KO | the editor shows the content as a plain nested bulleted list on the blue background of the menu, with dark blue links of low contrast on it, separators as empty bullets and every sub-menu expanded, while view mode shows a horizontal menu bar whose sub-menus open on hover. The sub-menus are built by JavaScript that does not run in the editor. To reproduce: insert the Horizontal Menu example of the documentation, {{menu type="horizontal fixedWidth"}}* Applications ** [[Dashboard>>Dashboard.WebHome]]...{{/menu}} , and compare the editor with view mode. |
| E2 errors | KO | invalid values are accepted silently, with no message: {{menu type="foo"}}* Home{{/menu}} and {{menu type="Horizontal"}}* Home{{/menu}} render a plain bulleted list, with no menu style, since the value is only used as a CSS class. {{menu id="my menu"}}* A{{/menu}} outputs the invalid HTML id "my menu", which the toggle of the mobile menu targets as "#my menu". A content that is not a list, like {{menu}}Some text{{/menu}} or a table, is shown as is in the menu bar, with no message, although the content description asks for list items. |
| E3 nesting | KO | in a list item and in a table cell, like * {{menu}}* Home{{/menu}} , the macro fails with "The [menu] macro is a standalone macro and it cannot be used inline", in the editor and in view mode. In a box it renders and its content stays editable. A list, a table or a box inserted in its content renders with no error, but a table or a box is shown as is inside the menu bar, and nothing in the editor says that the content expects a list. |
| E4 inline-support | OK | the macro does not declare inline support, and its output, a navigation bar with drop-down sub-menus, is a block: the missing declaration has a technical reason. |
| E5 empty | OK | the content emptied in the editor stays a visible area, with an empty list item, that one click puts the cursor in. The list items left are saved as * lines, which render as separators. |
| E6 inplace | KO | the content of a standalone menu is edited in place as rich text, but the Edit Macro dialog still shows it as a wiki syntax text area, also when editing an existing menu, and it is the only way to type the content when inserting the macro, see I3. The in-place content is a plain list, not the menu, see E1. |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| $content | OK | OK | N/A | OK | N/A | OK | N/A | N/A | N/A | N/A | C1: the description "Define the menu structure using wiki syntax. Each menu item should be a list item and should contain the menu item label or link. You can use nested lists for sub-menu items." says what the content holds and how sub-menus are made. It does not say how to make a separator, an empty list item, which the documentation explains. C4: edited in the wiki syntax text area of the Edit Macro dialog when inserting and in place afterwards, recorded under E6. |
| type | KO | OK | OK | KO | OK | KO | N/A | OK | OK | N/A | C1: the description "The optional menu type determines the menu appearance and behaviour. The supported values are: horizontal (default value) and vertical." does not mention the modifiers fixedWidth, collapsible and open, which the most common example of the documentation sets, type="horizontal fixedWidth" , nor that they are combined with spaces. C3: horizontal, the declared default, is prefilled, and is the type of the most common example. C4: a free text field, although the accepted values are horizontal or vertical, plus the modifiers fixedWidth, collapsible and open: a select for the type and checkboxes for the modifiers could be used. A typo or another case, like "Horizontal", is accepted and gives a plain list, see E2. C6: the fields are in alphabetical order, Id, Label, Type. type, the only parameter of the most common example, comes last. C13: the accepted values are a list rather than a range or a format, so it is recorded N/A: the select of C4 would declare them. |
| id | OK | OK | OK | OK | OK | OK | N/A | KO | OK | KO | C1: the description "Optional menu identifier that will be set on the HTML element that wraps the menu. You can use this identifier in JavaScript code to access the menu DOM or in functional tests to assert the menu items." uses developer terms, but it explains the technical name Id, a hook for developers like cssClass, which another wording would only make more confusing. C8: a parameter for JavaScript code and functional tests, rarely used, which is not marked as advanced. C13, minor: the parameter only accepts a valid HTML id, but declares no format: {{menu id="my menu"}}* A{{/menu}} is accepted and outputs id="my menu", see E2. No format can be declared, the macro being a wiki macro, see Wiki macros cannot declare constraints and XWIKI-25197. |
| label | KO | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | C1, minor: the description "Optional menu label used to describe the content of the menu. Especially important for assistive technologies and accessibility of the menu." does not say that the label is not displayed, only announced by screen readers, while the name "Label" suggests a visible title of the menu. C8: the label names the navigation landmark for screen readers, which every menu should set, so it is rightly not advanced. It is never output as given, a bug recorded in Other notes. |
Other notes
Other sources: the earlier analysis of the macro found the in-place editing of the content "not formatted using the menu standards and not WYSIWYG", see E1.
The label parameter is never output as given: the macro tests #if ("$!label" != '') instead of == , so {{menu label="Main navigation"}} gets the generated aria-label "Menu", and a menu with no label gets the literal aria-label "${services.rendering.escape($label, 'xwiki/2.1')}", also visible in the menu of extensions.xwiki.org. It is a bug of the macro, not a usability criterion, to be filed in JIRA.
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| I1 | I1 pattern | XWIKI-25563 | |
| I3 | I3 instant | XWIKI-25563 | |
| E1 | E1 wysiwyg | XWIKI-25523 (partial), XWIKI-25524 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25502 (partial), XWIKI-25582 (partial) | |
| E3 | E3 nesting | XWIKI-23501 (partial) | XWIKI-25560 |
| E6 | E6 inplace | XWIKI-25443, XWIKI-25563 (partial) | |
| C1:type | C1 clarity, type | XWIKI-25481 | |
| C4:type | C4 input-assistance, type | XWIKI-23045 (partial) | XWIKI-25502 |
| C6:type | C6 order, type | XWIKI-25482 | |
| C8:id | C8 advanced, id | XWIKI-25482 | |
| C13:id | C13 constraints, id | XWIKI-25197 | |
| C1:label | C1 clarity, label | XWIKI-25481 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-23501 | Existing | E3 | |
| XWIKI-25197 | Existing | C13:id | |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25443 | New | E6 | |
| XWIKI-25444 | New | D4 | |
| XWIKI-25481 | New | C1:label C1:type | |
| XWIKI-25482 | New | C6:type C8:id | |
| XWIKI-23045 | Existing | C4:type | |
| XWIKI-25502 | New | C4:type | E2 |
| XINFRA-525 | New | L2 | |
| XWIKI-25523 | New | E1 | |
| XWIKI-25524 | New | E1 | |
| XWIKI-25560 | New | E3 | |
| XWIKI-25563 | New | I1 I3 | E6 |
| XWIKI-25582 | New | E2 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
