Wiki source code of Async Rendering

Last modified by Eleni Cojocariu on 2026/11/17 16:50

Show last authors
1 {{velocity}}
2 $xwiki.ssx.use("Documentation.UserGuide.Features.KeyboardShortcuts")
3 {{/velocity}}
4
5 [[Async rendering>>doc:extensions:Extension.Rendering Module.Async.WebHome]] lets XWiki serve a page without waiting for its slow parts, and reuse the result of an expensive rendering instead of computing it again. A part rendered asynchronously is replaced by a placeholder, which is filled in once the result is ready. A cached result is kept in memory and invalidated automatically when one of the resources it used, such as a document or a component, is modified.
6
7 Without async rendering, the reader waits for the slowest part of the page:
8
9 {{plantuml}}
10 !theme bluegray
11 ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under
12 ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm.
13 skinparam activity {
14 BackgroundColor #0568AE
15 BorderColor #034873
16 FontColor #FFFFFF
17 StartColor #04538B
18 EndColor #04538B
19 BarColor #5A5A5A
20 ' Diamonds are blue with white text, not light with dark text: a labelled
21 ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from
22 ' FontColor above, so a light fill draws that one box white on white, and no
23 ' selector reaches it without reaching the decision diamonds too.
24 DiamondBackgroundColor #0568AE
25 DiamondBorderColor #034873
26 DiamondFontColor #FFFFFF
27 }
28 skinparam state {
29 BackgroundColor #0568AE
30 BorderColor #034873
31 FontColor #FFFFFF
32 AttributeFontColor #FFFFFF
33 StartColor #04538B
34 EndColor #04538B
35 }
36 skinparam class {
37 BackgroundColor #0568AE
38 BorderColor #034873
39 FontColor #FFFFFF
40 HeaderBackgroundColor #0568AE
41 AttributeFontColor #FFFFFF
42 StereotypeFontColor #262626
43 }
44 skinparam object {
45 BackgroundColor #0568AE
46 BorderColor #034873
47 FontColor #FFFFFF
48 AttributeFontColor #FFFFFF
49 StereotypeFontColor #262626
50 }
51 skinparam participant {
52 BackgroundColor #0568AE
53 BorderColor #034873
54 FontColor #FFFFFF
55 }
56 skinparam actor {
57 BackgroundColor #F5F5F5
58 BorderColor #5A5A5A
59 FontColor #262626
60 }
61 skinparam component {
62 BackgroundColor #0568AE
63 BorderColor #034873
64 FontColor #FFFFFF
65 }
66 skinparam collections {
67 BackgroundColor #0568AE
68 BorderColor #034873
69 FontColor #FFFFFF
70 }
71 skinparam queue {
72 BackgroundColor #0568AE
73 BorderColor #034873
74 FontColor #FFFFFF
75 }
76 skinparam stack {
77 BackgroundColor #0568AE
78 BorderColor #034873
79 FontColor #FFFFFF
80 }
81 ' database, control, entity, boundary and interface draw their label beside or
82 ' under the icon, on the page, in some diagram types: their text stays dark.
83 skinparam database {
84 BackgroundColor #F5F5F5
85 BorderColor #5A5A5A
86 FontColor #262626
87 }
88 skinparam control {
89 BackgroundColor #0568AE
90 BorderColor #034873
91 FontColor #262626
92 }
93 skinparam entity {
94 BackgroundColor #0568AE
95 BorderColor #034873
96 FontColor #262626
97 }
98 skinparam boundary {
99 BackgroundColor #0568AE
100 BorderColor #034873
101 FontColor #262626
102 }
103 skinparam usecase {
104 BackgroundColor #0568AE
105 BorderColor #034873
106 FontColor #FFFFFF
107 StereotypeFontColor #FFFFFF
108 }
109 skinparam card {
110 BackgroundColor #04538B
111 BorderColor #034873
112 FontColor #FFFFFF
113 }
114 skinparam note {
115 BackgroundColor #04538B
116 BorderColor #034873
117 FontColor #FFFFFF
118 }
119 skinparam storage {
120 BackgroundColor #8A4A00
121 BorderColor #8A4A00
122 FontColor #FFFFFF
123 }
124 skinparam agent {
125 BackgroundColor #8A4A00
126 BorderColor #8A4A00
127 FontColor #FFFFFF
128 }
129 skinparam interface {
130 BackgroundColor #A62222
131 BorderColor #A62222
132 FontColor #262626
133 }
134 skinparam node {
135 BackgroundColor #F5F5F5
136 BorderColor #5A5A5A
137 FontColor #262626
138 }
139 skinparam cloud {
140 BackgroundColor #F5F5F5
141 BorderColor #5A5A5A
142 FontColor #262626
143 }
144 skinparam artifact {
145 BackgroundColor #F5F5F5
146 BorderColor #5A5A5A
147 FontColor #262626
148 }
149 skinparam file {
150 BackgroundColor #F5F5F5
151 BorderColor #5A5A5A
152 FontColor #262626
153 }
154 skinparam rectangle {
155 BackgroundColor #FFFFFF
156 BorderColor #5A5A5A
157 FontColor #262626
158 StereotypeFontColor #0568AE
159 }
160 skinparam folder {
161 BackgroundColor #F5F5F5
162 BorderColor #8A4A00
163 FontColor #8A4A00
164 }
165 skinparam frame {
166 BackgroundColor #F5F5F5
167 BorderColor #04538B
168 FontColor #04538B
169 }
170 skinparam package {
171 BackgroundColor #FFFFFF
172 BorderColor #0568AE
173 FontColor #262626
174 }
175 skinparam partition {
176 BackgroundColor #FFFFFF
177 BorderColor #0568AE
178 FontColor #0568AE
179 }
180 skinparam swimlane {
181 BorderColor #0568AE
182 TitleBackgroundColor #F5F5F5
183 TitleFontColor #0568AE
184 }
185 skinparam sequence {
186 BoxBackgroundColor #F5F5F5
187 BoxBorderColor #5A5A5A
188 BoxFontColor #262626
189 DelayFontColor #262626
190 GroupBorderColor #5A5A5A
191 GroupFontColor #262626
192 LifeLineBorderColor #5A5A5A
193 LifeLineBackgroundColor #F5F5F5
194 TitleFontColor #0568AE
195 StartColor #0568AE
196 EndColor #0568AE
197 BorderColor #0568AE
198 }
199 skinparam arrow {
200 Color #0568AE
201 FontColor #262626
202 }
203 skinparam legend {
204 BackgroundColor #F5F5F5
205 BorderColor #5A5A5A
206 FontColor #262626
207 }
208 skinparam stereotype {
209 CBackgroundColor #F5F5F5
210 CBorderColor #5A5A5A
211 ABackgroundColor #F5F5F5
212 ABorderColor #5A5A5A
213 IBackgroundColor #F5F5F5
214 IBorderColor #5A5A5A
215 EBackgroundColor #F5F5F5
216 EBorderColor #5A5A5A
217 NBackgroundColor #F5F5F5
218 NBorderColor #5A5A5A
219 }
220 skinparam ArrowColor #0568AE
221 ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form
222 ' leaks its background onto every element in the diagram.
223 skinparam titleFontColor #0568AE
224 skinparam titleBorderColor #5A5A5A
225 ' Links otherwise take bluegray's white root colour, unreadable on a light fill.
226 <style>
227 root {
228 HyperLinkColor #0568AE
229 }
230 element {
231 HyperLinkColor #FFFFFF
232 }
233 actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface,
234 legend, node, package, rectangle {
235 HyperLinkColor #0568AE
236 }
237 </style>
238 ' ---- end XWiki accessible diagram palette ----
239 actor Reader
240 participant Browser
241 participant XWiki
242 Reader -> Browser : open page
243 Browser -> XWiki : request page
244 XWiki -> XWiki : render every part, including the slow one
245 XWiki --> Browser : complete page
246 Browser --> Reader : page, after the slow part is done
247 {{/plantuml}}
248
249 With async rendering:
250
251 {{plantuml}}
252 !theme bluegray
253 ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under
254 ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm.
255 skinparam activity {
256 BackgroundColor #0568AE
257 BorderColor #034873
258 FontColor #FFFFFF
259 StartColor #04538B
260 EndColor #04538B
261 BarColor #5A5A5A
262 ' Diamonds are blue with white text, not light with dark text: a labelled
263 ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from
264 ' FontColor above, so a light fill draws that one box white on white, and no
265 ' selector reaches it without reaching the decision diamonds too.
266 DiamondBackgroundColor #0568AE
267 DiamondBorderColor #034873
268 DiamondFontColor #FFFFFF
269 }
270 skinparam state {
271 BackgroundColor #0568AE
272 BorderColor #034873
273 FontColor #FFFFFF
274 AttributeFontColor #FFFFFF
275 StartColor #04538B
276 EndColor #04538B
277 }
278 skinparam class {
279 BackgroundColor #0568AE
280 BorderColor #034873
281 FontColor #FFFFFF
282 HeaderBackgroundColor #0568AE
283 AttributeFontColor #FFFFFF
284 StereotypeFontColor #262626
285 }
286 skinparam object {
287 BackgroundColor #0568AE
288 BorderColor #034873
289 FontColor #FFFFFF
290 AttributeFontColor #FFFFFF
291 StereotypeFontColor #262626
292 }
293 skinparam participant {
294 BackgroundColor #0568AE
295 BorderColor #034873
296 FontColor #FFFFFF
297 }
298 skinparam actor {
299 BackgroundColor #F5F5F5
300 BorderColor #5A5A5A
301 FontColor #262626
302 }
303 skinparam component {
304 BackgroundColor #0568AE
305 BorderColor #034873
306 FontColor #FFFFFF
307 }
308 skinparam collections {
309 BackgroundColor #0568AE
310 BorderColor #034873
311 FontColor #FFFFFF
312 }
313 skinparam queue {
314 BackgroundColor #0568AE
315 BorderColor #034873
316 FontColor #FFFFFF
317 }
318 skinparam stack {
319 BackgroundColor #0568AE
320 BorderColor #034873
321 FontColor #FFFFFF
322 }
323 ' database, control, entity, boundary and interface draw their label beside or
324 ' under the icon, on the page, in some diagram types: their text stays dark.
325 skinparam database {
326 BackgroundColor #F5F5F5
327 BorderColor #5A5A5A
328 FontColor #262626
329 }
330 skinparam control {
331 BackgroundColor #0568AE
332 BorderColor #034873
333 FontColor #262626
334 }
335 skinparam entity {
336 BackgroundColor #0568AE
337 BorderColor #034873
338 FontColor #262626
339 }
340 skinparam boundary {
341 BackgroundColor #0568AE
342 BorderColor #034873
343 FontColor #262626
344 }
345 skinparam usecase {
346 BackgroundColor #0568AE
347 BorderColor #034873
348 FontColor #FFFFFF
349 StereotypeFontColor #FFFFFF
350 }
351 skinparam card {
352 BackgroundColor #04538B
353 BorderColor #034873
354 FontColor #FFFFFF
355 }
356 skinparam note {
357 BackgroundColor #04538B
358 BorderColor #034873
359 FontColor #FFFFFF
360 }
361 skinparam storage {
362 BackgroundColor #8A4A00
363 BorderColor #8A4A00
364 FontColor #FFFFFF
365 }
366 skinparam agent {
367 BackgroundColor #8A4A00
368 BorderColor #8A4A00
369 FontColor #FFFFFF
370 }
371 skinparam interface {
372 BackgroundColor #A62222
373 BorderColor #A62222
374 FontColor #262626
375 }
376 skinparam node {
377 BackgroundColor #F5F5F5
378 BorderColor #5A5A5A
379 FontColor #262626
380 }
381 skinparam cloud {
382 BackgroundColor #F5F5F5
383 BorderColor #5A5A5A
384 FontColor #262626
385 }
386 skinparam artifact {
387 BackgroundColor #F5F5F5
388 BorderColor #5A5A5A
389 FontColor #262626
390 }
391 skinparam file {
392 BackgroundColor #F5F5F5
393 BorderColor #5A5A5A
394 FontColor #262626
395 }
396 skinparam rectangle {
397 BackgroundColor #FFFFFF
398 BorderColor #5A5A5A
399 FontColor #262626
400 StereotypeFontColor #0568AE
401 }
402 skinparam folder {
403 BackgroundColor #F5F5F5
404 BorderColor #8A4A00
405 FontColor #8A4A00
406 }
407 skinparam frame {
408 BackgroundColor #F5F5F5
409 BorderColor #04538B
410 FontColor #04538B
411 }
412 skinparam package {
413 BackgroundColor #FFFFFF
414 BorderColor #0568AE
415 FontColor #262626
416 }
417 skinparam partition {
418 BackgroundColor #FFFFFF
419 BorderColor #0568AE
420 FontColor #0568AE
421 }
422 skinparam swimlane {
423 BorderColor #0568AE
424 TitleBackgroundColor #F5F5F5
425 TitleFontColor #0568AE
426 }
427 skinparam sequence {
428 BoxBackgroundColor #F5F5F5
429 BoxBorderColor #5A5A5A
430 BoxFontColor #262626
431 DelayFontColor #262626
432 GroupBorderColor #5A5A5A
433 GroupFontColor #262626
434 LifeLineBorderColor #5A5A5A
435 LifeLineBackgroundColor #F5F5F5
436 TitleFontColor #0568AE
437 StartColor #0568AE
438 EndColor #0568AE
439 BorderColor #0568AE
440 }
441 skinparam arrow {
442 Color #0568AE
443 FontColor #262626
444 }
445 skinparam legend {
446 BackgroundColor #F5F5F5
447 BorderColor #5A5A5A
448 FontColor #262626
449 }
450 skinparam stereotype {
451 CBackgroundColor #F5F5F5
452 CBorderColor #5A5A5A
453 ABackgroundColor #F5F5F5
454 ABorderColor #5A5A5A
455 IBackgroundColor #F5F5F5
456 IBorderColor #5A5A5A
457 EBackgroundColor #F5F5F5
458 EBorderColor #5A5A5A
459 NBackgroundColor #F5F5F5
460 NBorderColor #5A5A5A
461 }
462 skinparam ArrowColor #0568AE
463 ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form
464 ' leaks its background onto every element in the diagram.
465 skinparam titleFontColor #0568AE
466 skinparam titleBorderColor #5A5A5A
467 ' Links otherwise take bluegray's white root colour, unreadable on a light fill.
468 <style>
469 root {
470 HyperLinkColor #0568AE
471 }
472 element {
473 HyperLinkColor #FFFFFF
474 }
475 actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface,
476 legend, node, package, rectangle {
477 HyperLinkColor #0568AE
478 }
479 </style>
480 ' ---- end XWiki accessible diagram palette ----
481 actor Reader
482 participant Browser
483 participant XWiki
484 Reader -> Browser : open page
485 Browser -> XWiki : request page
486 XWiki -> XWiki : start the slow part in the background
487 XWiki --> Browser : page with a placeholder
488 Browser --> Reader : page, without waiting for the slow part
489 loop until the result is ready
490 Browser -> XWiki : ask for the placeholder result
491 alt still running after the wait timeout
492 XWiki --> Browser : 202
493 Browser --> Reader : spinner in the placeholder
494 else finished
495 XWiki --> Browser : 200, rendered result
496 end
497 end
498 Browser --> Reader : result in place of the placeholder
499 note over XWiki
500 when caching is enabled, the result is also kept
501 and reused until a resource it used is modified
502 end note
503 {{/plantuml}}
504
505 Async rendering is supported for:
506
507 * page content
508 * [[panels>>doc:documentation.xs.dev.panels.WebHome]]
509 * [[UI extensions>>doc:extensions:Extension.UIExtension Module]]
510 * [[wiki macros>>doc:extensions:Extension.WikiMacroStore.WebHome]]
511 * [[templates>>doc:documentation.xs.dev.templates.WebHome]]
512
513 To render a part of wiki content asynchronously or to cache it, wrap it in the [["async" Macro>>doc:documentation.xs.dev.async-rendering.async-macro.WebHome]]. The context entries an asynchronous execution can keep, the ##async## script service and the details of cache invalidation are described on the [[Async Rendering extension page>>doc:extensions:Extension.Rendering Module.Async.WebHome]].

Get Connected