Wiki source code of Rendering Macros

Last modified by Eleni Cojocariu on 2026/11/13 12:35

Hide last authors
Eleni Cojocariu 20.1 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.
Lucas Charpentier 2.1 2
Eleni Cojocariu 20.1 3 == What Rendering Is ==
Eleni Cojocariu 13.1 4
Eleni Cojocariu 20.1 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.
Lucas Charpentier 2.1 6
Eleni Cojocariu 8.1 7 {{plantuml}}
8 @startuml
9 !theme bluegray
Eleni Cojocariu 25.3 10 ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under
11 ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm.
12 skinparam activity {
13 BackgroundColor #0568AE
14 BorderColor #034873
15 FontColor #FFFFFF
16 StartColor #04538B
17 EndColor #04538B
18 BarColor #5A5A5A
Eleni Cojocariu 25.4 19 ' Diamonds are blue with white text, not light with dark text: a labelled
20 ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from
21 ' FontColor above, so a light fill draws that one box white on white, and no
22 ' selector reaches it without reaching the decision diamonds too.
23 DiamondBackgroundColor #0568AE
24 DiamondBorderColor #034873
25 DiamondFontColor #FFFFFF
Eleni Cojocariu 25.3 26 }
27 skinparam state {
28 BackgroundColor #0568AE
29 BorderColor #034873
30 FontColor #FFFFFF
31 AttributeFontColor #FFFFFF
32 StartColor #04538B
33 EndColor #04538B
34 }
35 skinparam class {
36 BackgroundColor #0568AE
37 BorderColor #034873
38 FontColor #FFFFFF
39 HeaderBackgroundColor #0568AE
40 AttributeFontColor #FFFFFF
41 StereotypeFontColor #262626
42 }
43 skinparam object {
44 BackgroundColor #0568AE
45 BorderColor #034873
46 FontColor #FFFFFF
47 AttributeFontColor #FFFFFF
48 StereotypeFontColor #262626
49 }
50 skinparam participant {
51 BackgroundColor #0568AE
52 BorderColor #034873
53 FontColor #FFFFFF
54 }
55 skinparam actor {
56 BackgroundColor #F5F5F5
57 BorderColor #5A5A5A
58 FontColor #262626
59 }
60 skinparam component {
61 BackgroundColor #0568AE
62 BorderColor #034873
63 FontColor #FFFFFF
64 }
65 skinparam collections {
66 BackgroundColor #0568AE
67 BorderColor #034873
68 FontColor #FFFFFF
69 }
70 skinparam queue {
71 BackgroundColor #0568AE
72 BorderColor #034873
73 FontColor #FFFFFF
74 }
75 skinparam stack {
76 BackgroundColor #0568AE
77 BorderColor #034873
78 FontColor #FFFFFF
79 }
80 ' database, control, entity, boundary and interface draw their label beside or
81 ' under the icon, on the page, in some diagram types: their text stays dark.
82 skinparam database {
83 BackgroundColor #F5F5F5
84 BorderColor #5A5A5A
85 FontColor #262626
86 }
87 skinparam control {
88 BackgroundColor #0568AE
89 BorderColor #034873
90 FontColor #262626
91 }
92 skinparam entity {
93 BackgroundColor #0568AE
94 BorderColor #034873
95 FontColor #262626
96 }
97 skinparam boundary {
98 BackgroundColor #0568AE
99 BorderColor #034873
100 FontColor #262626
101 }
102 skinparam usecase {
103 BackgroundColor #0568AE
104 BorderColor #034873
105 FontColor #FFFFFF
106 StereotypeFontColor #FFFFFF
107 }
108 skinparam card {
109 BackgroundColor #04538B
110 BorderColor #034873
111 FontColor #FFFFFF
112 }
113 skinparam note {
114 BackgroundColor #04538B
115 BorderColor #034873
116 FontColor #FFFFFF
117 }
118 skinparam storage {
119 BackgroundColor #8A4A00
120 BorderColor #8A4A00
121 FontColor #FFFFFF
122 }
123 skinparam agent {
124 BackgroundColor #8A4A00
125 BorderColor #8A4A00
126 FontColor #FFFFFF
127 }
128 skinparam interface {
129 BackgroundColor #A62222
130 BorderColor #A62222
131 FontColor #262626
132 }
133 skinparam node {
134 BackgroundColor #F5F5F5
135 BorderColor #5A5A5A
136 FontColor #262626
137 }
138 skinparam cloud {
139 BackgroundColor #F5F5F5
140 BorderColor #5A5A5A
141 FontColor #262626
142 }
143 skinparam artifact {
144 BackgroundColor #F5F5F5
145 BorderColor #5A5A5A
146 FontColor #262626
147 }
148 skinparam file {
149 BackgroundColor #F5F5F5
150 BorderColor #5A5A5A
151 FontColor #262626
152 }
153 skinparam rectangle {
154 BackgroundColor #FFFFFF
155 BorderColor #5A5A5A
156 FontColor #262626
157 StereotypeFontColor #0568AE
158 }
159 skinparam folder {
160 BackgroundColor #F5F5F5
161 BorderColor #8A4A00
162 FontColor #8A4A00
163 }
164 skinparam frame {
165 BackgroundColor #F5F5F5
166 BorderColor #04538B
167 FontColor #04538B
168 }
169 skinparam package {
170 BackgroundColor #FFFFFF
171 BorderColor #0568AE
172 FontColor #262626
173 }
174 skinparam partition {
175 BackgroundColor #FFFFFF
176 BorderColor #0568AE
177 FontColor #0568AE
178 }
179 skinparam swimlane {
180 BorderColor #0568AE
181 TitleBackgroundColor #F5F5F5
182 TitleFontColor #0568AE
183 }
184 skinparam sequence {
185 BoxBackgroundColor #F5F5F5
186 BoxBorderColor #5A5A5A
187 BoxFontColor #262626
188 DelayFontColor #262626
189 GroupBorderColor #5A5A5A
190 GroupFontColor #262626
191 LifeLineBorderColor #5A5A5A
192 LifeLineBackgroundColor #F5F5F5
193 TitleFontColor #0568AE
194 StartColor #0568AE
195 EndColor #0568AE
196 BorderColor #0568AE
197 }
198 skinparam arrow {
199 Color #0568AE
200 FontColor #262626
201 }
202 skinparam legend {
203 BackgroundColor #F5F5F5
204 BorderColor #5A5A5A
205 FontColor #262626
206 }
207 skinparam stereotype {
208 CBackgroundColor #F5F5F5
209 CBorderColor #5A5A5A
210 ABackgroundColor #F5F5F5
211 ABorderColor #5A5A5A
212 IBackgroundColor #F5F5F5
213 IBorderColor #5A5A5A
214 EBackgroundColor #F5F5F5
215 EBorderColor #5A5A5A
216 NBackgroundColor #F5F5F5
217 NBorderColor #5A5A5A
218 }
219 skinparam ArrowColor #0568AE
220 ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form
221 ' leaks its background onto every element in the diagram.
222 skinparam titleFontColor #0568AE
223 skinparam titleBorderColor #5A5A5A
224 ' Links otherwise take bluegray's white root colour, unreadable on a light fill.
225 <style>
226 root {
227 HyperLinkColor #0568AE
228 }
229 element {
230 HyperLinkColor #FFFFFF
231 }
232 actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface,
233 legend, node, package, rectangle {
234 HyperLinkColor #0568AE
235 }
236 </style>
237 ' ---- end XWiki accessible diagram palette ----
Eleni Cojocariu 8.1 238 skinparam nodesep 35
239 skinparam ranksep 45
240
241 actor "Reader" as R
Eleni Cojocariu 20.1 242 file "Stored Page content:\nXWiki Syntax, with the\nMacros you inserted" as SRC
243 rectangle "XWiki renders the Page:\nit reads the syntax\nand runs every Macro" as RUN
244 card "The result:\nthe Page in the browser,\nor the file you export" as OUT
Eleni Cojocariu 8.1 245
Eleni Cojocariu 20.1 246 R --> RUN : opens or exports the Page
Eleni Cojocariu 8.1 247 SRC --> RUN : read, never changed
248 RUN --> OUT
249 @enduml
250 {{/plantuml}}
251
Eleni Cojocariu 20.1 252 == A Macro in the Editor ==
Eleni Cojocariu 8.1 253
Eleni Cojocariu 20.1 254 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:
Eleni Cojocariu 8.1 255
Eleni Cojocariu 22.2 256 {{image reference="macro-editor.png" size="large" alt="The Table of Contents macro selected in the WYSIWYG editor, outlined as a single block."/}}
Eleni Cojocariu 8.1 257
Eleni Cojocariu 20.1 258 The list inside that block cannot be typed into, because XWiki builds it only when the Page is displayed.
259
260 == Name, Parameters and Content ==
261
262 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.
263
264 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:
265
266 {{code language="none"}}
267 {{box title="Release"}}
268 Freeze the branch.
269 {{/box}}
Eleni Cojocariu 8.1 270 {{/code}}
271
Eleni Cojocariu 20.1 272 A Macro that takes no content closes itself instead, like the ##toc## Macro that builds a table of contents.
Eleni Cojocariu 8.1 273
Eleni Cojocariu 20.1 274 == A Macro on the Displayed Page ==
Eleni Cojocariu 8.1 275
Eleni Cojocariu 20.1 276 Opening the Page displays what each Macro produced:
Eleni Cojocariu 8.1 277
Eleni Cojocariu 22.2 278 {{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."/}}
Eleni Cojocariu 20.1 279
280 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.
281
Eleni Cojocariu 8.1 282 == Where Macros Come From ==
283
Eleni Cojocariu 13.1 284 * Bundled with XWiki, which is the set a new wiki already has.
Eleni Cojocariu 8.1 285 * Added by an [[extension>>doc:documentation.xs.user.extensions.WebHome]] an administrator installed, and taken away again when that extension is uninstalled.
Eleni Cojocariu 24.1 286 * 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.
Eleni Cojocariu 8.1 287
288 == When a Macro Cannot Run ==
289
Eleni Cojocariu 20.1 290 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:
Eleni Cojocariu 8.1 291
Eleni Cojocariu 22.2 292 {{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."/}}
Eleni Cojocariu 8.1 293
Eleni Cojocariu 20.1 294 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.

Get Connected