Rendering Transformations
Reference
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 :) by an icon. Both are set in xwiki.properties.
| Property | Default | What it sets |
|---|---|---|
| rendering.transformations | macro, icon | The transformations to run, named by the component hint each is registered under |
| 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 |
rendering.transformations = macro, iconThe macro categories are configured in the same file, under rendering.transformation.macro.categories and rendering.transformation.macro.hiddenCategories, which Macro Categories describes.
Marking a Macro's Execution as Isolated
A macro that promises not to change the structure of the page while it runs spares the macro transformation 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.
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:
rendering.macro.<macro>.executionIsolated = trueThe setting covers that macro id in every syntax and in every wiki of the instance.
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.
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.
FAQ
What happens if I leave macro out of the list?
No macro is executed anywhere on the instance, so nothing any of them produces appears on any page.
Can I run a transformation that is not one of the two bundled?
Yes. Any component registered on the Transformation role can be added to the list by its name, as the Link Checker extension's linkchecker is.
Where do I find the id to use in the isolated execution property?
It is the name the macro is called by in wiki syntax, toc for the table of contents macro.
