documentTree

Last modified by Lucas Charpentier on 2026/10/27 10:28

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.

SourceWhat it givesUsed forWhere
DocumentationParameters, default values and examples, including the most common exampleL2, L3, and the criteria measured with the most common examplehttps://extensions.xwiki.org/xwiki/bin/view/Extension/Document%20Tree%20Macro#HWikiMacro
Source codeHow the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline supportC4, C5, C7, C8, C9, C13, E4, E6https://github.com/xwiki/xwiki-platform/blob/xwiki-platform-18.8.0/xwiki-platform-core/xwiki-platform-index/xwiki-platform-index-tree/xwiki-platform-index-tree-macro/src/main/resources/XWiki/DocumentTree.xml
Macro descriptorWhat the Edit Macro dialog is built from, on design.xwiki.orgD1, D2, C1 to C9, E4Descriptor, list of macros with their categories
TranslationsThe name, description and parameter names in each languageD1, D2, D4, C1l10n.xwiki.org
Uses in XWiki pagesHow XWiki itself uses the macro, a realistic example when the documentation has noneL3, C2, C3, C6, C8, C9Search the xwiki organization on GitHub
Compared macrosThe audits of the macros of the same typeL1, D3children, toc
Other sources specific to this macro
  • documentTree_macros.vm, xwiki-platform: the defaults of the tree options, and readOnly read as false for any value other than "true", which enables drag and drop and the context menu.
  • Uses in XWiki Standard: {{documentTree /}} and variants hiding translations and attachments, or setting root, are the most frequent calls.
CriterionResultNotes
D1 wordingOK
D2 summaryKOthe 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 categoryOK
D4 quick-actionKOQuick 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 consistencyOKcompared 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-parametersKOthe 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-exampleOKthe most common example is {{documentTree /}} , the usage example of the documentation and the most frequent call in XWiki Standard.
I1 patternOKcompared 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-configOKQuick 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 instantN/A
I4 cursorN/A
I5 focusOKthe 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 wysiwygKOin 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: documentTree-e1-editor.png documentTree-e1-view.png
E2 errorsKOevery 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 nestingKOin 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-supportOKthe macro declares no inline support, and its output is a tree of nested lists, which cannot be inside a sentence.
E5 emptyN/A
E6 inplaceN/A

Parameters

ParameterC1 clarityC2 mandatoryC3 defaultsC4 input-assistanceC5 groupsC6 orderC7 alternativesC8 advancedC9 technicalC13 constraintsNotes
readOnlyOKOKOKOKOKOKN/AOKOKN/A
showWikisOKOKOKOKKOOKN/AOKOKN/A

C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree.

showWikiPrettyNameKOOKOKOKKOOKN/AOKOKN/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.

showSpacesKOOKOKOKKOOKN/AOKOKN/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.

showDocumentTitleOKOKOKOKKOOKN/AOKOKN/A

C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree.

showTranslationsOKOKOKOKKOOKN/AOKOKN/A

C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree.

showAttachmentsOKOKOKOKKOOKN/AOKOKN/A

C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree.

showObjectsKOOKOKOKKOOKN/AOKOKN/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.

showClassPropertiesKOOKOKOKKOOKN/AOKOKN/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.

hierarchyModeKOOKOKKOOKOKN/AOKOKKO

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.

rootOKOKOKOKOKOKN/AOKOKOK

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.

compactOKOKOKOKOKOKN/AOKOKN/A
linksOKOKOKOKOKOKN/AOKOKN/A
checkboxesOKOKOKOKOKOKN/AOKOKN/A
openToOKOKOKOKOKOKN/AOKOKOK

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.

showOnlyViewableOKOKOKOKKOOKN/AOKOKN/A

C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree.

filterByClassKOOKOKKOOKOKN/AOKOKN/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.

finderOKOKOKOKOKOKN/AOKOKN/A
showRootOKOKOKOKKOOKN/AOKOKN/A

C5: the Elements to show group holds 10 parameters, above 7 ± 2, and mixes the filter showOnlyViewable with the elements of the tree.

filterHiddenDocumentsKOOKOKOKOKOKN/AOKOKN/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.

limitOKOKOKKOOKOKN/AOKOKKO

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.

exclusionsKOOKOKKOOKOKN/AOKOKKO

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.

sortDocumentsByOKOKKOOKOKOKN/AOKOKOK

C3, minor: the selects open on "-", the default order, which is by title when Show Page Title is checked and by name otherwise. The field does not say which order "-" gives, although a default is used.

expandToLevelOKOKOKKOOKOKN/AOKOKKO

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.

