dashboard
Audit
- Macro ID
- dashboard
- Source
- XS
- Type
- Generator
- Classification reason
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-19
- Auditor
- Compared macros
- children liveData
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Source | What it gives | Used for | Where |
|---|---|---|---|
| Documentation | Parameters, default values and examples, including the most common example | L2, L3, and the criteria measured with the most common example | https://extensions.xwiki.org/xwiki/bin/view/Extension/Dashboard%20Macro#HDescription |
| Source code | How the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline support | C4, C5, C7, C8, C9, C13, E4, E6 | Not recorded yet: search GitHub |
| Macro descriptor | What the Edit Macro dialog is built from, on design.xwiki.org | D1, D2, C1 to C9, E4 | Descriptor, list of macros with their categories |
| Translations | The name, description and parameter names in each language | D1, D2, D4, C1 | l10n.xwiki.org |
| Uses in XWiki pages | How XWiki itself uses the macro, a realistic example when the documentation has none | L3, C2, C3, C6, C8, C9 | Search the xwiki organization on GitHub |
| Compared macros | The audits of the macros of the same type | L1, D3 | children, liveData |
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | "Dashboard" is the user's word for what the macro produces, a page of gadgets giving an overview of the wiki, with no camelCase or acronym. |
| D2 summary | KO | the description "A macro to define a dashboard to fill with gadgets." mostly repeats the name, and starts with "A macro to": it does not say what the macro adds to the page, the gadgets saved on the page, or on the Source page, shown in columns. The Java description, "A macro to define a dashboard.", is overridden by the translation. |
| D3 category | KO | minor: the macro is in Layout, like container and gallery, but a dashboard is not a layout: it shows gadgets, the page tree or the activity stream, which users would rather look for in Content or Navigation, the categories of the compared generators liveData and children. Which category fits should be questioned again with the community. |
| D4 quick-action | KO | Quick Actions finds the macro first for "dashboard", "Dashboard", the French name "Tableau de bord" and the synonym "gadget". The German name is "Dashboard", as in English. The synonyms "widget", "overview", "portal" and "home" give no result for the macro, "overview" listing Table of Contents, "portal" Info Box and "home" Mention and center. |
| L1 consistency | OK | compared with children and liveData, two generators with no mandatory parameter: like them, every parameter is optional and the Quick Action inserts the macro right away, with no dialog. Like children, there is no content, while the optional content of liveData is an advanced JSON configuration. Unlike children, which declares no default, dashboard declares its defaults, columns for layout and an empty style. Unlike them, an empty dashboard shows nothing at all, see I2. |
| L2 doc-parameters | KO | the parameters are documented only on the legacy extensions.xwiki.org page, with no page in the new documentation. On that page, the three parameters and their optional flags match the descriptor, but the default of layout is given as "none" in the table while the macro declares columns, which the description explains. |
| L3 doc-example | KO | minor: the documentation has no example to copy: the only call is {{dashboard}} in a sentence of "Creating a dashboard", with no closing, probably a typo for {{dashboard/}} , and no code block calls the macro. The description of source gives Dashboard.WebHome as an example, but it is a hidden page that the page picker cannot find: the documentation should give a page users can pick. The audit uses {{dashboard/}} , the call of 4 of the 8 uses of the macro in XWiki Standard, like Dashboard.WebHome, on a page holding gadgets; the other uses set source, like {{dashboard source="$xcontext.user"/}} in XWikiUserDashboardSheet. To get gadgets on a test page, the audit uses {{dashboard source="Dashboard.WebHome"/}} , which shows the 3 gadgets of the main dashboard. |
| I1 pattern | OK | like children, the reference generator, Quick Actions inserts {{dashboard/}} without a dialog, since no parameter is mandatory, and the Insert Macro dialog opens an Edit Macro dialog whose fields are all optional. |
| I2 zero-config | KO | Quick Actions and the Edit Macro dialog submitted with the default values insert {{dashboard/}} . On a page without gadgets, view mode shows nothing at all, and the editor shows a widget 10 pixels high with no placeholder, which disappears once the cursor leaves it: nothing says that the dashboard is there or that gadgets are added from the inline form editor, ?editor=inline. An empty dashboard should at least show a minimal wrapping, like the frame of its empty columns. To reproduce: insert the macro on a new page, click away, then save. |
| I3 instant | N/A | N/A, the macro is a generator. |
| I4 cursor | N/A | N/A, the macro is a generator. |
| I5 focus | OK | no parameter is mandatory. The focus is on the first field, Layout, prefilled with columns. |
| E1 wysiwyg | KO | in the WYSIWYG editor, {{dashboard source="Dashboard.WebHome"/}} shows the gadget titles, Pages, Tags and Activity Stream, but not the page tree and the activity stream that view mode shows under them, which are built by JavaScript that does not run in the editor; an empty dashboard shows nothing, see I2. The dedicated edit representation of the dashboard, with the Add Gadget and Add column buttons, the gadget frames and their edit and remove actions, is only in the inline form editor, ?editor=inline, which the WYSIWYG editor does not lead to: once inserted in the WYSIWYG editor, the gadgets can neither be seen fully nor added there. |
| E2 errors | KO | an unknown layout, like {{dashboard layout="noSuchLayout"/}} , renders "Failed to execute the [dashboard] macro. Cause: [Could not find dashboard renderer noSuchLayout]." with a stack trace in the details: it names the value, not the parameter, and does not say that columns is the only layout. A source that does not exist, like source="No.Such.Page" , shows an empty dashboard, a valid use since adding gadgets creates it. style accepts any value, by design, since it is a CSS class. |
| E3 nesting | KO | in a list item and in a table cell, like * {{dashboard/}} , the macro is inline and renders "The [dashboard] macro is a standalone macro and it cannot be used inline." in view mode. In a box it renders. The macro has no content, so the second half of the measure does not apply. |
| E4 inline-support | OK | the macro declares no inline support, and its output is a layout of gadget columns, which cannot be inside a sentence: in a sentence it renders the standalone error, as expected. |
| E5 empty | N/A | N/A, the macro is a generator. |
| E6 inplace | N/A | N/A, the macro is a generator. |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| layout | KO | OK | OK | OK | OK | OK | N/A | KO | OK | N/A | C1, minor: "The identifier of the layout to use for this dashboard (e.g. columns, etc)" uses the developer term "identifier" and an "etc" for a list of values that has only one entry in XWiki Standard. The English name in the descriptor is the ID, "layout", the dialog only capitalizing it. C4: a plain text field, OK: columns is the only layout of XWiki Standard, and the field is there for the layouts customizations add. C8: rarely used and not marked as advanced: it should be advanced at the very least. The documentation says "This parameter is for advanced usage, should be left empty for basic use cases." C9: columns is the only layout of XWiki Standard, the default, and no use of the macro sets it, but customizations can add layouts, so the field is kept visible, as an advanced parameter, see C8. |
| source | KO | OK | OK | OK | OK | OK | N/A | KO | OK | N/A | C1: "The source of the dashboard macro, as a page reference, where the gadget configurations (objects) should be read from." is circular, "the source of the dashboard macro", and uses the developer terms "page reference" and "objects". It does not say the effect for the user: showing, and editing, the gadgets of another page, shared by every page that uses it. C3: no default is declared, but the field opens empty, which means the current page, the value of the most common example. C4: a page picker, which finds pages by their title, like "Sandbox". The example of the description, Dashboard.WebHome, is a hidden page, so searching "Dashboard" gives only "Select Dashboard ...": the picker hiding hidden pages is generic, and the documentation should give another example, see L3. C8: the documentation says "This parameter is for advanced usage, should be left empty for basic use cases.", and XWiki Standard sets it only from sheets, like source="$xcontext.user" , but it is not marked as advanced. |
| style | KO | OK | OK | KO | OK | OK | N/A | KO | OK | N/A | C1: the parameter holds a CSS class, like cssClass in other macros such as box, container or code, but it is named style, which reads as an inline CSS style: the name is inconsistent with the other macros. The description is long, four sentences, but it explains the effect of no value and of "panels". C3: the field opens empty, which means no style, the value of every use of the macro in XWiki Standard. C4, minor: a plain text field, while the only predefined value, "panels", is given in the description only: a field suggesting it, and accepting any other CSS class, would show it. C8: a styling parameter that is rarely used, set by no use of the macro in XWiki Standard, but it is not marked as advanced. |
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 |
|---|---|---|---|
| D2 | D2 summary | XWIKI-25483 | |
| D3 | D3 category | XWIKI-25483 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| L3 | L3 doc-example | XINFRA-526 | |
| I2 | I2 zero-config | XWIKI-22046 (partial) | XWIKI-25512 |
| E1 | E1 wysiwyg | XWIKI-25523 (partial), XWIKI-25524 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25503 (partial) | |
| E3 | E3 nesting | XWIKI-23501 | |
| C1:layout | C1 clarity, layout | XWIKI-25483 | |
| C8:layout | C8 advanced, layout | XWIKI-25484 | |
| C1:source | C1 clarity, source | XWIKI-25483 | |
| C8:source | C8 advanced, source | XWIKI-25484 | |
| C1:style | C1 clarity, style | XWIKI-25483 | |
| C4:style | C4 input-assistance, style | XWIKI-23045 (partial) | XWIKI-25503 |
| C8:style | C8 advanced, style | XWIKI-25484 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-22046 | Existing | I2 | |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| XWIKI-25483 | New | C1:layout C1:source C1:style D2 D3 | |
| XWIKI-25484 | New | C8:layout C8:source C8:style | |
| XWIKI-23045 | Existing | C4:style | |
| XWIKI-25503 | New | C4:style | E2 |
| XINFRA-525 | New | L2 | |
| XINFRA-526 | New | L3 | |
| XWIKI-25512 | New | I2 | |
| XWIKI-25523 | New | E1 | |
| XWIKI-25524 | New | E1 | |
| XWIKI-23501 | Existing | E3 |
Known issues of this macro
| Issue | Title | Status | Criteria |
|---|---|---|---|
| XWIKI-6138 | Add Gadget dialog add gadget title field on top of the macro description | Open | C6 |
| XWIKI-20634 | Suggestions of the page picker in macro parameters display under the modal when used on the dashboard editor | Open | C4 |
68 more known issues affect every macro: see the Known issues.
