Wiki source code of Caching Code Macro
Last modified by Vincent Massol on 2026/11/12 16:56
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The [[Caching Code Macro>>doc:extensions:Extension.Caching Code Macro.WebHome]] extension replaces the standard [[Code Macro>>doc:extensions:Extension.Code Macro.WebHome]] to make pages holding code display faster. Syntax highlighting is costly to compute, so the extension changes two things: | ||
| 2 | |||
| 3 | * **Cached**: the highlighted code is computed once and kept in a cache, which every later display uses. | ||
| 4 | * **Asynchronous**: when the highlighted code isn't in the cache yet, it's computed in the background, so the page is displayed without waiting for it. | ||
| 5 | |||
| 6 | Pages keep using the ##code## macro exactly as before. It requires XWiki 15.10 or later and is installed from the Extension Manager. | ||
| 7 | |||
| 8 | The asynchronous rendering is enabled by default. To compute the highlighted code while the page is rendered instead, still keeping the cache, see [[Disable the Asynchronous Rendering of the Caching Code Macro>>doc:documentation.extensions.admin.caching-code-macro.disable-asynchronous-rendering.WebHome]]. | ||
| 9 | |||
| 10 | == First and Later Displays == | ||
| 11 | |||
| 12 | The first time a code macro is displayed, the page does not wait for it: the highlighted code appears a moment later. Every later display, of this page or of any page holding the same macro, takes the code from the cache. | ||
| 13 | |||
| 14 | {{plantuml}} | ||
| 15 | @startuml | ||
| 16 | !theme bluegray | ||
| 17 | ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under | ||
| 18 | ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm. | ||
| 19 | skinparam activity { | ||
| 20 | BackgroundColor #0568AE | ||
| 21 | BorderColor #034873 | ||
| 22 | FontColor #FFFFFF | ||
| 23 | StartColor #04538B | ||
| 24 | EndColor #04538B | ||
| 25 | BarColor #5A5A5A | ||
| 26 | DiamondBackgroundColor #F5F5F5 | ||
| 27 | DiamondBorderColor #5A5A5A | ||
| 28 | DiamondFontColor #262626 | ||
| 29 | } | ||
| 30 | skinparam state { | ||
| 31 | BackgroundColor #0568AE | ||
| 32 | BorderColor #034873 | ||
| 33 | FontColor #FFFFFF | ||
| 34 | AttributeFontColor #FFFFFF | ||
| 35 | StartColor #04538B | ||
| 36 | EndColor #04538B | ||
| 37 | } | ||
| 38 | skinparam class { | ||
| 39 | BackgroundColor #0568AE | ||
| 40 | BorderColor #034873 | ||
| 41 | FontColor #FFFFFF | ||
| 42 | HeaderBackgroundColor #0568AE | ||
| 43 | AttributeFontColor #FFFFFF | ||
| 44 | StereotypeFontColor #262626 | ||
| 45 | } | ||
| 46 | skinparam object { | ||
| 47 | BackgroundColor #0568AE | ||
| 48 | BorderColor #034873 | ||
| 49 | FontColor #FFFFFF | ||
| 50 | AttributeFontColor #FFFFFF | ||
| 51 | StereotypeFontColor #262626 | ||
| 52 | } | ||
| 53 | skinparam participant { | ||
| 54 | BackgroundColor #0568AE | ||
| 55 | BorderColor #034873 | ||
| 56 | FontColor #FFFFFF | ||
| 57 | } | ||
| 58 | skinparam actor { | ||
| 59 | BackgroundColor #F5F5F5 | ||
| 60 | BorderColor #5A5A5A | ||
| 61 | FontColor #262626 | ||
| 62 | } | ||
| 63 | skinparam component { | ||
| 64 | BackgroundColor #0568AE | ||
| 65 | BorderColor #034873 | ||
| 66 | FontColor #FFFFFF | ||
| 67 | } | ||
| 68 | skinparam collections { | ||
| 69 | BackgroundColor #0568AE | ||
| 70 | BorderColor #034873 | ||
| 71 | FontColor #FFFFFF | ||
| 72 | } | ||
| 73 | skinparam queue { | ||
| 74 | BackgroundColor #0568AE | ||
| 75 | BorderColor #034873 | ||
| 76 | FontColor #FFFFFF | ||
| 77 | } | ||
| 78 | skinparam stack { | ||
| 79 | BackgroundColor #0568AE | ||
| 80 | BorderColor #034873 | ||
| 81 | FontColor #FFFFFF | ||
| 82 | } | ||
| 83 | ' database, control, entity, boundary and interface draw their label beside or | ||
| 84 | ' under the icon, on the page, in some diagram types: their text stays dark. | ||
| 85 | skinparam database { | ||
| 86 | BackgroundColor #F5F5F5 | ||
| 87 | BorderColor #5A5A5A | ||
| 88 | FontColor #262626 | ||
| 89 | } | ||
| 90 | skinparam control { | ||
| 91 | BackgroundColor #0568AE | ||
| 92 | BorderColor #034873 | ||
| 93 | FontColor #262626 | ||
| 94 | } | ||
| 95 | skinparam entity { | ||
| 96 | BackgroundColor #0568AE | ||
| 97 | BorderColor #034873 | ||
| 98 | FontColor #262626 | ||
| 99 | } | ||
| 100 | skinparam boundary { | ||
| 101 | BackgroundColor #0568AE | ||
| 102 | BorderColor #034873 | ||
| 103 | FontColor #262626 | ||
| 104 | } | ||
| 105 | skinparam usecase { | ||
| 106 | BackgroundColor #0568AE | ||
| 107 | BorderColor #034873 | ||
| 108 | FontColor #FFFFFF | ||
| 109 | StereotypeFontColor #FFFFFF | ||
| 110 | } | ||
| 111 | skinparam card { | ||
| 112 | BackgroundColor #04538B | ||
| 113 | BorderColor #034873 | ||
| 114 | FontColor #FFFFFF | ||
| 115 | } | ||
| 116 | skinparam note { | ||
| 117 | BackgroundColor #04538B | ||
| 118 | BorderColor #034873 | ||
| 119 | FontColor #FFFFFF | ||
| 120 | } | ||
| 121 | skinparam storage { | ||
| 122 | BackgroundColor #8A4A00 | ||
| 123 | BorderColor #8A4A00 | ||
| 124 | FontColor #FFFFFF | ||
| 125 | } | ||
| 126 | skinparam agent { | ||
| 127 | BackgroundColor #8A4A00 | ||
| 128 | BorderColor #8A4A00 | ||
| 129 | FontColor #FFFFFF | ||
| 130 | } | ||
| 131 | skinparam interface { | ||
| 132 | BackgroundColor #A62222 | ||
| 133 | BorderColor #A62222 | ||
| 134 | FontColor #262626 | ||
| 135 | } | ||
| 136 | skinparam node { | ||
| 137 | BackgroundColor #F5F5F5 | ||
| 138 | BorderColor #5A5A5A | ||
| 139 | FontColor #262626 | ||
| 140 | } | ||
| 141 | skinparam cloud { | ||
| 142 | BackgroundColor #F5F5F5 | ||
| 143 | BorderColor #5A5A5A | ||
| 144 | FontColor #262626 | ||
| 145 | } | ||
| 146 | skinparam artifact { | ||
| 147 | BackgroundColor #F5F5F5 | ||
| 148 | BorderColor #5A5A5A | ||
| 149 | FontColor #262626 | ||
| 150 | } | ||
| 151 | skinparam file { | ||
| 152 | BackgroundColor #F5F5F5 | ||
| 153 | BorderColor #5A5A5A | ||
| 154 | FontColor #262626 | ||
| 155 | } | ||
| 156 | skinparam rectangle { | ||
| 157 | BackgroundColor #FFFFFF | ||
| 158 | BorderColor #5A5A5A | ||
| 159 | FontColor #262626 | ||
| 160 | StereotypeFontColor #0568AE | ||
| 161 | } | ||
| 162 | skinparam folder { | ||
| 163 | BackgroundColor #F5F5F5 | ||
| 164 | BorderColor #8A4A00 | ||
| 165 | FontColor #8A4A00 | ||
| 166 | } | ||
| 167 | skinparam frame { | ||
| 168 | BackgroundColor #F5F5F5 | ||
| 169 | BorderColor #04538B | ||
| 170 | FontColor #04538B | ||
| 171 | } | ||
| 172 | skinparam package { | ||
| 173 | BackgroundColor #FFFFFF | ||
| 174 | BorderColor #0568AE | ||
| 175 | FontColor #262626 | ||
| 176 | } | ||
| 177 | skinparam partition { | ||
| 178 | BackgroundColor #FFFFFF | ||
| 179 | BorderColor #0568AE | ||
| 180 | FontColor #0568AE | ||
| 181 | } | ||
| 182 | skinparam swimlane { | ||
| 183 | BorderColor #0568AE | ||
| 184 | TitleBackgroundColor #F5F5F5 | ||
| 185 | TitleFontColor #0568AE | ||
| 186 | } | ||
| 187 | skinparam sequence { | ||
| 188 | BoxBackgroundColor #F5F5F5 | ||
| 189 | BoxBorderColor #5A5A5A | ||
| 190 | BoxFontColor #262626 | ||
| 191 | DelayFontColor #262626 | ||
| 192 | GroupBorderColor #5A5A5A | ||
| 193 | GroupFontColor #262626 | ||
| 194 | LifeLineBorderColor #5A5A5A | ||
| 195 | LifeLineBackgroundColor #F5F5F5 | ||
| 196 | TitleFontColor #0568AE | ||
| 197 | StartColor #0568AE | ||
| 198 | EndColor #0568AE | ||
| 199 | BorderColor #0568AE | ||
| 200 | } | ||
| 201 | skinparam arrow { | ||
| 202 | Color #0568AE | ||
| 203 | FontColor #262626 | ||
| 204 | } | ||
| 205 | skinparam legend { | ||
| 206 | BackgroundColor #F5F5F5 | ||
| 207 | BorderColor #5A5A5A | ||
| 208 | FontColor #262626 | ||
| 209 | } | ||
| 210 | skinparam stereotype { | ||
| 211 | CBackgroundColor #F5F5F5 | ||
| 212 | CBorderColor #5A5A5A | ||
| 213 | ABackgroundColor #F5F5F5 | ||
| 214 | ABorderColor #5A5A5A | ||
| 215 | IBackgroundColor #F5F5F5 | ||
| 216 | IBorderColor #5A5A5A | ||
| 217 | EBackgroundColor #F5F5F5 | ||
| 218 | EBorderColor #5A5A5A | ||
| 219 | NBackgroundColor #F5F5F5 | ||
| 220 | NBorderColor #5A5A5A | ||
| 221 | } | ||
| 222 | skinparam ArrowColor #0568AE | ||
| 223 | ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form | ||
| 224 | ' leaks its background onto every element in the diagram. | ||
| 225 | skinparam titleFontColor #0568AE | ||
| 226 | skinparam titleBorderColor #5A5A5A | ||
| 227 | ' Links otherwise take bluegray's white root colour, unreadable on a light fill. | ||
| 228 | <style> | ||
| 229 | root { | ||
| 230 | HyperLinkColor #0568AE | ||
| 231 | } | ||
| 232 | element { | ||
| 233 | HyperLinkColor #FFFFFF | ||
| 234 | } | ||
| 235 | actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface, | ||
| 236 | legend, node, package, rectangle { | ||
| 237 | HyperLinkColor #0568AE | ||
| 238 | } | ||
| 239 | </style> | ||
| 240 | ' ---- end XWiki accessible diagram palette ---- | ||
| 241 | start | ||
| 242 | :A page holding a code macro is displayed; | ||
| 243 | if (Result in the cache?) then (yes) | ||
| 244 | :Code shown with the page; | ||
| 245 | else (no) | ||
| 246 | :Page shown with a placeholder; | ||
| 247 | :Code highlighted in the background; | ||
| 248 | :Result stored in the cache; | ||
| 249 | :Code shown in the page; | ||
| 250 | endif | ||
| 251 | stop | ||
| 252 | @enduml | ||
| 253 | {{/plantuml}} | ||
| 254 | |||
| 255 | == What Is Cached == | ||
| 256 | |||
| 257 | {{version product="Caching Code Macro" since="1.1"}} | ||
| 258 | A cache entry is identified by what the highlighting result depends on: the macro content, its parameters (##language##, ##layout##, ##title##, ##image##, ##cssClass##, ##width##), whether the macro is inline, the syntax of the macro and of the output, and the current wiki. As a consequence: | ||
| 259 | |||
| 260 | * Identical code macros share one cache entry, even on different pages. | ||
| 261 | * Content generated by a script is cached per distinct content, so each user sees their own. | ||
| 262 | * Content read through the ##source## parameter is fetched first, with the rights of the current user, and cached per content. | ||
| 263 | * Editing a macro creates a new entry. Modifying the page resets nothing, except in the case below. | ||
| 264 | * A macro with a ##title## or an ##image##, when not inline, gets an entry per page, and the relative links and images they hold point to the page holding the macro. When such an entry is computed in the background, it is computed again after that page is modified. | ||
| 265 | {{/version}} | ||
| 266 | |||
| 267 | {{version product="Caching Code Macro" before="1.1"}}The result was cached per page and macro position, and reset when the page was modified.{{/version}} |
