Rendering Macros
Explanation
A rendering macro is a named call you write in the content of a page, which XWiki replaces by what the macro produces. It is called a rendering macro because it runs while the page is being rendered, and it is what the editors and the rest of this documentation call simply a macro.
A macro has a name, most macros take parameters, and many also take a content:
{{macroName parameter="value"}}
The content of the macro.
{{/macroName}}A macro that takes no content closes itself instead, like the toc macro that builds a table of contents. A macro can stand on its own in the page or sit inside a sentence, and the content you give a macro can hold other macros.
You do not have to type any of this: the editors list the macros installed on your wiki and ask you for the parameters, as Insert a Macro with the BlockNote Editor describes.
A Macro Runs When the Page Is Displayed
XWiki stores the macro call, never its output. Every time somebody opens the page, each macro in it runs again, against the wiki as it is at that moment.
So this page content:
{{toc/}}
= Before the Release =
Freeze the branch and check that the build is green.is displayed as a list of links to the headings that exist right now:
Add a heading later and the list gains an entry on its own, because what is stored is still the same single macro call.
Where Macros Come From
- Bundled with XWiki, which is the set a new wiki already has.
- Added by an extension an administrator installed, and taken away again when that extension is uninstalled.
- Written on the wiki itself, since an advanced user can define a macro in a wiki page without writing any Java.
When a Macro Cannot Run
Because macros run while the page is being displayed, a macro can fail at that moment. XWiki then replaces that one macro by an error box and displays the rest of the page normally:
Clicking the box tells you what went wrong, and names the extension that provides the macro when XWiki recognises it. The usual causes are a macro that is not installed on this wiki, a misspelled macro name, and a parameter value the macro does not accept.
Where the Macros Are Documented
Each macro has its own Reference page, in the topic of the feature it serves: the six that lay content out on a page, box, info, success, warning, error and display, are documented under Edit a Page, and the "displayIcon" macro under Icons. All Bundled Rendering Macros gathers every one of them into a single table, whichever topic it lives in.
FAQ
Can a macro be put inside another macro?
Yes, whenever the outer macro accepts wiki content. A "box" macro can hold an "info" macro, which can itself hold a code macro.
Why does a page show me different content than it shows a colleague?
A macro runs with the rights of the person opening the page, so a macro that lists or displays other pages only shows what that reader is allowed to see.
Can I stop a macro from running on one page?
No, but you can show the call instead of running it by putting it inside a code macro, which is how every example above is written.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
