Wiki source code of Async Rendering

Last modified by Thomas Mortagne on 2022/12/30 17:36

Hide last authors
Thomas Mortagne 9.1 1 {{toc/}}
2
Thomas Mortagne 2.1 3 Since 10.10 XWiki provide various tools to make easier to execute part of the UI asynchronously.
Thomas Mortagne 1.1 4
5 Support for asynchronous execution is integrated in:
6
Thomas Mortagne 13.1 7 * Pages (for the execution of the content)
Thomas Mortagne 2.1 8 * [[Panels>>Extension.Panels Application]]
9 * [[UI extensions>>Extension.UIExtension Module]]
10 * [[Wiki macros>>Extension.WikiMacroStore]]
Vincent Massol 15.2 11 * [[Templates>>Extension.Template Module]]
Thomas Mortagne 1.1 12
Vincent Massol 15.2 13 There are also two public entry points to manipulate contextual information related to the asynchronous rendering:
Thomas Mortagne 1.1 14
Thomas Mortagne 6.1 15 = ##AsyncContext## component =
Thomas Mortagne 1.1 16
Thomas Mortagne 3.1 17 * **##is/setEnabled##**: indicate if asynchronous rendering is allowed in the current context (for example it's disabled when doing HTML export)
18 * **##use*##** methods: indicate what kind of elements is used in the current context so that it's registered with the cached rendering to know when to invalidate it (for example XWiki#getDocument register the loaded document so that the cached content which needed to load that document is automatically invalidate when the document is modified in any way)
Thomas Mortagne 1.1 19
Vincent Massol 15.5 20 = Async Script Service =
Thomas Mortagne 1.1 21
Vincent Massol 15.4 22 The ##async## script service expose the ##AsyncContext## API and also add the following:
Thomas Mortagne 1.1 23
Thomas Mortagne 3.1 24 * **##flushCache##**: remove from the cache all the result of asynchronous rendering
Thomas Mortagne 7.2 25
Thomas Mortagne 14.1 26 = Context entries =
Thomas Mortagne 7.2 27
Thomas Mortagne 14.1 28 == Standard context entries ==
Thomas Mortagne 7.2 29
Thomas Mortagne 14.1 30 * ##user##: the reference of the current user ({{code language="velocity"}}$xcontext.userReference{{/code}}), fallback on the author when not set
31 * ##author##: the reference of the author of the currently executed script (##XWikiContext#getAuthorReference##), superadmin if not set
Thomas Mortagne 23.2 32 * ##doc.reference##: the reference of the current document ({{code language="velocity"}}$doc.documentReference{{/code}}), the wiki home page if not set. {{version since="12.9"}}the context document is also automatically associated with the cached result and invalidated when the document is modified.{{/version}} {{version since="12.10"}}the wiki of the document is used to set the context wiki and it's not saved.{{/version}}
Thomas Mortagne 7.2 33 * ##wiki##: the identifier of the current wiki ({{code language="velocity"}}$xcontext.database{{/code}})
Thomas Mortagne 23.3 34 * ##secureDocument##: {{version since="10.11.11, 11.0"}}the reference of the current secure document (which contains the current ##author##){{/version}}
Thomas Mortagne 7.2 35 * ##request.url##: the URL received by XWiki
36 * ##request.parameters##: the parameters received by XWiki ({{code language="velocity"}}$request.parameterMap{{/code}})
Thomas Mortagne 14.1 37 * ##request.base##: the first part of the URL (##<protocol>~://<host:<port>//##//) received by XWiki. Also imply ##request.contextpath##.//
Thomas Mortagne 23.3 38 * ##request.contextpath##: {{version since="10.11.11, 11.0"}}the part following the base URL (usually ##xwiki## unless the configuration has been changed){{/version}}
Thomas Mortagne 8.1 39 * ##request.wiki##: the wiki corresponding to the URL received by XWiki (could be different from the current wiki when the async execution is triggered).
Thomas Mortagne 23.2 40 * ##request.*##: {{version since="12.10"}}all the above request related data{{/version}}
Thomas Mortagne 7.2 41 * ##locale##: the current locale
Thomas Mortagne 23.2 42 * ##action##: {{version since="12.10"}}the current action{{/version}}
Thomas Mortagne 7.2 43 * ##icon.theme##: the current icon theme
Thomas Mortagne 23.3 44 * ##rendering.defaultsyntax##: {{version since="11.8"}}the value of ##org.xwiki.rendering.transformation.RenderingContext#getTargetSyntax##{{/version}}
45 * ##rendering.targetsyntax##: {{version since="11.8"}}the value of ##org.xwiki.rendering.transformation.RenderingContext#getDefaultSyntax##{{/version}}
Thomas Mortagne 24.1 46 * ##rendering.restricted##: {{version since="13.10.11, 14.4.8, 14.10.3, 15.0-rc-1"}}the value of ##org.xwiki.rendering.transformation.RenderingContext#isRestricted##{{/version}}
Thomas Mortagne 7.2 47
Thomas Mortagne 14.1 48 == Custom context entries ==
Thomas Mortagne 7.2 49
50 Any extension can provide its own context elements. For this you will need to provider a component implementing the role ##org.xwiki.context.concurrent.ContextStore## and have any unique role hint:
51
52 * ##getSupportedEntries##: the names of the context entries supported by the ContextStore
53 * ##save##: save only the passed context entries in the passed map
54 * ##restore##: inject in the current context data found in the passed map
55
56 You can provide display names for these properties in the form of translations of the form ##rendering.async.context.entry.<key>##.
57
58 For example:
59
60 {{code language="properties"}}
61 rendering.async.context.entry.wiki=Wiki
62 {{/code}}
Thomas Mortagne 11.1 63
Thomas Mortagne 14.1 64 = Caching =
Thomas Mortagne 11.1 65
Thomas Mortagne 12.1 66 When you enable cache the result of the execution will be stored in a memory cache and automatically invalidated when an event related to one of the associated resources (document, components, etc.) is received.
67
68 XWiki is doing its best to automatically associate many things but sometimes it's not easy to do it automatically (for example when you use database requests) and you will need to be a bit more explicit. For this you can use the various "use" API described in previous sections.
69
Thomas Mortagne 14.1 70 == Resource which are automatically "used" ==
Thomas Mortagne 12.1 71
Thomas Mortagne 11.1 72 You won't need to call ###use## API for the following elements:
Thomas Mortagne 14.1 73
Thomas Mortagne 11.1 74 * anything that end up calling ##XWiki#getDocument## will automatically cause the document reference to be associated
75 * any lookup for a component or a component list will automatically be associated
Simon Urli 15.1 76 * {{info}}since 11.8{{/info}} any security right check is associated
Thomas Mortagne 17.1 77 * {{info}}since 12.9{{/info}} the context document when provided in the async context configuration
Thomas Mortagne 12.1 78
Simon Urli 15.1 79 == Force refresh ==
Thomas Mortagne 12.1 80
Simon Urli 15.1 81 {{info}}since 11.8{{/info}} It's possible to force skipping the cache by sending the HTTP header ##Cache-Control## with value "no-cache". Fortunately this is something the browser does when you force refresh (##SHIFT+F5## or ##CTRL+SHIFT+R## usually) so using forcing refresh in your browser will not only affect the browser cache but also the async rendering server side cache.

Get Connected