Async Macro

Last modified by Thomas Mortagne on 2024/03/19 09:16

cogAsynchronous and cached execution of wiki content.
TypeJAR
CategoryMacro
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU 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}}

Parameters definition

NameOptionalAllowed valuesDefault valueDescription
asyncyestrue/falsetrueEnable (true) or disable (false) asynchronous execution
cachedyestrue/falsefalseEnable (true) or disable (false) caching of the result of the macro content execution
contextyeslist 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).
idyeslistgenerated to be unique for each macro callA 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}}

Example 2:

{{async context="user"}}
{{velocity}}
Script that need the current user $xcontext.userReference
{{/velocity}}
{{/async}}
Tags:
    

Get Connected