cache
Audit
- Macro ID
- cache
- Source
- XS
- Type
- Wrapper
- Classification reason
- The output is the wiki content the user types, parsed and kept for a time: the parameters only change how long and under which key it is kept, never what is shown, so it is classified with the wrappers, like its sibling async, html and content, even though it adds no decoration around the content.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- html content
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Source | What it gives | Used for | Where |
|---|---|---|---|
| Documentation | Parameters, default values and examples, including the most common example | L2, L3, and the criteria measured with the most common example | https://extensions.xwiki.org/xwiki/bin/view/Extension/Cache%20Macro |
| Source code | How the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline support | C4, C5, C7, C8, C9, C13, E4, E6 | Not recorded yet: search GitHub |
| Macro descriptor | What the Edit Macro dialog is built from, on design.xwiki.org | D1, D2, C1 to C9, E4 | Descriptor, list of macros with their categories |
| Translations | The name, description and parameter names in each language | D1, D2, D4, C1 | l10n.xwiki.org |
| Uses in XWiki pages | How XWiki itself uses the macro, a realistic example when the documentation has none | L3, C2, C3, C6, C8, C9 | Search the xwiki organization on GitHub |
| Compared macros | The audits of the macros of the same type | L1, D3 | html, content |
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | the name "Cache" is the name of the technology, which the documentation lists under the developer macros, and the macro is in Development, so it is audited as a developer macro and a technical name is fine. The French name is the same word, which is also the French word. |
| D2 summary | KO | the description "Caches content." repeats the name and adds nothing: it does not say that the result of executing the content is kept for a time and then computed again, nor that the scripts of the content run only once, which is the main limit the documentation gives. A simple wrapper that repeats its name is still a KO. |
| D3 category | OK | the macro is in Development only, like html, which fits a macro for developers. The sibling async, which also caches, is in Content, and its audit notes that users who know the technology look for the cache macro in Development. Recorded OK. |
| D4 quick-action | OK | Quick Actions finds the macro first for "cache" and "Cache", and the German name "Pufferspeicher" comes first too. The French name is the same word as the English one, so it is not counted, and the German name is enough. The synonyms "cache content", "memoize output", "store rendering", "remember result", "cache result" and "save output" give nothing. For a technical macro named after its technology few synonyms finding it is acceptable, as for html and async. The Insert Macro dialog is not counted. |
| L1 consistency | OK | compared with html and content, the compared macros of async. Like html, the Quick Actions entry opens the Edit Macro dialog with a required Content text area, while content is inserted at once; an empty cache macro makes no sense, so the difference is by design. Like html, it is in Development. |
| L2 doc-parameters | KO | the parameters are documented only on the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/Cache%20Macro, and there is no page in the new documentation, unlike its sibling async. The page lists id, timeToLive and maxEntries, and its defaults match the descriptor: the checker flags "300 seconds (5 minutes)" against 300, which is the same value. It does not list the content, and it gives a default for id, the content itself, that the descriptor leaves empty. |
| L3 doc-example | KO | minor: the audit example is Example 2 of the documentation, {{cache id="myuniqueid"}}content to cache here...{{/cache}} , the first example with real values, since Example 1 is a syntax template with placeholders, id="...", that fails with "ISPN000424: Memory eviction is enabled, please specify a maximum size or count greater than zero" when copied. Examples 2 to 6 render without error, but they all cache the text "content to cache here...": none shows the real use, the result of a slow script, which only the Limitations paragraph describes, and the GitHub code search of the xwiki organization found no call of the macro in XWiki Standard to compare with. Async shows its real uses, with velocity content, in its examples. |
| I1 pattern | KO | compared with warning, the reference wrapper, and with html. The Quick Actions entry "Cache" opens the Edit Macro dialog instead of inserting the macro at once with an area to type in, like the Quick Action of html and async, see I3. |
| I2 zero-config | OK | submitting the Edit Macro dialog with the default values keeps it open with no message, the generic behavior, since the content is mandatory. A cache with an id and an empty content, {{cache id="x"}}{{/cache}} , renders nothing in view mode and shows the visible "macro:cache" placeholder in the editor, as html does. {{cache/}} written in the source, with no content and no id, renders "Failed to execute the [cache] macro. Cause: [Null keys are not supported!]", a raw message, kept as a bug outside the criteria since the dialog does not insert an empty content. |
| I3 instant | KO | "/cache" then Enter opens the Edit Macro dialog with an empty Content text area. The macro is only inserted after typing the content and submitting, unlike warning, which is inserted at once with its content area. |
| I4 cursor | KO | after submitting the dialog the macro widget is selected and the cursor is not in the content: typing "TYPED" after inserting the macro with the content "Probe content" changes nothing, the page stays {{cache}}Probe content{{/cache}} , and the content can only be changed through the dialog, see E6. |
| I5 focus | N/A | |
| E1 wysiwyg | OK | in the editor the macro shows its rendered content, "content to cache here..." for the audit example, in a widget whose generic "macro:cache" label is hidden, and the status bar shows macro:cache. The output is the content the user typed, as for html, so there is nothing else to replace. |
| E2 errors | KO | the invalid values of the number parameters are not handled. maxEntries with "abc", "-3", "0" or "2.5" renders "Failed to execute the [cache] macro. Cause: [ISPN000424: Memory eviction is enabled, please specify a maximum size or count greater than zero]", the same message as the first example of the documentation, which does not name the parameter. timeToLive with "abc", "-3" or "0" is accepted silently and the content renders as for a valid value, since the source only stores the number. An id with a space, "my id", is accepted, which is valid for a key written as text. An unknown parameter is accepted, which is generic. |
| E3 nesting | KO | the macro renders in a list item, a table cell and a box with no error, and a list, a table and a box as its content render in view mode. But its content can never be edited in place in these cases, only through the Edit Macro dialog, see E5 and E6, which is the same call as for its sibling async. The "True, False" of the box row of the probe is the editable area of the box, not the macro content: the macro is a non-editable widget in every case. |
| E4 inline-support | OK | the macro declares inline support and renders inside a sentence with no error, Before {{cache id="e4x"}}inline text{{/cache}} after. gives "Before inline text after.". |
| E5 empty | KO | minor: an empty macro, {{cache id="x"}}{{/cache}} , shows a visible "macro:cache" placeholder that one click selects but that never receives the cursor. With a content, the editor shows the output in a widget that is not editable either, see E6. |
| E6 inplace | KO | the content is never edited in place, not even right after the insertion, see I4: the editor shows the rendered content, and changing it needs the Edit Macro dialog, where it is a plain text area in the syntax of the page. A content with bold text and a list, submitted unchanged, is saved unchanged, so the dialog does not corrupt it. |
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 | OK | OK | N/A | OK | N/A | OK | N/A | N/A | N/A | N/A | C1: "Content" with "The content to cache." says what to type. C2: mandatory, since an empty cache macro renders nothing, see I2. C4: a plain text area in the Edit Macro dialog, counted under E6. |
| id | KO | OK | OK | OK | OK | OK | OK | OK | OK | OK | C1, minor: "Id" with "A unique id under which the content is cached." says what the value is, which is enough for a developer hook. It does not say that an empty id uses the content itself as the key, which the documentation does and the documentation also warns that the content does not guarantee unicity. Nor does it say that the id is read as wiki syntax and then rendered as plain text, so that a script macro can generate it, which is why examples 3, 4 and 6 of the documentation escape the macro, id="~{~{velocity~}~}$myid~{~{/velocity~}~}" : the escaping of the macro is the part users get wrong. In French and German the name is the ID in English too. C3: empty. The default of the documentation, the content itself, is computed from the content and cannot be preselected, and the first example of the documentation sets an id, so the empty field does not hide a value that users would otherwise keep. C8: every example of the documentation sets an id, so it stays visible. |
| maxEntries | OK | OK | OK | KO | OK | OK | OK | KO | OK | OK | C1: "MaxEntries" is the ID title-cased in the dialog, and the description "The maximum number of entries in the cache (Least Recently Used entries are ejected)." explains it, which is enough for a developer macro. The name is the ID in English in the translations, in French too. C3: 1000, the default of the macro, which is the usual value. C4: a text field for a number, where a number input would only accept numbers. The values "abc", "-3" and "0" reach the macro and end with the error of E2. C8: no example of the documentation sets it, and the cache it sizes is shared by every call with the same time to live and the same size, so it is a rare tuning, shown with the main options instead of as an advanced parameter. C9: realistic use, for a macro that caches many different contents, so it stays visible. |
| timeToLive | OK | OK | OK | KO | OK | OK | OK | OK | OK | OK | C1: "TimeToLive" is the ID title-cased in the dialog, and "The number of seconds to cache the content." gives the unit, which is enough for a developer macro. C3: 300, the default of the macro, 5 minutes, which is the usual value. C4: a text field for a number, where a number input would only accept numbers. The values "abc", "-3" and "0" are accepted silently, see E2. C6: after maxEntries, though examples 5 and 6 of the documentation set it and none sets maxEntries. With three visible fields, none is hard to reach. |
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-25479 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| L3 | L3 doc-example | XINFRA-526 | |
| I1 | I1 pattern | XWIKI-25563 | |
| I3 | I3 instant | XWIKI-25563 | |
| I4 | I4 cursor | XWIKI-25569 | |
| E2 | E2 errors | XWIKI-25182 (partial) | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25582 (partial) |
| E3 | E3 nesting | CKEDITOR-248 (partial), XWIKI-19954 (partial), XWIKI-23309 (partial) | XWIKI-25567 (partial) |
| E5 | E5 empty | XWIKI-25567 | |
| E6 | E6 inplace | XWIKI-25443 (partial), XWIKI-25567 | |
| C1:id | C1 clarity, id | XWIKI-25479 | |
| C4:maxEntries | C4 input-assistance, maxEntries | XWIKI-25182 | |
| C8:maxEntries | C8 advanced, maxEntries | XWIKI-25480 | |
| C4:timeToLive | C4 input-assistance, timeToLive | XWIKI-25182 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-25182 | Existing | C4:maxEntries C4:timeToLive | E2 |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25443 | New | E6 | |
| XWIKI-25479 | New | C1:id D2 | |
| XWIKI-25480 | New | C8:maxEntries | |
| XINFRA-525 | New | L2 | |
| XINFRA-526 | New | L3 | |
| CKEDITOR-248 | Existing | E3 | |
| XWIKI-19954 | Existing | E3 | |
| XWIKI-23309 | Existing | E3 | |
| XWIKI-25563 | New | I1 I3 | |
| XWIKI-25567 | New | E6 E5 | E3 |
| XWIKI-25569 | New | I4 | |
| XWIKI-25582 | New | 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.
