"async" Macro
Reference
Description
The async macro executes the wiki content it wraps asynchronously, caches the result of that execution, or both. In the macro list of the editors it appears as "Async", in the "Content" category.
Executing asynchronously means XWiki serves the page without waiting for the content: a placeholder is rendered in its place and replaced once the result is ready, so one slow block no longer holds back the whole page. Caching means the result of an execution is kept and reused the next times the page is displayed, instead of being computed again. The two are independent, and the macro can do either on its own. Async Rendering describes the framework behind both.
The macro works inline as well as standalone, so it can wrap a fragment inside a sentence.
Usage
{{async}}
The content to execute.
{{/async}}The content is mandatory, and it is executed as wiki content. A macro whose content is empty displays nothing at all rather than reporting an error.
What the content does not get by default is the context of the page displaying it: only the author of the content, and the document its rights are checked against, are always kept. Anything else a script needs has to be named in the context parameter, which is where this macro is most often got wrong. The standard context entries are the values that parameter accepts.
Two fallbacks apply to whatever is left out:
- when user is not kept, the current user of the asynchronous execution is a copy of the author
- when no request entry is kept, the request is a copy of the one from the first access, and it is ignored when external URLs are generated, the same way a background thread behaves
Parameters
| Name | Mandatory | Allowed Values | Default Value | Description |
|---|---|---|---|---|
| content | yes | wiki content | none | The content the macro executes. Nothing is displayed when it is empty. |
| async | no | true or false | true | Whether the content is executed asynchronously. Set it to false to keep the content in the page rendering and still benefit from cached. |
| cached | no | true or false | false | Whether the result of the execution is kept and reused for the next displays. |
| context | no | a comma-separated list of context entry names | none | The context entries the content needs in order to execute, for example user, wiki, locale, doc.reference or request.base. Nothing beyond the author and the document the rights are checked against is kept when the parameter is left out. |
| id | no | a comma-separated list of strings | generated from the position of the macro in the page | The identifier the cached result is stored under. Give an explicit one to share a single result between several pages. |
Examples
Executing a Slow Script Asynchronously
The page is served immediately and the result of the script replaces the placeholder once it is ready.
{{async}}
{{velocity}}
Some slow script.
{{/velocity}}
{{/async}}Giving the Content the Current User
The script reads the current user, so user has to be named in the context parameter. Without it the script would see the author of the content instead.
{{async context="user"}}
{{velocity}}
Script that needs the current user $xcontext.userReference
{{/velocity}}
{{/async}}Caching a Result That Rarely Changes
The result is computed once and reused for the next displays. Caching works whether the content is executed asynchronously or not.
{{async cached="true" context="wiki"}}
{{velocity}}
An expensive count that is the same for every reader of the wiki.
{{/velocity}}
{{/async}}FAQ
Why does the script inside the macro not see the current document?
Only the author of the content and the document its rights are checked against are kept by default. Name the entries the script needs in the context parameter, doc.reference in this case.
Does setting async to false also disable caching?
No, the two parameters are independent. With async="false" and cached="true" the content is executed while the page is rendered and its result is still reused for the next displays.
