documents

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

Audit

Macro ID
documents
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
liveData children

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/Documents%20Macro#HDescription
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-ui/src/main/resources/XWiki/DocumentsMacro.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, D3liveData, children
Other sources specific to this macro
CriterionResultNotes
D1 wordingOK
D2 summaryKOminor: "Displays a list of pages in a Livetable" is outdated: "Livetable" is the developer name of the table component that the macro no longer uses: it renders a Live Data. It does not say that the table can be sorted, filtered and paged through, nor that it adds Likes and Actions columns, with Copy, Rename and Delete, by default.
D3 categoryKOminor: the macro is in Content, like liveData, while children and documentTree, the other macros that list pages, are in Navigation, where a user looking for a list of pages would also look.
D4 quick-actionKOQuick Actions finds the macro first for its ID "documents", its name "Pages" and the French name "Documents". The synonyms "page list", "page index", "index", "all pages" and "page table" give no result.
L1 consistencyOKcompared with liveData and children: like them, no parameter is mandatory, there is no content, and the Quick Action inserts the macro right away, with no dialog. Like liveData, it renders a Live Data; unlike liveData, it declares its default page size, 15.
L2 doc-parametersKOthe parameters are only documented on the legacy extensions.xwiki.org page, not in the new documentation. That page does not document the description parameter, and documents space and parent as deprecated, which the macro does not declare, see C9.
L3 doc-exampleOKthe most common example is {{documents location="Drafts."/}} , Example 1 of the documentation, which renders without error. The "Usage" line with placeholder values is a template, not an example.
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 {{documents/}} , which lists every page of the wiki in view mode, with no error. In the standalone editor it stays a loading spinner, see E1.
I3 instantN/A
I4 cursorN/A
I5 focusOKthe macro has no mandatory parameter. The focus is on the first field, Actions.
E1 wysiwygKOin the standalone WYSIWYG editor, ?editor=wysiwyg, the most common example stays a loading spinner, still after 60 seconds, while view mode shows the table of pages: the Live Data scripts are not loaded in the editor iframe, as for the liveData macro. To reproduce: on a page with two child pages, insert {{documents location="<page name>."/}} . In the in-place editor, the table renders as in view mode.
E2 errorsKOevery invalid value tried is accepted silently. For example, {{documents count="abc"/}} shows a page size of 0 and every entry under "Entries 0 - 0 out of 4", {{documents count="-3"/}} shows "(No entries)", {{documents actions="maybe"/}} is read as false, {{documents columns="doc.noSuch"/}} and {{documents columns="title,author"/}} show an empty table with "(No entries)", {{documents filters="noSuch=abc"/}} is ignored, and {{documents space="No.Such"/}} and {{documents parent="No.Such.WebHome"/}} show "(No entries)", all with no message.
E3 nestingKOin a list item and in a table cell, like * {{documents location="Drafts."/}} , the macro is inline and renders "The [documents] macro is a standalone macro and it cannot be used inline." In a box it renders. The macro has no content, so the second half of the measure does not apply.
E4 inline-supportOKthe macro declares no inline support, and its output is a table with pagination bars, 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
countOKOKOKKOKOOKN/AOKOKKO

C4: a plain text field for a number of entries per page, which a number field would fit.

C5, minor: the 9 fields are all in the single group "Optional parameters", above 7, mixing the parameters that choose the pages, location, space, parent and filters, with the display options, columns, count, actions, id and description. The same holds for every parameter.

C13: the macro is a wiki macro, whose parameters cannot declare a range or a format, see XWIKI-25197 in the Cross-macro findings. count="-3" is accepted and shows "(No entries)".

actionsOKOKOKOKKOOKN/AOKOKN/A
spaceKOOKOKOKKOOKKOOKKON/A

C1, minor: "space" is a technical term that the UI no longer shows since nested pages, and the description does not say that the full space reference is needed.

C4: a plain text field for a space reference, not counted: the parameter is deprecated, and hiding it, see C9, is the fix.

C7: an older alternative of location, shown as a separate field, see location.

C8: rarely used and not marked as advanced, not counted: hiding it, see C9, is the fix.

C9: documented as deprecated, "Doesn't work with Nested Pages, use the location parameter instead", but shown, and not declared deprecated or hidden.

idKOOKOKOKKOOKN/AKOOKN/A

C1: "Livetable id" uses a developer term, and the wrong one, the table being a Live Data, and does not say what the id is for: styling the table, and telling apart two tables of a page.

C8: rarely used, for styling, and not marked as advanced.

parentKOOKOKOKKOOKKOOKKON/A

C1: "Only list pages having the specified parent" means the legacy parent field, not the page that contains the listed pages: on a page with two nested child pages, {{documents parent="<that page>.WebHome"/}} shows "(No entries)". The description does not say it.

C4: a plain text field for a page reference, not counted: the parameter is deprecated, and hiding it, see C9, is the fix.

