Wiki source code of Rendering Transformations
Last modified by superadmin on 2026/10/14 18:25
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | A rendering transformation changes the content of a page after it has been parsed and before it is rendered. An instance runs two of them out of the box: the macro transformation, which executes the macros, and the icon transformation, which replaces character sequences such as {{code language="none"}}:){{/code}} by an icon. Both are set in ##xwiki.properties##. | ||
| 2 | |||
| 3 | |=Property|=Default|=What it sets | ||
| 4 | |##rendering.transformations##|##macro, icon##|The transformations to run, named by the component hint each is registered under | ||
| 5 | |##rendering.macro.<macro>.executionIsolated##|What the macro declares in its own code|Whether the macro named ##<macro>## is treated as leaving the structure of the page untouched while it runs | ||
| 6 | |||
| 7 | {{code language="none"}} | ||
| 8 | rendering.transformations = macro, icon | ||
| 9 | {{/code}} | ||
| 10 | |||
| 11 | The macro categories are configured in the same file, under ##rendering.transformation.macro.categories## and ##rendering.transformation.macro.hiddenCategories##, which [[Macro Categories>>doc:documentation.xs.dev.rendering-macros.macro-categories.WebHome]] describes. | ||
| 12 | |||
| 13 | == Marking a Macro's Execution as Isolated == | ||
| 14 | |||
| 15 | A macro that promises not to change the structure of the page while it runs spares the [[macro transformation>>doc:documentation.xs.dev.rendering-macros.macro-transformation.WebHome]] a search of the whole page after every execution. On a page holding thousands of macro calls, those searches dominate the time it takes to render it, and that is the case this property exists for. | ||
| 16 | |||
| 17 | A macro that is safe to run that way but does not say so in its own code can be declared isolated from the configuration, by its id, which is the name it is called by in wiki syntax: | ||
| 18 | |||
| 19 | {{code language="none"}} | ||
| 20 | rendering.macro.<macro>.executionIsolated = true | ||
| 21 | {{/code}} | ||
| 22 | |||
| 23 | The setting covers that macro id in every syntax and in every wiki of the instance. | ||
| 24 | |||
| 25 | Declare it only for a macro you know never inserts content elsewhere in the page. One that does can then be executed in the wrong order or not at all, and whether it is depends on what else the page holds, so the symptom is hard to trace back to this line. The same property set to ##false## has the opposite effect, forcing the search for a macro that declares itself isolated and turns out not to be. | ||
| 26 | |||
| 27 | This is a way to bring the rendering time of a page of thousands of macros down without waiting for those macros to be changed. It is not a substitute for a macro declaring its own execution isolated. |
