Macro handling
Explanation
There are three main ways of handling macros coming from Confluence:
- bridges
- converters
- we have the same macro in XWiki
Bridges
By default, we convert macros to bridges:
- the macro is named confluence_nnn, where nnn is the original name of the macro in Confluence
- parameter are kept as is (or, more accurately, their values are converted to strings: in Confluence, parameter values can be arbitrary XML)
Converters
Confluence XML offers the possibility to write custom converters for macros, and provide quite a few of these converters. See Writing macro converters.
Same macro in XWiki and Confluence
It happens that we do have the same macro in XWiki as in Confluence, with compatible parameter names. It's usually very simple macros. This is for example the case for the html macro.
Confluence XML's "unprefixed macros" parameter can be used to tell Confluence XML not to prefix the macro.
Macro handling policy
When dealing with a new macro from Confluence, we follow the current rule:
- if the macro from Confluence has a compatible name and compatible parameters, "unprefixing" it can be considered
- Otherwise, we consider writing a macro converter that will convert the macro to a macro implemented in XWiki standard or in a contrib extension.
If nothing is done, then a bridge will be output. So far, no Confluence bridge is implemented in standard XWiki or in a contrib extension, which means the macro call will display an error because it's not implemented. There's nothing against implementing bridges in a contrib extension. XWiki SAS implements a few bridges as part of their Pro packages.
In short:
- A macro converter is strongly preferred
- implementing a bridge should only be considered if a macro converter would not be suitable for some reason
