faq
Last modified by Lucas Charpentier on 2026/10/27 10:28
Audit
- Macro ID
- faq
- Source
- FAQ Application
- Type
- Generator
- Classification reason
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- liveData documents
Lucas CharpentierSources
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 | "FAQ" is the acronym users know and the name of the application the macro comes from, so it is the word a user searches for. |
| D2 summary | KO | "Lists FAQ entries" restates the name with a verb. It does not say that the entries are shown in a table the reader can sort and filter, and it misses a rule the user needs to insert the macro: only the entries of the space given in the filter are listed, so without a filter the macro lists nothing, see I2. The French and German descriptions are left in English. |
| D3 category | KO | the macro has no category: the macro list gives it an empty category, so it appears in no category of the Insert Macro dialog. Like documents and liveData, the other macros that list data, it belongs in Content, where a user looking for a list of entries would look. |
| D4 quick-action | KO | Quick Actions finds the macro first for its ID and name "faq", which are the same. The synonyms "faq list", "frequently asked questions", "questions" and "answers" give no result in Quick Actions nor in the Insert Macro dialog, "frequently asked questions" being what the acronym stands for. The French and German names are "FAQ", as in English, an acronym that needs no translation. |
| L1 consistency | OK | compared with liveData and documents, the other generators that list data. Like them, no parameter is mandatory, there is no content, and Quick Actions inserts the macro right away, with no dialog. Like liveData without a source, it lists nothing until its parameter is set, see I2. |
| L2 doc-parameters | KO | the macro is documented only on the legacy extensions.xwiki.org page of the FAQ Application, in its FAQ Macro section: a search of the new documentation tree on www.xwiki.org by the macro name and by its topic finds no page about it. The filter is described in a sentence, "filter allows specifying some filtering parameters", with no parameter table, default or mandatory flag. Its keys, space and tag, appear only in the examples, and the page does not say that a space is needed to list anything. |
| L3 doc-example | KO | minor: the Usage line {{faq filter="..."/}} is a template, not an example. The three examples are fragments of the form filter="space=FAQ" in a list, not macro calls, with a screenshot of the result. The most common one, filter="space=FAQ", renders both entries of the fixture. But filter="tag=test", documented as listing the entries having a test tag, lists nothing: with a test tag on one of the two entries, space=FAQ&tag=test lists it and tag=test alone lists nothing, since the results page of the macro always filters on the space, see the miscSources. Only the third example does what its text says, besides the first. |
| I1 pattern | OK | like children and liveData, Quick Actions inserts {{faq/}} without a dialog, and the Insert Macro dialog has the single optional field Filter. |
| I2 zero-config | OK | Quick Actions and the dialog submitted with the default values insert {{faq/}} , which renders an empty table in view mode, with the headers, the filter fields and "Results 0 - 0 out of 0", while the wiki holds two FAQ entries and with no hint that a space is needed. There is no error box, and the criterion lets a generator require configuration first, as rated for liveData. In the editor the table shows a warning, see E1. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | the only parameter, Filter, is optional, first and visible with the focus. It is essential, since nothing is listed without space=, but it is the only field of the dialog, which is not the case of the jira server. |
| E1 wysiwyg | KO | in the standalone WYSIWYG editor, ?editor=wysiwyg, the macro shows the frame of the table, the "per page of" and "Page" labels, the headers Question, Created On, Last Modified and Actions, empty filter fields and the warning "The environment prevents the table from loading data.", with no row, right after the insertion and after saving and reopening the page. View mode loads the two entries. The live table scripts are not loaded in the editor, like the Live Data of liveData and the table of notificationsFiltersPreferences. The macro should show an edit-mode replacement, such as the list of its entries or a frame naming the FAQ and its filter, rather than depend on its scripts. |
| E2 errors | KO | every invalid value of filter, checked in a browser with the rows awaited, is accepted silently and gives the same empty table, "Results 0 - 0 out of 0", with no message: an unknown key (bogus=1), an unknown space (space=NoSuchSpace), a wrong case (space=faq), a key without a value (tag=), a key without an equal sign (space), spaces around the equal sign (space = FAQ), plain text (maybe) and an empty filter. The results page lists nothing without an exact space. |
| E3 nesting | KO | in a list item and in a table cell, the macro is inline and renders "The [faq] 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 table with pagination bars, which cannot be inside a sentence: in a sentence it renders the standalone error, as expected. |
| 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| filter | KO | OK | OK | OK | OK | OK | N/A | OK | OK | KO | C1: the name is the ID, "filter", and the description, "Provides ability to filter where the FAQ entries are looked for. For example the following will look for FAQ entries only in the FAQ space: filter="space=FAQ"", reads as an optional narrowing while the macro lists nothing without it. It does not explain the mini-syntax: that the keys are space and tag, that several are joined with an ampersand, as in space=FAQ&tag=test, that the space is needed and must have the exact case, and that spaces around the equal sign break the filter. The French and German texts are left in English. C3: the field opens empty, and the macro then lists nothing, while every example sets space=FAQ. Not counted: the filter is almost mandatory and is the only field, which is fine, as for source of liveData. C4: a plain text field for a key=value list, whose values are a space and a tag. Not counted: a picker for a mini-syntax is overkill, and explaining it, see C1, is the fix. C13: the format, keys space and tag joined with an ampersand, is not declared, and a wiki macro cannot declare one, see XWIKI-25197 in the Cross-macro findings. Every invalid value is accepted and gives an empty table with no message, see E2. |
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 | FAQ-39 | |
| D3 | D3 category | FAQ-39 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| L3 | L3 doc-example | XINFRA-526 | |
| E1 | E1 wysiwyg | FAQ-8, XWIKI-25433 | |
| E2 | E2 errors | XWIKI-25197 (partial), FAQ-34 (partial) | XCOMMONS-3847 (partial), XRENDERING-823 (partial) |
| E3 | E3 nesting | XWIKI-23501 | |
| C1:filter | C1 clarity, filter | XWIKI-6061 (partial) | FAQ-39 |
| C13:filter | C13 constraints, filter | XWIKI-25197 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| FAQ-8 | Existing | E1 | |
| XWIKI-25197 | Existing | C13:filter | E2 |
| XWIKI-25433 | Existing | E1 | |
| XWIKI-6061 | Existing | C1:filter | |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| FAQ-39 | New | D2 D3 C1:filter | |
| XINFRA-525 | New | L2 | |
| XINFRA-526 | New | L3 | |
| XWIKI-23501 | Existing | E3 | |
| FAQ-34 | Existing | E2 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
