async
Audit
- Macro ID
- async
- Source
- XS
- Type
- Wrapper
- Classification reason
- The output is the wiki content the user types, executed in the background or kept in a cache: the parameters only change how it is executed, never what is shown, so it is classified with the wrappers, like 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
- content html
Sources
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://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/macros/async-macro/ |
| 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 | content, html |
| Other sources specific to this macro |
|---|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | KO | minor: "Async macro" is a developer term, and it names only one of the two things the macro does, the other one being the cache of the result; the documentation lists it under the developer macros, but the macro is in the user category Content, so it is audited as a user macro. The cache macro, which is in Development, shows that users who know the technology look for it there. |
| D2 summary | KO | minor: the description "Execute asynchronously and/or cache the macro content." repeats the name, "asynchronously", and uses the same jargon; it adds only the cache and does not say what the reader gets, the page showing at once and the slow content replacing a placeholder when it is ready. |
| D3 category | KO | minor: the macro is in Content, like content, include and display, which fits a macro that wraps wiki content. The compared macros are in different categories, content in Content and html in Development, so the measure gives no single category. Users who look for what the macro is used for, slow scripts, find velocity, groovy, html and the cache macro in Development, and the macro is not listed there. |
| D4 quick-action | OK | Quick Actions finds the macro first for "async" and "Async macro", and the German name "Asynchrones Makro" comes first too. The French name "macro async" gives nothing. The synonyms "asynchronous" and "cache" give the macro second, after "job" and after "Cache", and "background", "deferred" and "lazy loading" give nothing. Recorded OK: the name, the ID and the name in German are found, and for a technical macro named after its technology few synonyms finding it is acceptable, as for html. |
| L1 consistency | OK | compared with content and html. Like html, the Quick Actions entry opens the Edit Macro dialog with a required Content text area, since an empty async macro shows nothing; content is inserted at once. The difference is by design. |
| L2 doc-parameters | OK | the new documentation, https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/macros/async-macro/, lists the five parameters with their defaults. The default of id is only in the documentation, "generated from the position of the macro in the page", and the dialog description says the same. |
| L3 doc-example | OK | the four examples of the documentation render without error. The first one, {{async}}The content to execute.{{/async}} , is the audit example: it renders but shows nothing of what the macro does. The velocity examples with context="user" and cached="true" show the real uses, and the page explains why context is needed. |
| I1 pattern | KO | compared with warning, the reference wrapper, and with html. The Quick Actions entry "Async macro" opens the Edit Macro dialog instead of inserting the macro at once with an area to type in, like the Quick Action of html, see I3. |
| I2 zero-config | OK | submitting the Edit Macro dialog with the default values keeps it open with no message, the generic behavior, and an empty content shows nothing, which the documentation states: {{async/}} renders nothing, with no error. |
| I3 instant | KO | "/async" 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 | OK | after submitting the dialog the cursor is in the content: typing "TYPED" gives {{async}}TYPEDProbe content{{/async}} , and the editor shows the content in place with no placeholder. |
| I5 focus | N/A | the content is the only mandatory field, and it is the first one, with the focus in it. |
| E1 wysiwyg | KO | in the editor the macro is only the generic "macro:async" placeholder, never the content, even after waiting 10 seconds: the asynchronous container the editor puts under the placeholder stays empty. View mode shows the content. An async macro needs a semantic replacement in edit mode, like the other macros that need JavaScript to render. |
| E2 errors | KO | invalid values are accepted silently, with no message, and the content renders as for a valid one. {{async async="maybe"}} and {{async cached="maybe"}} are read as booleans. {{async context="nosuchctx"}} , {{async context="User"}} and {{async context="user wiki"}} are accepted, though the context entries are a fixed list in lower case separated by commas, and the unknown entry is ignored as the source shows. {{async id="my id"}} and {{async id="a,b"}} are accepted, the second one as two identifiers. |
| 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, like content, whose content cannot be edited in place in a list item and a table cell either. |
| E4 inline-support | OK | the macro declares inline support and renders inside a sentence, with no block element. |
| E5 empty | KO | after the page is saved and reopened, the macro is a "macro:async" placeholder with no content area, so the cursor can never be put in it and the content cannot be emptied or retyped in place, as with container. Right after insertion from Quick Actions the content is a real area, see I4, but that state is lost when the page is reopened. |
| E6 inplace | KO | the content is edited in place only right after the macro is inserted. For an existing macro, the only way to change the content is the Edit Macro dialog, where it is a plain text area in the syntax of the page; the content shows in the dialog and a submit without change does not alter it. The same macro therefore behaves differently before and after saving the page. |
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 wiki content to execute." says what to type. C2: mandatory, as the documentation says: an empty content shows nothing. C4: a plain text area in the Edit Macro dialog, counted under E6. |
| async | KO | OK | OK | OK | OK | OK | OK | OK | OK | OK | C1, minor: the name "Async" is jargon, untranslated in French, and the description "Enable or disable asynchronous execution" repeats it without saying what the reader gets, the page appearing at once and the content replacing a placeholder later. C3: the checkbox is checked, the default of the macro, which is the usual use. C8: the parameter is used now and then, for the case of the cache without the asynchronous execution, {{async async="false" cached="true"}} . It sits next to the other options, which is acceptable with five fields. |
| cached | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | C1: "Cached" with "Enable or disable caching of the result of the macro content execution" says what it does, though it does not say when the result is recomputed, and the documentation does not either. C3: the checkbox is unchecked, the default of the macro, and the example of the documentation sets nothing. |
| context | KO | OK | OK | KO | OK | OK | OK | OK | OK | KO | C1: the name is the ID "context", written in lower case in the descriptor, and the description is the same word, "context". It does not say what to type, nor that the content only sees the author and the document of its rights by default, which the documentation calls the place where the macro is most often got wrong. In French and German the name and the description are in English too. C3: empty, which is the value of the most common example. C4: a text field for a list of context entries, "user", "wiki", "locale", "doc.reference" or "request.base", that the documentation lists and that components extend. A multiple select of the available entries would show them and avoid the wrong case or the unknown entry that E2 shows is accepted. C8: most calls that run a script need it, the documentation says it is the usual mistake, so it stays visible. C13: the value is a comma-separated list of entry names, which neither the name nor the description says. A value with a space or in the wrong case is accepted silently. |
| id | KO | OK | OK | OK | OK | OK | OK | KO | OK | KO | C1, minor: "Identifier" with "The identifier associated with the content. If left empty it's deduced from the macro location." says it is deduced when empty, which is enough for a technical hook, but not that it is the key of the cached result, so only useful with cached="true", nor that several can be given. The French name, "Ecraser l'identifiant", and the German one, "ID überschreiben", say "override", unlike the English one. C3: empty, and the description says the identifier is deduced from the macro location. C8: the parameter shares one cached result between several pages, a rare need, and no call of the macro in XWiki Standard sets it, but it is shown with the main options instead of as an advanced parameter. C13, minor: the value is a list of identifiers separated by commas, which the dialog does not say. A value with a space, "my id", or with a comma, "a,b", is accepted silently, 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 |
|---|---|---|---|
| D1 | D1 wording | XWIKI-25479 | |
| D2 | D2 summary | XWIKI-25479 | |
| D3 | D3 category | XWIKI-25479 | |
| I1 | I1 pattern | XWIKI-25563 | |
| I3 | I3 instant | XWIKI-25563 | |
| E1 | E1 wysiwyg | XWIKI-23034, XWIKI-23947 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25509 (partial) | |
| E3 | E3 nesting | CKEDITOR-248 (partial), XWIKI-19954 (partial), XWIKI-23034 (partial), XWIKI-23309 (partial) | |
| E5 | E5 empty | XWIKI-23034 | |
| E6 | E6 inplace | XWIKI-23035 | XWIKI-25443 (partial) |
| C1:async | C1 clarity, async | XWIKI-23032 | |
| C1:context | C1 clarity, context | XWIKI-23033 | |
| C4:context | C4 input-assistance, context | XWIKI-16665 | |
| C13:context | C13 constraints, context | XWIKI-25509 | |
| C1:id | C1 clarity, id | XWIKI-25479 | |
| C8:id | C8 advanced, id | XWIKI-25480 | |
| C13:id | C13 constraints, id | XWIKI-25509 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| CKEDITOR-248 | Existing | E3 | |
| XWIKI-19954 | Existing | E3 | |
| XWIKI-23032 | Existing | C1:async | |
| XWIKI-23033 | Existing | C1:context | |
| XWIKI-23034 | Existing | E1 E5 | E3 |
| XWIKI-23035 | Existing | E6 | |
| XWIKI-23309 | Existing | E3 | |
| XWIKI-23947 | Existing | E1 | |
| XWIKI-16665 | Existing | C4:context | |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25443 | New | E6 | |
| XWIKI-25479 | New | C1:id D1 D2 D3 | |
| XWIKI-25480 | New | C8:id | |
| XWIKI-25509 | New | C13:context C13:id | E2 |
| XWIKI-25563 | New | I1 I3 |
Known issues of this macro
| Issue | Title | Status | Criteria |
|---|---|---|---|
| XWIKI-23032 | Async macro editor: Description of `async` parameter should be improved | Open | C1 |
| XWIKI-23033 | Async macro editor: Description of `context` parameter must be improved | Open | C1 |
| XWIKI-23034 | Async macro WYSIWYG:By default, the async block is invisible in the editor | Open | E5 |
| XWIKI-23035 | Async macro editor: The content cannot be edited in the MacroEditor. | Open | L1 |
| XWIKI-23947 | Async rendering should be disabled when the WYSIWYG editor doesn't load JavaScript skin extensions | Open | E1 |
68 more known issues affect every macro: see the Known issues.
Lucas Charpentier