KOCriterionExisting ticketsNew tickets
D2D2 summaryXWIKI-25470
D4D4 quick-actionXWIKI-25444
L2L2 doc-parametersXINFRA-525
E1E1 wysiwygXWIKI-25523 (partial), XWIKI-25524
E2E2 errorsXWIKI-23142 (partial)XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25580 (partial)
E3E3 nestingXWIKI-23501
C5:showWikisC5 groups, showWikisXWIKI-25472
C1:showWikiPrettyNameC1 clarity, showWikiPrettyNameXWIKI-25470
C5:showWikiPrettyNameC5 groups, showWikiPrettyNameXWIKI-25472
C1:showSpacesC1 clarity, showSpacesXWIKI-25470
C5:showSpacesC5 groups, showSpacesXWIKI-25472
C5:showDocumentTitleC5 groups, showDocumentTitleXWIKI-25472
C5:showTranslationsC5 groups, showTranslationsXWIKI-25472
C5:showAttachmentsC5 groups, showAttachmentsXWIKI-25472
C1:showObjectsC1 clarity, showObjectsXWIKI-25470
C5:showObjectsC5 groups, showObjectsXWIKI-25472
C1:showClassPropertiesC1 clarity, showClassPropertiesXWIKI-25470
C5:showClassPropertiesC5 groups, showClassPropertiesXWIKI-25472
C1:hierarchyModeC1 clarity, hierarchyModeXWIKI-25470
C4:hierarchyModeC4 input-assistance, hierarchyModeXWIKI-23557
C13:hierarchyModeC13 constraints, hierarchyModeXWIKI-25197
C5:showOnlyViewableC5 groups, showOnlyViewableXWIKI-25472
C1:filterByClassC1 clarity, filterByClassXWIKI-25470
C4:filterByClassC4 input-assistance, filterByClassXWIKI-25559
C5:showRootC5 groups, showRootXWIKI-25472
C1:filterHiddenDocumentsC1 clarity, filterHiddenDocumentsXWIKI-25470
C4:limitC4 input-assistance, limitXWIKI-25182 (partial), XWIKI-25197 (partial)XWIKI-25498
C13:limitC13 constraints, limitXWIKI-25197
C1:exclusionsC1 clarity, exclusionsXWIKI-25470
C4:exclusionsC4 input-assistance, exclusionsXWIKI-25565
C13:exclusionsC13 constraints, exclusionsXWIKI-25197
C3:sortDocumentsByC3 defaults, sortDocumentsByXWIKI-25472
C4:expandToLevelC4 input-assistance, expandToLevelXWIKI-25182 (partial), XWIKI-25197 (partial)XWIKI-25498
C13:expandToLevelC13 constraints, expandToLevelXWIKI-25197
Success

Every KO is covered by a ticket.

Tickets

TicketOriginKOs coveredKOs partly covered
XWIKI-23142ExistingE2
XWIKI-23557ExistingC4:hierarchyMode
XWIKI-25182ExistingC4:expandToLevel C4:limit
XWIKI-25197ExistingC13:exclusions C13:expandToLevel C13:hierarchyMode C13:limitC4:limit C4:expandToLevel
XCOMMONS-3847NewE2
XRENDERING-823NewE2
XWIKI-25444NewD4
XWIKI-25470NewC1:exclusions C1:filterByClass C1:filterHiddenDocuments C1:hierarchyMode C1:showClassProperties C1:showObjects C1:showSpaces C1:showWikiPrettyName D2
XWIKI-25472NewC3:sortDocumentsBy C5:showAttachments C5:showClassProperties C5:showDocumentTitle C5:showObjects C5:showOnlyViewable C5:showRoot C5:showSpaces C5:showTranslations C5:showWikiPrettyName C5:showWikis
XWIKI-25498NewC4:limit C4:expandToLevel
XINFRA-525NewL2
XWIKI-25523NewE1
XWIKI-25524NewE1
XWIKI-25559NewC4:filterByClass
XWIKI-23501ExistingE3
XWIKI-25565NewC4:exclusions
XWIKI-25580NewE2

Known issues of this macro

IssueTitleStatusCriteria
XWIKI-23026Error when sorting by "Creation date" or "Last modification date" in Document Tree macro that prevents displaying the documentsOpenE2
XWIKI-23142Rendering error is not clear when inserting a wrong Root parameter in Children Macro and Page Tree MacroOpenE2
XWIKI-24713Small misalignment still present on the document picker on Page Tree macroOpenC4

68 more known issues affect every macro: see the Known issues.

Get Connected