figureCaption
Last modified by Lucas Charpentier on 2026/10/27 10:28
Audit
- Macro ID
- figureCaption
- Source
- Figure Macro
- Type
- Wrapper
- Classification reason
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- figure footnote
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 | |
| D2 summary | KO | minor: "Provide a figure caption when used inside the Figure macro." repeats the name and only adds where the macro goes. It does not say where the caption is shown, below or above the content of the figure, nor that it must be the first or last element of the figure. |
| D3 category | KO | the macro is in the Development category, like figure, while a user looking for a way to caption an image or a table would look in Layout or Content, as noted for figure. |
| D4 quick-action | KO | Quick Actions finds the macro first for "figureCaption", "Figure Caption", "caption" and "image caption". The synonyms "legend", "figure title" and "table caption" give no result. The macro name and description are not translated: French and German show "Figure Caption" and the English description, so no other language finds the macro with a different word, like figure. |
| L1 consistency | OK | compared with figure and footnote. Like footnote, the content is mandatory with no default and typed in the dialog from the Quick Action, which is by design since an empty caption gives nothing to show. Figure has an optional content and is inserted directly. |
| L2 doc-parameters | KO | the macro is documented only on the legacy extensions.xwiki.org Figure Macro page, with no page in the new documentation. Its parameter table lists only type, which is a parameter of figure: the content of the caption is not documented. Its Usage examples show the caption. |
| L3 doc-example | OK | the documentation shows the caption first and last in a figure, with an image, a table and a lemma, and these examples render. The first examples use placeholder text, "...caption content here". |
| I1 pattern | KO | the reference wrapper, warning, is inserted by its Quick Action without a dialog. The Figure Caption Quick Action opens the Edit Macro dialog, see I3, the generic behavior of macros without a dedicated Quick Action, like footnote. Nothing in the editor tells that the macro only works inside a figure: it is inserted anywhere and renders "The figure caption must be located inside a figure macro." there. |
| I2 zero-config | OK | |
| I3 instant | KO | inserting from the Quick Actions menu with "/figure caption" and Enter opens the Edit Macro dialog with an empty Content text area, the only field; the macro is only inserted after typing a text and submitting. |
| I4 cursor | KO | after submitting the dialog, the macro widget is selected and the cursor is not in its content: text typed right away goes nowhere. |
| I5 focus | N/A | the only parameter is the mandatory content, shown at the top of the dialog without scrolling. |
| E1 wysiwyg | OK | the editor shows the caption as a plain paragraph under the table, like view mode, also after saving and reopening the page. Nothing marks it as a caption: its widget is only labeled "macro:figureCaption widget" for assistive technologies, and no placeholder says what it is. It is recorded OK like the other wrappers whose content is edited in place, but a user cannot tell the caption from a paragraph. |
| E2 errors | N/A | the macro has no parameter and accepts any text as content, so there is no invalid value to test. A caption that is neither the first nor the last element of the figure gives a clear error in view mode: "The figure caption must be the first or last element of the figure." |
| E3 nesting | KO | the caption works with bold text, a link, several paragraphs, a list, a table and a box in its content, inside a figure, in view mode and in the editor. The whole figure with its caption renders in a box, but in a list item and in a table cell the figure renders "The [figure] macro is a standalone macro and it cannot be used inline." as noted for figure, and a caption alone there renders the figure caption error. The KO is shared with figure. |
| E4 inline-support | OK | the macro does not support the inline mode and renders an error block inside the sentence when used inline, which is expected since a figure is a block. |
| E5 empty | OK | after emptying the content, the area keeps a visible height, one click enters it and the text typed goes into the caption. An empty caption saves and renders no error. |
| E6 inplace | KO | the content is edited in place, but the Edit Macro dialog of an existing caption still shows it as a wiki syntax text area, like figure and box. |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| $content | KO | OK | N/A | OK | N/A | OK | N/A | N/A | N/A | N/A | C1, minor: the description "Caption content" only repeats the name of the parameter. It does not say that the content is shown as the caption of the figure, nor that it accepts wiki syntax and blocks like lists and tables. |
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 | XFIGURE-7 | |
| D3 | D3 category | XFIGURE-7 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| I1 | I1 pattern | XWIKI-25563 | |
| I3 | I3 instant | XWIKI-25563 | |
| I4 | I4 cursor | XWIKI-25569 | |
| E3 | E3 nesting | XWIKI-23501 | |
| E6 | E6 inplace | XWIKI-25443 | |
| C1:$content | C1 clarity, $content | XFIGURE-7 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-23501 | Existing | E3 | |
| XWIKI-25443 | New | E6 | |
| XWIKI-25444 | New | D4 | |
| XFIGURE-7 | New | C1:$content D2 D3 | |
| XINFRA-525 | New | L2 | |
| XWIKI-25563 | New | I1 I3 | |
| XWIKI-25569 | New | I4 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
