async

Last modified by Lucas Charpentier on 2026/10/27 10:26

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.

SourceWhat it givesUsed forWhere
DocumentationParameters, default values and examples, including the most common exampleL2, L3, and the criteria measured with the most common examplehttps://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/macros/async-macro/
Source codeHow the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline supportC4, C5, C7, C8, C9, C13, E4, E6Not recorded yet: search GitHub
Macro descriptorWhat the Edit Macro dialog is built from, on design.xwiki.orgD1, D2, C1 to C9, E4Descriptor, list of macros with their categories
TranslationsThe name, description and parameter names in each languageD1, D2, D4, C1l10n.xwiki.org
Uses in XWiki pagesHow XWiki itself uses the macro, a realistic example when the documentation has noneL3, C2, C3, C6, C8, C9Search the xwiki organization on GitHub
Compared macrosThe audits of the macros of the same typeL1, D3content, html
Other sources specific to this macro
CriterionResultNotes
D1 wordingKOminor: "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 summaryKOminor: 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 categoryKOminor: 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-actionOKQuick 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 consistencyOKcompared 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-parametersOKthe 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-exampleOKthe 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 patternKOcompared 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-configOKsubmitting 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 instantKO"/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 cursorOKafter 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 focusN/Athe content is the only mandatory field, and it is the first one, with the focus in it.
E1 wysiwygKOin 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 errorsKOinvalid 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 nestingKOthe 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-supportOKthe macro declares inline support and renders inside a sentence, with no block element.
E5 emptyKOafter 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 inplaceKOthe 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

ParameterC1 clarityC2 mandatoryC3 defaultsC4 input-assistanceC5 groupsC6 orderC7 alternativesC8 advancedC9 technicalC13 constraintsNotes
$contentOKOKN/AOKN/AOKN/AN/AN/AN/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.

asyncKOOKOKOKOKOKOKOKOKOK

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.

cachedOKOKOKOKOKOKOKOKOKOK

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.

contextKOOKOKKOOKOKOKOKOKKO

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.

idKOOKOKOKOKOKOKKOOKKO

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.

KOCriterionExisting ticketsNew tickets
D1D1 wordingXWIKI-25479
D2D2 summaryXWIKI-25479
D3D3 categoryXWIKI-25479
I1I1 patternXWIKI-25563
I3I3 instantXWIKI-25563
E1E1 wysiwygXWIKI-23034, XWIKI-23947
E2E2 errorsXCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25509 (partial)
E3E3 nestingCKEDITOR-248 (partial), XWIKI-19954 (partial), XWIKI-23034 (partial), XWIKI-23309 (partial)
E5E5 emptyXWIKI-23034
E6E6 inplaceXWIKI-23035XWIKI-25443 (partial)
C1:asyncC1 clarity, asyncXWIKI-23032
C1:contextC1 clarity, contextXWIKI-23033
C4:contextC4 input-assistance, contextXWIKI-16665
C13:contextC13 constraints, contextXWIKI-25509
C1:idC1 clarity, idXWIKI-25479
C8:idC8 advanced, idXWIKI-25480
C13:idC13 constraints, idXWIKI-25509
Success

Every KO is covered by a ticket.

Tickets

TicketOriginKOs coveredKOs partly covered
CKEDITOR-248ExistingE3
XWIKI-19954ExistingE3
XWIKI-23032ExistingC1:async
XWIKI-23033ExistingC1:context
XWIKI-23034ExistingE1 E5E3
XWIKI-23035ExistingE6
XWIKI-23309ExistingE3
XWIKI-23947ExistingE1
XWIKI-16665ExistingC4:context
XCOMMONS-3847NewE2
XRENDERING-823NewE2
XWIKI-25443NewE6
XWIKI-25479NewC1:id D1 D2 D3
XWIKI-25480NewC8:id
XWIKI-25509NewC13:context C13:idE2
XWIKI-25563NewI1 I3

Known issues of this macro

IssueTitleStatusCriteria
XWIKI-23032Async macro editor: Description of `async` parameter should be improvedOpenC1
XWIKI-23033Async macro editor: Description of `context` parameter must be improvedOpenC1
XWIKI-23034Async macro WYSIWYG:By default, the async block is invisible in the editorOpenE5
XWIKI-23035Async macro editor: The content cannot be edited in the MacroEditor.OpenL1
XWIKI-23947Async rendering should be disabled when the WYSIWYG editor doesn't load JavaScript skin extensionsOpenE1

68 more known issues affect every macro: see the Known issues.

Get Connected