Wiki source code of Macro handling
Last modified by Raphaël Jakse on 2026/03/23 12:27
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
3.1 | 1 | |
| |
2.1 | 2 | {{info}} |
| 3 | To help with cases where there is no direct equivalent in XWiki Standard, XWiki SAS, a sponsoring company of XWiki, has released the [[paying "Pro Macros">>url:https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/]] package which supports a set of Confluence Macros. See the "Warning" section in this document. In particular, if you see a "layout macro" error, this package will be very useful. | ||
| |
3.1 | 4 | {{/info}} |
| |
2.1 | 5 | |
| |
1.1 | 6 | There are three main ways of handling macros coming from Confluence: |
| 7 | |||
| 8 | 1. bridges | ||
| 9 | 1. converters | ||
| 10 | 1. we have the same macro in XWiki | ||
| 11 | |||
| 12 | == Bridges == | ||
| 13 | |||
| 14 | By default, we convert macros to bridges: | ||
| 15 | |||
| 16 | * the macro is named ##confluence_nnn##, where ##nnn## is the original name of the macro in Confluence | ||
| 17 | * parameter are kept as is (or, more accurately, their values are converted to strings: in Confluence, parameter values can be arbitrary XML) | ||
| 18 | |||
| 19 | == Converters == | ||
| 20 | |||
| |
1.3 | 21 | Confluence XML offers the possibility to write custom converters for macros, and provide quite a few of these converters. See [[Writing macro converters>>doc:xwiki:documentation.extensions.dev.confluence.write-macro-converters.WebHome]]. |
| |
1.1 | 22 | |
| 23 | == Same macro in XWiki and Confluence == | ||
| 24 | |||
| 25 | 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. | ||
| 26 | [[Confluence XML's "unprefixed macros" parameter>>doc:documentation.extensions.admin.confluence.input-parameters.WebHome]] can be used to tell Confluence XML not to prefix the macro. | ||
| 27 | |||
| 28 | {{info}} | ||
| 29 | By default, in Confluence XML, all macros are prefixed and the unprefixed macro parameter needs to be set. There's an issue to set a default value to this parameter so well known macros are not prefixed: [[https:~~/~~/jira.xwiki.org/browse/CONFLUENCE-250>>https://jira.xwiki.org/browse/CONFLUENCE-250]] | ||
| 30 | \\If it's currently working for you and you are wondering why, it might be because [[tools>>https://store.xwiki.com/xwiki/bin/view/Extension/Confluence%20Migrator%20Application%20(Pro)/]] you are using could be setting this parameter by default. | ||
| 31 | {{/info}} | ||
| 32 | |||
| 33 | == Macro handling policy == | ||
| 34 | |||
| 35 | When dealing with a new macro from Confluence, we follow the current rule: | ||
| 36 | |||
| 37 | * if the macro from Confluence has a compatible name and compatible parameters, "unprefixing" it can be considered | ||
| 38 | * Otherwise, we consider writing a macro converter that will convert the macro to a macro implemented in XWiki standard or in a contrib extension. | ||
| 39 | |||
| 40 | {{info}} | ||
| 41 | It is suitable to develop a new standard or contrib macro to implement a feature in XWiki equivalent to what the Confluence macro provides, but following the XWiki conventions, if none exist yet. | ||
| 42 | {{/info}} | ||
| 43 | |||
| 44 | {{warning}} | ||
| 45 | It is not suitable to implement a macro converter in Confluence XML to a macro that doesn't exist as a contrib or standard macro. In particular, XWIKI SAS implements macro converters in Confluence Migrator Pro for macros implemented in other "Pro" packages they provide, such as Pro Macros. | ||
| 46 | {{/warning}} | ||
| 47 | |||
| 48 | 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. | ||
| 49 | |||
| 50 | In short: | ||
| 51 | |||
| 52 | * A macro converter is strongly preferred | ||
| 53 | * implementing a bridge should only be considered if a macro converter would not be suitable for some reason |
