Async Macro
Last modified by Thomas Mortagne on 2024/07/05 18:01
 | Asynchronous and cached execution of wiki content. |
| Type | JAR |
| Category | Macro |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | Since XWiki 11.6. |
Description
This macro provide an easy way to execute asynchronously and/or cached wiki content.
Usage
From Wiki Syntax
{{async async="false" cached="true" context="user,doc.reference"}}
content
{{/async}}
content
{{/async}}
Parameters definition
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| async | yes | true/false | true | Enable (true) or disable (false) asynchronous execution |
| cached | yes | true/false | false | Enable (true) or disable (false) caching of the result of the macro content execution |
| context | yes | list | The list of context elements needed for the execution (wiki, user, locale, request.base, doc.reference...). By default no specific information from the context, except the author of the macro, is provided (even if there is a usable context provided to manipulate API which need one). | |
| id | yes | list | generated to be unique for each macro call | A unique id is automatically generated by default (based on the location of the macro) but it's possible to provide a custom one if needed (for example to share the result of an sync block between two different pages). |
Contextual information
As indicated in the parameters table above and in the examples when your script need something from the context you need to explicitly indicate it in the "context" parameter.
However the generated async context still have some default values and fallback logic:
- the context author is always kept for security reasons
- if the context user is not kept explicitly it will be a copy of the author in the async context
- if the context request is not kept explicitly it will be a copy of the first access request and won't be taken into account when generating external URL (same behavior as background threads)
Example
Example 1:
{{async}}
{{velocity}}
Some slow script.
{{/velocity}}
{{/async}}
{{velocity}}
Some slow script.
{{/velocity}}
{{/async}}
Example 2:
{{async context="user"}}
{{velocity}}
Script that need the current user $xcontext.userReference
{{/velocity}}
{{/async}}
{{velocity}}
Script that need the current user $xcontext.userReference
{{/velocity}}
{{/async}}
