Wiki source code of Async Rendering
Last modified by Thomas Mortagne on 2022/12/30 17:36
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{toc/}} | ||
| 2 | |||
| 3 | Since 10.10 XWiki provide various tools to make easier to execute part of the UI asynchronously. | ||
| 4 | |||
| 5 | Support for asynchronous execution is integrated in: | ||
| 6 | |||
| 7 | * Pages (for the execution of the content) | ||
| 8 | * [[Panels>>Extension.Panels Application]] | ||
| 9 | * [[UI extensions>>Extension.UIExtension Module]] | ||
| 10 | * [[Wiki macros>>Extension.WikiMacroStore]] | ||
| 11 | * [[Templates>>Extension.Template Module]] | ||
| 12 | |||
| 13 | There are also two public entry points to manipulate contextual information related to the asynchronous rendering: | ||
| 14 | |||
| 15 | = ##AsyncContext## component = | ||
| 16 | |||
| 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) | ||
| 19 | |||
| 20 | = Async Script Service = | ||
| 21 | |||
| 22 | The ##async## script service expose the ##AsyncContext## API and also add the following: | ||
| 23 | |||
| 24 | * **##flushCache##**: remove from the cache all the result of asynchronous rendering | ||
| 25 | |||
| 26 | = Context entries = | ||
| 27 | |||
| 28 | == Standard context entries == | ||
| 29 | |||
| 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 | ||
| 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}} | ||
| 33 | * ##wiki##: the identifier of the current wiki ({{code language="velocity"}}$xcontext.database{{/code}}) | ||
| 34 | * ##secureDocument##: {{version since="10.11.11, 11.0"}}the reference of the current secure document (which contains the current ##author##){{/version}} | ||
| 35 | * ##request.url##: the URL received by XWiki | ||
| 36 | * ##request.parameters##: the parameters received by XWiki ({{code language="velocity"}}$request.parameterMap{{/code}}) | ||
| 37 | * ##request.base##: the first part of the URL (##<protocol>~://<host:<port>//##//) received by XWiki. Also imply ##request.contextpath##.// | ||
| 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}} | ||
| 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). | ||
| 40 | * ##request.*##: {{version since="12.10"}}all the above request related data{{/version}} | ||
| 41 | * ##locale##: the current locale | ||
| 42 | * ##action##: {{version since="12.10"}}the current action{{/version}} | ||
| 43 | * ##icon.theme##: the current icon theme | ||
| 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}} | ||
| 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}} | ||
| 47 | |||
| 48 | == Custom context entries == | ||
| 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}} | ||
| 63 | |||
| 64 | = Caching = | ||
| 65 | |||
| 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 | |||
| 70 | == Resource which are automatically "used" == | ||
| 71 | |||
| 72 | You won't need to call ###use## API for the following elements: | ||
| 73 | |||
| 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 | ||
| 76 | * {{info}}since 11.8{{/info}} any security right check is associated | ||
| 77 | * {{info}}since 12.9{{/info}} the context document when provided in the async context configuration | ||
| 78 | |||
| 79 | == Force refresh == | ||
| 80 | |||
| 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. |
