Wiki source code of Rendering Macros
Last modified by superadmin on 2026/10/14 18:26
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | A [[rendering macro>>doc:extensions:Extension.RenderingMacroTransformation.WebHome]] 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. | ||
| 2 | |||
| 3 | == What Rendering Is == | ||
| 4 | |||
| 5 | A Page is not stored as the screen you read. XWiki stores its content as text in [[XWiki Syntax>>xwiki:Documentation.UserGuide.Features.XWikiSyntax]], 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>>doc:documentation.xs.user.exports.WebHome]]. Macros are the part of that text XWiki does not simply format but runs. | ||
| 6 | |||
| 7 | {{plantuml}} | ||
| 8 | @startuml | ||
| 9 | !theme bluegray | ||
| 10 | skinparam nodesep 35 | ||
| 11 | skinparam ranksep 45 | ||
| 12 | |||
| 13 | actor "Reader" as R | ||
| 14 | file "Stored Page content:\nXWiki Syntax, with the\nMacros you inserted" as SRC | ||
| 15 | rectangle "XWiki renders the Page:\nit reads the syntax\nand runs every Macro" as RUN | ||
| 16 | card "The result:\nthe Page in the browser,\nor the file you export" as OUT | ||
| 17 | |||
| 18 | R --> RUN : opens or exports the Page | ||
| 19 | SRC --> RUN : read, never changed | ||
| 20 | RUN --> OUT | ||
| 21 | @enduml | ||
| 22 | {{/plantuml}} | ||
| 23 | |||
| 24 | == A Macro in the Editor == | ||
| 25 | |||
| 26 | You insert a Macro from the editor, and [[Ways to Insert a Macro>>doc:documentation.xs.user.rendering-macros.ways-insert.WebHome]] describes the route each one offers. Once inserted, the Macro is a single block you can select, move or delete: | ||
| 27 | |||
| 28 | {{image reference="macro-editor.png" size="large" alt="The Table of Contents macro selected in the WYSIWYG editor, outlined as a single block."/}} | ||
| 29 | |||
| 30 | The list inside that block cannot be typed into, because XWiki builds it only when the Page is displayed. | ||
| 31 | |||
| 32 | == Name, Parameters and Content == | ||
| 33 | |||
| 34 | 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. | ||
| 35 | |||
| 36 | Those three things are what the [[Wiki editor>>doc:documentation.xs.user.base.page.edit.edit-wiki-editor.WebHome]] shows you directly, since there you write the Macro yourself: | ||
| 37 | |||
| 38 | {{code language="none"}} | ||
| 39 | {{box title="Release"}} | ||
| 40 | Freeze the branch. | ||
| 41 | {{/box}} | ||
| 42 | {{/code}} | ||
| 43 | |||
| 44 | A Macro that takes no content closes itself instead, like the ##toc## Macro that builds a table of contents. | ||
| 45 | |||
| 46 | == A Macro on the Displayed Page == | ||
| 47 | |||
| 48 | Opening the Page displays what each Macro produced: | ||
| 49 | |||
| 50 | {{image reference="macro-output.png" size="large" alt="The list of links the table of contents macro produced, above the first heading it points at."/}} | ||
| 51 | |||
| 52 | 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. | ||
| 53 | |||
| 54 | == Where Macros Come From == | ||
| 55 | |||
| 56 | * Bundled with XWiki, which is the set a new wiki already has. | ||
| 57 | * Added by an [[extension>>doc:documentation.xs.user.extensions.WebHome]] an administrator installed, and taken away again when that extension is uninstalled. | ||
| 58 | * Written on the wiki itself, since an advanced user can [[define a Macro in a wiki Page>>doc:documentation.xs.dev.rendering-macros.wiki-macros.WebHome]] without writing any Java. | ||
| 59 | |||
| 60 | == When a Macro Cannot Run == | ||
| 61 | |||
| 62 | 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: | ||
| 63 | |||
| 64 | {{image reference="macro-error.png" size="large" alt="An error box replacing a macro that is not installed, between the two paragraphs of the page."/}} | ||
| 65 | |||
| 66 | 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. |
