XWiki Rendering Architecture
- Parser: Parses some textual input in a given syntax and generates a XDOM object which is an AST representing the input into structured blocks.
- Renderer: Takes a XDOM as input and generates some output.
- Transformation: Takes some XDOM and modifies it to generate modified XDOM (see the list of ). One important transformation is the MacroTransformation which looks for all macro blocks in the XDOM object and replaces them by blocks generated by various macros. Note that executing transformations is an optional step and if you don't run them then you'll get a XDOM object without any transformation applied on it (e.g. without macros executed). Also not that there's a TransformationContext used that holds various information about the context: the XDOM being transformed, the syntax, and more.
- Macro: Takes a macro definition as input and generates XDOM Blocks (see the list of ).
Macro Execution Process
Macros are executed by the "Macro Transformation". Here are rules that apply:
- Macros can be registered for a given syntax or for all syntaxes.
- Macros also have a priority which allows some macros to be executed before or after other macros. For example the "Include" macro runs first and the "Table Of Content" macro executes last (so that it can take into account all headers created by other macros).
- The Macro Transformation finds all macro blocks defined in the passed XDOM object. For each macro block found it verifies if there's a macro registered for that macro block and for the target syntax. It then sorts all macros by priority and execute them one by one, replacing the macro block with the list of blocks generated by the macro, until there are no macro blocks left in the XDOM. Note that a macro can generate macro blocks.
- The Macro Transformation uses a MacroTransformationContext which augments the TransformationContext by holding additional information such as the current XDOM block being processed or whether the macro is called inline or not.
Starting with XWiki 6.0, it's now possible to access the context of the rendering in progress from any components. The information, initially provided by the org.xwiki.rendering.transformation.TransformationContext and org.xwiki.rendering.transformation.MacroTransformationContext (for Transformations and for Macros) are now available to any component using the org.xwiki.rendering.transformation.RenderingContext role.
For this context to be properly actuated, any process that initiate a transformation without using the default implementation of org.xwiki.rendering.transformation.TransformationManager role (or implement it) should take care of it. At the moment, there is no public API for this (internally we use org.xwiki.rendering.internal.transformation.MutableRenderingContext for this purpose), so it is highly recommended to use the Transformation Manager when possible.