documentTree
Audit
- Macro ID
- documentTree
- Source
- XS
- Type
- Generator
- Classification reason
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-16
- Auditor
- Compared macros
- children toc
Sources
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 | |
| D2 summary | KO | the description "Displays the tree of XWiki pages." repeats the name "Page Tree", and does not say that the tree lists the pages of the wiki, or of a given page, as links that expand on click. |
| D3 category | OK | |
| D4 quick-action | KO | Quick Actions finds the macro first for "documentTree", "Page Tree" and the French name "Arborescence", second for the synonym "tree", after the Tree macro, and fifth for "navigation". The synonyms "hierarchy", "sitemap" and "index" do not find it: "hierarchy" only lists the Tree macro. |
| L1 consistency | OK | compared with children and toc: like them, no parameter is mandatory, there is no content, and the Quick Action inserts the macro right away, with no dialog. |
| L2 doc-parameters | KO | the parameters are only documented on the legacy extensions.xwiki.org page, not in the new documentation. That page also documents showChildDocuments, which is no longer a parameter of the macro, and gives title:asc as the default of sortDocumentsBy, while the macro declares no default. |
| L3 doc-example | OK | the most common example is {{documentTree /}} , the usage example of the documentation and the most frequent call in XWiki Standard. |
| I1 pattern | OK | compared with children, the reference generator: both are inserted by their Quick Action without a dialog, and through the Insert Macro dialog with an Edit Macro dialog whose fields are all optional. |
| I2 zero-config | OK | Quick Actions and the Edit Macro dialog submitted with the default values insert {{documentTree/}} , which shows the tree of the whole wiki in view mode, with no error. In the editor only the generic "macro:documentTree" placeholder is shown, see E1. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | the macro has no mandatory parameter. The first tab, Optional parameters, starts with Root, and the focus is on its type selector, the first control of the dialog. |
| E1 wysiwyg | KO | in the editor, {{documentTree /}} shows only the generic "macro:documentTree" placeholder, even after waiting for the tree to load, while view mode shows the tree of the wiki pages. The editor does not show which pages the tree lists or how it is configured. In the editor, then in view mode: ![]() |
| E2 errors | KO | every invalid value tried is accepted silently. For example, {{documentTree limit="abc"/}} , {{documentTree expandToLevel="abc"/}} , {{documentTree hierarchyMode="abc"/}} and {{documentTree sortDocumentsBy="title:sideways"/}} render the default tree, {{documentTree root="abc"/}} renders "No pages found", with no message about the root, and {{documentTree readOnly="maybe"/}} is read as false, which makes the tree editable. |
| E3 nesting | KO | in a list item and in a table cell, like * {{documentTree/}} , the macro is inline and renders "The [documentTree] macro is a standalone macro and it cannot be used inline." in the editor and in view mode. Inserting it from Quick Actions at the end of a list item gives the same error and saves * two{{documentTree/}}((( ))) . In a box it works. |
| E4 inline-support | OK | the macro declares no inline support, and its output is a tree of nested lists, which cannot be inside a sentence. |
| E5 empty | N/A | |
| E6 inplace | N/A |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| readOnly | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | |
| showWikis | OK | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| showWikiPrettyName | KO | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C1, minor: "Pretty Name" and "wiki id" are technical terms: the name does not say that it shows the title of the wiki instead of its identifier, like "Show wiki titles". C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| showSpaces | KO | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C1, minor: "Spaces" is a technical term that the UI no longer shows since nested pages, and the description, "The pages are grouped by space", does not explain it. C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| showDocumentTitle | OK | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| showTranslations | OK | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| showAttachments | OK | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| showObjects | KO | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C1: "Objects" is a developer term, while the macro targets every user: nothing explains it in the dialog. C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| showClassProperties | KO | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C1: "Class Properties" is a developer term, while the macro targets every user: nothing explains it in the dialog. C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| hierarchyMode | KO | OK | OK | KO | OK | OK | N/A | OK | OK | KO | C1: the values "reference" and "parentchild" and the description, "the nested spaces component of the page reference", "the parent page field from the database", are technical terms that do not say which tree the user gets. C4: a plain text field where any text can be typed, while the value is one of "reference" and "parentchild", which a select would fit. For example, typing "parent-child" is accepted and gives the default tree. C13: the macro is a wiki macro, whose parameters cannot declare a range or a format, see XWIKI-25197 in the Cross-macro findings. |
| root | OK | OK | OK | OK | OK | OK | N/A | OK | OK | OK | C1: "Root" and "root node id" are technical, but the field is a picker with a type selector, and the description explains that the tree shows the descendants of the given node. |
| compact | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | |
| links | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | |
| checkboxes | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | |
| openTo | OK | OK | OK | OK | OK | OK | N/A | OK | OK | OK | C1: "node id" is technical, but the field is the same picker as Root. The German name "Offen für" is a mistranslation, to fix on l10n.xwiki.org. |
| showOnlyViewable | OK | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| filterByClass | KO | OK | OK | KO | OK | OK | N/A | OK | OK | N/A | C1: "Class" is a developer term, while the macro targets every user. The description gives an example, Blog.CategoryClass, but does not explain what a class is. C4: a plain text field for the reference of a class page, where a page picker could be used. |
| finder | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | |
| showRoot | OK | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree. |
| filterHiddenDocuments | KO | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | C1, minor: the name and description say "documents" while the rest of the dialog says pages, and "Filter Hidden Documents" checked does not filter them for a user whose preferences show hidden pages. |
| limit | OK | OK | OK | KO | OK | OK | N/A | OK | OK | KO | C4: a plain text field where any text can be typed, while the value is a number of child nodes, which a number field would fit. C13: the macro is a wiki macro, whose parameters cannot declare a range or a format, see XWIKI-25197 in the Cross-macro findings. |
| exclusions | KO | OK | OK | KO | OK | OK | N/A | OK | OK | KO | C1: the description says the nodes are "specified by their id and separated by comma" but does not give the format of a node id, like document:xwiki:Main.WebHome, which only the documentation gives. C4: a plain text field for a list of node ids, where the node picker of Root, with several values, could be used. C13: the macro is a wiki macro, whose parameters cannot declare a range or a format, see XWIKI-25197 in the Cross-macro findings. |
| sortDocumentsBy | OK | OK | KO | OK | OK | OK | N/A | OK | OK | OK | C3, minor: the selects open on " |
| expandToLevel | OK | OK | OK | KO | OK | OK | N/A | OK | OK | KO | C4: a plain text field where any text can be typed, while the value is a tree depth from 0, which a number field would fit. C13: the macro is a wiki macro, whose parameters cannot declare a range or a format, see XWIKI-25197 in the Cross-macro findings. |
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-25470 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| E1 | E1 wysiwyg | XWIKI-25523 (partial), XWIKI-25524 | |
| E2 | E2 errors | XWIKI-23142 (partial) | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25580 (partial) |
| E3 | E3 nesting | XWIKI-23501 | |
| C5:showWikis | C5 groups, showWikis | XWIKI-25472 | |
| C1:showWikiPrettyName | C1 clarity, showWikiPrettyName | XWIKI-25470 | |
| C5:showWikiPrettyName | C5 groups, showWikiPrettyName | XWIKI-25472 | |
| C1:showSpaces | C1 clarity, showSpaces | XWIKI-25470 | |
| C5:showSpaces | C5 groups, showSpaces | XWIKI-25472 | |
| C5:showDocumentTitle | C5 groups, showDocumentTitle | XWIKI-25472 | |
| C5:showTranslations | C5 groups, showTranslations | XWIKI-25472 | |
| C5:showAttachments | C5 groups, showAttachments | XWIKI-25472 | |
| C1:showObjects | C1 clarity, showObjects | XWIKI-25470 | |
| C5:showObjects | C5 groups, showObjects | XWIKI-25472 | |
| C1:showClassProperties | C1 clarity, showClassProperties | XWIKI-25470 | |
| C5:showClassProperties | C5 groups, showClassProperties | XWIKI-25472 | |
| C1:hierarchyMode | C1 clarity, hierarchyMode | XWIKI-25470 | |
| C4:hierarchyMode | C4 input-assistance, hierarchyMode | XWIKI-23557 | |
| C13:hierarchyMode | C13 constraints, hierarchyMode | XWIKI-25197 | |
| C5:showOnlyViewable | C5 groups, showOnlyViewable | XWIKI-25472 | |
| C1:filterByClass | C1 clarity, filterByClass | XWIKI-25470 | |
| C4:filterByClass | C4 input-assistance, filterByClass | XWIKI-25559 | |
| C5:showRoot | C5 groups, showRoot | XWIKI-25472 | |
| C1:filterHiddenDocuments | C1 clarity, filterHiddenDocuments | XWIKI-25470 | |
| C4:limit | C4 input-assistance, limit | XWIKI-25182 (partial), XWIKI-25197 (partial) | XWIKI-25498 |
| C13:limit | C13 constraints, limit | XWIKI-25197 | |
| C1:exclusions | C1 clarity, exclusions | XWIKI-25470 | |
| C4:exclusions | C4 input-assistance, exclusions | XWIKI-25565 | |
| C13:exclusions | C13 constraints, exclusions | XWIKI-25197 | |
| C3:sortDocumentsBy | C3 defaults, sortDocumentsBy | XWIKI-25472 | |
| C4:expandToLevel | C4 input-assistance, expandToLevel | XWIKI-25182 (partial), XWIKI-25197 (partial) | XWIKI-25498 |
| C13:expandToLevel | C13 constraints, expandToLevel | XWIKI-25197 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-23142 | Existing | E2 | |
| XWIKI-23557 | Existing | C4:hierarchyMode | |
| XWIKI-25182 | Existing | C4:expandToLevel C4:limit | |
| XWIKI-25197 | Existing | C13:exclusions C13:expandToLevel C13:hierarchyMode C13:limit | C4:limit C4:expandToLevel |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| XWIKI-25470 | New | C1:exclusions C1:filterByClass C1:filterHiddenDocuments C1:hierarchyMode C1:showClassProperties C1:showObjects C1:showSpaces C1:showWikiPrettyName D2 | |
| XWIKI-25472 | New | C3:sortDocumentsBy C5:showAttachments C5:showClassProperties C5:showDocumentTitle C5:showObjects C5:showOnlyViewable C5:showRoot C5:showSpaces C5:showTranslations C5:showWikiPrettyName C5:showWikis | |
| XWIKI-25498 | New | C4:limit C4:expandToLevel | |
| XINFRA-525 | New | L2 | |
| XWIKI-25523 | New | E1 | |
| XWIKI-25524 | New | E1 | |
| XWIKI-25559 | New | C4:filterByClass | |
| XWIKI-23501 | Existing | E3 | |
| XWIKI-25565 | New | C4:exclusions | |
| XWIKI-25580 | New | E2 |
Known issues of this macro
| Issue | Title | Status | Criteria |
|---|---|---|---|
| XWIKI-23026 | Error when sorting by "Creation date" or "Last modification date" in Document Tree macro that prevents displaying the documents | Open | E2 |
| XWIKI-23142 | Rendering error is not clear when inserting a wrong Root parameter in Children Macro and Page Tree Macro | Open | E2 |
| XWIKI-24713 | Small misalignment still present on the document picker on Page Tree macro | Open | C4 |
68 more known issues affect every macro: see the Known issues.
Lucas Charpentier
