Rendering Macros
Explanation
A rendering macro is a building block you add to a Page and that XWiki replaces by what it produces: a table of contents, a coloured box, a chart, the list of Pages matching a search. It is called a rendering macro because XWiki works it out while rendering the Page, and it is what the editors and the rest of this documentation call simply a Macro.
What Rendering Is
A Page is not stored as the screen you read. XWiki stores its content as text in XWiki Syntax, where = Release = is a heading and **frozen** is bold. Rendering is the step that turns that text into the result you asked for: the Page in your browser, or the file you get when you export it. Macros are the part of that text XWiki does not simply format but runs.
A Macro in the Editor
You insert a Macro from the editor, and Ways to Insert a Macro describes the route each one offers. Once inserted, the Macro is a single block you can select, move or delete:
The list inside that block cannot be typed into, because XWiki builds it only when the Page is displayed.
Name, Parameters and Content
Every Macro has a name, which is what identifies it. Most Macros also take parameters, the settings the editor asks you for: how deep the table of contents goes, the title of a box. Some take content as well, the text they act on, and that content can itself hold other Macros.
Those three things are what the Wiki editor shows you directly, since there you write the Macro yourself:
{{box title="Release"}}
Freeze the branch.
{{/box}}A Macro that takes no content closes itself instead, like the toc Macro that builds a table of contents.
A Macro on the Displayed Page
Opening the Page displays what each Macro produced:
XWiki stores the Macro, never its output, so the output is worked out again for every reader and against the wiki as it is at that moment. Add a heading to that Page later and the list gains an entry on its own, with nothing for you to update.
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 a Macro runs while the Page is being displayed, it 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.
FAQ
Can a Macro be put inside another Macro?
Yes, whenever the outer Macro accepts 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.
Where do I find the parameters a Macro accepts?
The editor describes each one as you fill it in, and the Macro's own Reference page documents them all. Check the page listing all rendering macros.
Can I stop a Macro from running on one Page?
No, but you can show the Macro instead of running it by putting it inside a code Macro, which is how the 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.