C7: an older alternative of location, shown as a separate field, see location.

C8: rarely used and not marked as advanced, not counted: hiding it, see C9, is the fix.

C9: documented as deprecated, "Doesn't work with Nested Pages, use the location parameter instead", but shown, and not declared deprecated or hidden.

columnsKOOKKOKOKOOKN/AOKOKN/A

C1: the description gives a wrong default, "doc.name,doc.space,doc.date,doc.author", while the table shows Title, Location, Date and Last Author, doc.title,doc.location,doc.date,doc.author. It does not say where the property names come from, nor that the Likes and Actions columns are added anyway.

C3: the field opens empty and the descriptor declares no default. Empty gives the expected columns, Title, Location, Date and Last Author, but the description gives another default, see C1, so the dialog does not show the actual default.

C4: a plain text field for a list of page properties, which a picker could offer.

locationOKOKOKKOKOKOKOOKOKN/A

C1: "full reference" is a technical term, but the description explains the match with an example. The French and German descriptions are left in English, to fix on l10n.xwiki.org.

C4: a plain text field, where a page picker could set the location of the listed pages, the use of every example.

C6: the only parameter set by the most common example, and the 6th of the 9 fields, after Actions, Columns, Count, Description and Id.

C7: space and parent are older alternatives of location for choosing the listed pages, deprecated in the documentation, but they are shown as separate fields rather than as one feature.

descriptionOKOKOKOKKOOKN/AOKOKN/A
filtersKOOKOKOKKOOKN/AOKOKN/A

C1, minor: "Provide a default filter to apply in the documents Live Data" does not give the format, like doc.author=Admin, which only the documentation gives.

Other notes

The Likes column is always added, even when columns lists other columns: {{documents columns="doc.noSuch"/}} shows the columns doc.noSuch, Likes and Actions.

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
D3D3 categoryXWIKI-25470
D4D4 quick-actionXWIKI-25444
L2L2 doc-parametersXINFRA-525
E1E1 wysiwygXWIKI-25433
E2E2 errorsXCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25580 (partial)
E3E3 nestingXWIKI-23501
C4:countC4 input-assistance, countXWIKI-25182 (partial), XWIKI-25197 (partial)XWIKI-25498
C5:countC5 groups, countXWIKI-25472
C13:countC13 constraints, countXWIKI-25197
C5:actionsC5 groups, actionsXWIKI-25472
C1:spaceC1 clarity, spaceXWIKI-25470
C5:spaceC5 groups, spaceXWIKI-25472
C7:spaceC7 alternatives, spaceXWIKI-13363
C9:spaceC9 technical, spaceXWIKI-13363
C1:idC1 clarity, idXWIKI-25470
C5:idC5 groups, idXWIKI-25472
C8:idC8 advanced, idXWIKI-25472
C1:parentC1 clarity, parentXWIKI-25470
C5:parentC5 groups, parentXWIKI-25472
C7:parentC7 alternatives, parentXWIKI-13363
C9:parentC9 technical, parentXWIKI-13363
C1:columnsC1 clarity, columnsXWIKI-23116 (partial)XWIKI-25470
C3:columnsC3 defaults, columnsXWIKI-25472
C4:columnsC4 input-assistance, columnsXWIKI-23045 (partial)XWIKI-25498
C5:columnsC5 groups, columnsXWIKI-25472
C4:locationC4 input-assistance, locationXWIKI-25534
C5:locationC5 groups, locationXWIKI-25472
C6:locationC6 order, locationXWIKI-25472
C7:locationC7 alternatives, locationXWIKI-13363
C5:descriptionC5 groups, descriptionXWIKI-25472
C1:filtersC1 clarity, filtersXWIKI-25470
C5:filtersC5 groups, filtersXWIKI-25472
Success

Every KO is covered by a ticket.

Tickets

TicketOriginKOs coveredKOs partly covered
XWIKI-13363ExistingC9:parent C9:space C7:space C7:parent C7:location
XWIKI-23116ExistingC1:columns
XWIKI-25182ExistingC4:count
XWIKI-25197ExistingC13:countC4:count
XWIKI-25433ExistingE1
XCOMMONS-3847NewE2
XRENDERING-823NewE2
XWIKI-25444NewD4
XWIKI-25470NewC1:filters C1:id C1:parent C1:space D2 D3 C1:columns
XWIKI-25472NewC3:columns C5:actions C5:columns C5:count C5:description C5:filters C5:id C5:location C5:parent C5:space C6:location C8:id
XWIKI-23045ExistingC4:columns
XWIKI-25498NewC4:count C4:columns
XINFRA-525NewL2
XWIKI-25534NewC4:location
XWIKI-23501ExistingE3
XWIKI-25580NewE2

Known issues of this macro

IssueTitleStatusCriteria
XWIKI-13363Remove deprecated macro parameters from the Wysiwyg macro wizardOpenC9

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

Get Connected