documents
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.
| Other sources specific to this macro |
|---|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | |
| D2 summary | KO | minor: "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 category | KO | minor: 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-action | KO | Quick 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 consistency | OK | compared 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-parameters | KO | the 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-example | OK | the 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 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 {{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 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | the macro has no mandatory parameter. The focus is on the first field, Actions. |
| E1 wysiwyg | KO | in 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 errors | KO | every 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 nesting | KO | in 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-support | OK | the macro declares no inline support, and its output is a table with pagination bars, 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| count | OK | OK | OK | KO | KO | OK | N/A | OK | OK | KO | 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)". |
| actions | OK | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | |
| space | KO | OK | OK | OK | KO | OK | KO | OK | KO | N/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. |
| id | KO | OK | OK | OK | KO | OK | N/A | KO | OK | N/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. |
| parent | KO | OK | OK | OK | KO | OK | KO | OK | KO | N/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. |
| columns | KO | OK | KO | KO | KO | OK | N/A | OK | OK | N/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. |
| location | OK | OK | OK | KO | KO | KO | KO | OK | OK | N/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. |
| description | OK | OK | OK | OK | KO | OK | N/A | OK | OK | N/A | |
| filters | KO | OK | OK | OK | KO | OK | N/A | OK | OK | N/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.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| D2 | D2 summary | XWIKI-25470 | |
| D3 | D3 category | XWIKI-25470 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| E1 | E1 wysiwyg | XWIKI-25433 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25580 (partial) | |
| E3 | E3 nesting | XWIKI-23501 | |
| C4:count | C4 input-assistance, count | XWIKI-25182 (partial), XWIKI-25197 (partial) | XWIKI-25498 |
| C5:count | C5 groups, count | XWIKI-25472 | |
| C13:count | C13 constraints, count | XWIKI-25197 | |
| C5:actions | C5 groups, actions | XWIKI-25472 | |
| C1:space | C1 clarity, space | XWIKI-25470 | |
| C5:space | C5 groups, space | XWIKI-25472 | |
| C7:space | C7 alternatives, space | XWIKI-13363 | |
| C9:space | C9 technical, space | XWIKI-13363 | |
| C1:id | C1 clarity, id | XWIKI-25470 | |
| C5:id | C5 groups, id | XWIKI-25472 | |
| C8:id | C8 advanced, id | XWIKI-25472 | |
| C1:parent | C1 clarity, parent | XWIKI-25470 | |
| C5:parent | C5 groups, parent | XWIKI-25472 | |
| C7:parent | C7 alternatives, parent | XWIKI-13363 | |
| C9:parent | C9 technical, parent | XWIKI-13363 | |
| C1:columns | C1 clarity, columns | XWIKI-23116 (partial) | XWIKI-25470 |
| C3:columns | C3 defaults, columns | XWIKI-25472 | |
| C4:columns | C4 input-assistance, columns | XWIKI-23045 (partial) | XWIKI-25498 |
| C5:columns | C5 groups, columns | XWIKI-25472 | |
| C4:location | C4 input-assistance, location | XWIKI-25534 | |
| C5:location | C5 groups, location | XWIKI-25472 | |
| C6:location | C6 order, location | XWIKI-25472 | |
| C7:location | C7 alternatives, location | XWIKI-13363 | |
| C5:description | C5 groups, description | XWIKI-25472 | |
| C1:filters | C1 clarity, filters | XWIKI-25470 | |
| C5:filters | C5 groups, filters | XWIKI-25472 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-13363 | Existing | C9:parent C9:space C7:space C7:parent C7:location | |
| XWIKI-23116 | Existing | C1:columns | |
| XWIKI-25182 | Existing | C4:count | |
| XWIKI-25197 | Existing | C13:count | C4:count |
| XWIKI-25433 | Existing | E1 | |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| XWIKI-25470 | New | C1:filters C1:id C1:parent C1:space D2 D3 C1:columns | |
| XWIKI-25472 | New | C3:columns C5:actions C5:columns C5:count C5:description C5:filters C5:id C5:location C5:parent C5:space C6:location C8:id | |
| XWIKI-23045 | Existing | C4:columns | |
| XWIKI-25498 | New | C4:count C4:columns | |
| XINFRA-525 | New | L2 | |
| XWIKI-25534 | New | C4:location | |
| XWIKI-23501 | Existing | E3 | |
| XWIKI-25580 | New | E2 |
Known issues of this macro
| Issue | Title | Status | Criteria |
|---|---|---|---|
| XWIKI-13363 | Remove deprecated macro parameters from the Wysiwyg macro wizard | Open | C9 |
68 more known issues affect every macro: see the Known issues.
Lucas Charpentier