Wiki source code of Rendering Macros

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

Hide last authors
Eleni Cojocariu 9.1 1 A [[rendering macro>>doc:extensions:Extension.RenderingMacroTransformation.WebHome]] is a component implementing the ##Macro## role, registered under the name it is called by in wiki syntax. [[Rendering Macros>>doc:documentation.xs.user.rendering-macros.WebHome]] describes what a macro is to the person reading the page; this one describes what a macro is in the code.
Lucas Charpentier 2.1 2
Eleni Cojocariu 9.1 3 == A Macro Is a Component ==
4
Eleni Cojocariu 12.1 5 The name a macro is called by in the syntax is its component hint, and nothing registers it separately. The class below is what makes {{code language="none"}}{{useravatar/}}{{/code}} work, declared in its module's ##META-INF/components.txt## like any other component:
Eleni Cojocariu 9.1 6
7 {{code language="java"}}
8 @Component
9 @Named("useravatar")
10 @Singleton
11 public class UserAvatarMacro extends AbstractMacro<UserAvatarMacroParameters>
12 {
13 public UserAvatarMacro()
14 {
15 super("User Avatar", DESCRIPTION, UserAvatarMacroParameters.class);
16 setDefaultCategories(Set.of(DEFAULT_CATEGORY_CONTENT));
17 }
18
19 @Override
20 public List<Block> execute(UserAvatarMacroParameters parameters, String content,
21 MacroTransformationContext context) throws MacroExecutionException
22 {
23 // Build and return the blocks the macro call is replaced by.
24 }
25
26 @Override
27 public boolean supportsInlineMode()
28 {
29 return true;
30 }
31 }
Lucas Charpentier 2.1 32 {{/code}}
33
Eleni Cojocariu 18.1 34 Changing the ##@Named## value renames the macro. A hint of the form ##macroname/syntaxid##, ##mymacro/xwiki/2.0## for instance, registers the macro for that one syntax instead of for all of them. Two components declared on the same hint are resolved by component priority, which is how an extension replaces a bundled macro without touching it.
Lucas Charpentier 2.1 35
Eleni Cojocariu 9.1 36 == A Macro Returns Blocks, Not Text ==
37
Eleni Cojocariu 18.1 38 ##execute## returns a list of ##Block##s, and the macro transformation substitutes them for the macro call in the XDOM, the tree the parser produced from the page. A renderer only ever sees that tree, once every macro in it has run. The components a macro injects to build those blocks are in [[Java Macro Helpers>>doc:documentation.xs.dev.rendering-macros.java-macro-helpers.WebHome]].
Eleni Cojocariu 9.1 39
40 {{plantuml}}
41 @startuml
42 !theme bluegray
Eleni Cojocariu 23.5 43 ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under
44 ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm.
45 skinparam activity {
46 BackgroundColor #0568AE
47 BorderColor #034873
48 FontColor #FFFFFF
49 StartColor #04538B
50 EndColor #04538B
51 BarColor #5A5A5A
Eleni Cojocariu 23.6 52 ' Diamonds are blue with white text, not light with dark text: a labelled
53 ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from
54 ' FontColor above, so a light fill draws that one box white on white, and no
55 ' selector reaches it without reaching the decision diamonds too.
56 DiamondBackgroundColor #0568AE
57 DiamondBorderColor #034873
58 DiamondFontColor #FFFFFF
Eleni Cojocariu 23.5 59 }
60 skinparam state {
61 BackgroundColor #0568AE
62 BorderColor #034873
63 FontColor #FFFFFF
64 AttributeFontColor #FFFFFF
65 StartColor #04538B
66 EndColor #04538B
67 }
68 skinparam class {
69 BackgroundColor #0568AE
70 BorderColor #034873
71 FontColor #FFFFFF
72 HeaderBackgroundColor #0568AE
73 AttributeFontColor #FFFFFF
74 StereotypeFontColor #262626
75 }
76 skinparam object {
77 BackgroundColor #0568AE
78 BorderColor #034873
79 FontColor #FFFFFF
80 AttributeFontColor #FFFFFF
81 StereotypeFontColor #262626
82 }
83 skinparam participant {
84 BackgroundColor #0568AE
85 BorderColor #034873
86 FontColor #FFFFFF
87 }
88 skinparam actor {
89 BackgroundColor #F5F5F5
90 BorderColor #5A5A5A
91 FontColor #262626
92 }
93 skinparam component {
94 BackgroundColor #0568AE
95 BorderColor #034873
96 FontColor #FFFFFF
97 }
98 skinparam collections {
99 BackgroundColor #0568AE
100 BorderColor #034873
101 FontColor #FFFFFF
102 }
103 skinparam queue {
104 BackgroundColor #0568AE
105 BorderColor #034873
106 FontColor #FFFFFF
107 }
108 skinparam stack {
109 BackgroundColor #0568AE
110 BorderColor #034873
111 FontColor #FFFFFF
112 }
113 ' database, control, entity, boundary and interface draw their label beside or
114 ' under the icon, on the page, in some diagram types: their text stays dark.
115 skinparam database {
116 BackgroundColor #F5F5F5
117 BorderColor #5A5A5A
118 FontColor #262626
119 }
120 skinparam control {
121 BackgroundColor #0568AE
122 BorderColor #034873
123 FontColor #262626
124 }
125 skinparam entity {
126 BackgroundColor #0568AE
127 BorderColor #034873
128 FontColor #262626
129 }
130 skinparam boundary {
131 BackgroundColor #0568AE
132 BorderColor #034873
133 FontColor #262626
134 }
135 skinparam usecase {
136 BackgroundColor #0568AE
137 BorderColor #034873
138 FontColor #FFFFFF
139 StereotypeFontColor #FFFFFF
140 }
141 skinparam card {
142 BackgroundColor #04538B
143 BorderColor #034873
144 FontColor #FFFFFF
145 }
146 skinparam note {
147 BackgroundColor #04538B
148 BorderColor #034873
149 FontColor #FFFFFF
150 }
151 skinparam storage {
152 BackgroundColor #8A4A00
153 BorderColor #8A4A00
154 FontColor #FFFFFF
155 }
156 skinparam agent {
157 BackgroundColor #8A4A00
158 BorderColor #8A4A00
159 FontColor #FFFFFF
160 }
161 skinparam interface {
162 BackgroundColor #A62222
163 BorderColor #A62222
164 FontColor #262626
165 }
166 skinparam node {
167 BackgroundColor #F5F5F5
168 BorderColor #5A5A5A
169 FontColor #262626
170 }
171 skinparam cloud {
172 BackgroundColor #F5F5F5
173 BorderColor #5A5A5A
174 FontColor #262626
175 }
176 skinparam artifact {
177 BackgroundColor #F5F5F5
178 BorderColor #5A5A5A
179 FontColor #262626
180 }
181 skinparam file {
182 BackgroundColor #F5F5F5
183 BorderColor #5A5A5A
184 FontColor #262626
185 }
186 skinparam rectangle {
187 BackgroundColor #FFFFFF
188 BorderColor #5A5A5A
189 FontColor #262626
190 StereotypeFontColor #0568AE
191 }
192 skinparam folder {
193 BackgroundColor #F5F5F5
194 BorderColor #8A4A00
195 FontColor #8A4A00
196 }
197 skinparam frame {
198 BackgroundColor #F5F5F5
199 BorderColor #04538B
200 FontColor #04538B
201 }
202 skinparam package {
203 BackgroundColor #FFFFFF
204 BorderColor #0568AE
205 FontColor #262626
206 }
207 skinparam partition {
208 BackgroundColor #FFFFFF
209 BorderColor #0568AE
210 FontColor #0568AE
211 }
212 skinparam swimlane {
213 BorderColor #0568AE
214 TitleBackgroundColor #F5F5F5
215 TitleFontColor #0568AE
216 }
217 skinparam sequence {
218 BoxBackgroundColor #F5F5F5
219 BoxBorderColor #5A5A5A
220 BoxFontColor #262626
221 DelayFontColor #262626
222 GroupBorderColor #5A5A5A
223 GroupFontColor #262626
224 LifeLineBorderColor #5A5A5A
225 LifeLineBackgroundColor #F5F5F5
226 TitleFontColor #0568AE
227 StartColor #0568AE
228 EndColor #0568AE
229 BorderColor #0568AE
230 }
231 skinparam arrow {
232 Color #0568AE
233 FontColor #262626
234 }
235 skinparam legend {
236 BackgroundColor #F5F5F5
237 BorderColor #5A5A5A
238 FontColor #262626
239 }
240 skinparam stereotype {
241 CBackgroundColor #F5F5F5
242 CBorderColor #5A5A5A
243 ABackgroundColor #F5F5F5
244 ABorderColor #5A5A5A
245 IBackgroundColor #F5F5F5
246 IBorderColor #5A5A5A
247 EBackgroundColor #F5F5F5
248 EBorderColor #5A5A5A
249 NBackgroundColor #F5F5F5
250 NBorderColor #5A5A5A
251 }
252 skinparam ArrowColor #0568AE
253 ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form
254 ' leaks its background onto every element in the diagram.
255 skinparam titleFontColor #0568AE
256 skinparam titleBorderColor #5A5A5A
257 ' Links otherwise take bluegray's white root colour, unreadable on a light fill.
258 <style>
259 root {
260 HyperLinkColor #0568AE
261 }
262 element {
263 HyperLinkColor #FFFFFF
264 }
265 actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface,
266 legend, node, package, rectangle {
267 HyperLinkColor #0568AE
268 }
269 </style>
270 ' ---- end XWiki accessible diagram palette ----
Eleni Cojocariu 9.1 271 skinparam nodesep 30
272 skinparam ranksep 40
273
274 file "Stored page content:\nwiki syntax holding\na macro call" as SRC
275 rectangle "Parser" as P
276 card "XDOM:\na MacroBlock among\nthe other blocks" as X1
277 rectangle "Macro transformation\nlooks the component up by\nthe macro name, calls execute()" as MT
278 card "XDOM:\nthe blocks the macro\nreturned, in its place" as X2
279 rectangle "Renderer" as R
280 file "HTML, LaTeX,\nplain text, ..." as OUT
281
282 SRC --> P
283 P --> X1
284 X1 --> MT
285 MT --> X2
286 X2 --> R
287 R --> OUT
288 @enduml
289 {{/plantuml}}
290
291 Two things follow, and they are what a first macro usually gets wrong:
292
293 * **The output is syntax-independent.** A macro returning an ##ImageBlock## renders in HTML, in a PDF export and in LaTeX alike, while one returning raw HTML renders in none of the others.
294 * **A macro may emit another macro call**, and that call is executed in turn, because what the macro returned went back into the tree rather than into the output.
295
296 Macros are also not run in the order they are written. The transformation runs them by priority, lowest first, and ##AbstractMacro## defaults to ##1000##. A macro that has to act before the ones its own content holds lowers it, as the ##container## macro does:
297
298 {{code language="java"}}
299 @Override
300 public int getPriority()
301 {
302 return 750;
303 }
304 {{/code}}
305
Eleni Cojocariu 21.1 306 Priority is one of several things the transformation decides rather than the macro. [[Macro Transformation>>doc:documentation.xs.dev.rendering-macros.macro-transformation.WebHome]] describes how it runs the macros of a page, and [[Macro Execution Rules>>doc:documentation.xs.dev.rendering-macros.macro-execution-rules.WebHome]] covers the rest, including when a macro is told not to execute at all.
Eleni Cojocariu 18.1 307
Eleni Cojocariu 9.1 308 == The Parameters Bean Is What the Editors Show ==
309
310 A macro declares its parameters as a bean, and the descriptor the editors read is built from it. The annotations on each setter are the whole of the parameter metadata, so a parameter is described once, in the code:
311
312 {{code language="java"}}
313 public class UserAvatarMacroParameters
314 {
315 private String username;
316
317 @PropertyMandatory
318 @PropertyDescription("the name of the user whose avatar is to be displayed")
319 @PropertyDisplayType(UserReference.class)
320 public void setUsername(String username)
321 {
322 this.username = username;
323 }
324 }
325 {{/code}}
326
Eleni Cojocariu 22.1 327 ##@PropertyDescription## is the help text beside the field, ##@PropertyMandatory## makes the editor refuse an empty value, and ##@PropertyDisplayType## replaces the plain text field by a [[picker>>doc:documentation.xs.dev.rendering-macros.macro-parameter-pickers.WebHome]], here the user picker. The [[Properties Module>>doc:extensions:Extension.Properties Module||anchor="HPopulateaJavaBean"]] documents every annotation a parameter bean can carry. The categories the macro is listed under come from ##setDefaultCategories##; ##AbstractMacro## defines the bundled ones, listed in [[Macro Categories>>doc:documentation.xs.dev.rendering-macros.macro-categories.WebHome]]: ##Formatting##, ##Content##, ##Navigation##, ##Development##, ##Layout##, ##Internal## and ##Deprecated##.
Eleni Cojocariu 9.1 328
Lucas Charpentier 17.8 329 == The Content Holds the Main Data ==
330
331 The main data of a macro goes in its content, between the opening and closing tags, whether it is rich text like a message or raw text like a code snippet. A parameter is for data that is always short, such as a title. The content is declared by a content descriptor, which the editors read like the parameters bean:
332
333 {{code language="java"}}
334 super("Info", DESCRIPTION,
335 new DefaultContentDescriptor("Content of the message", true, Block.LIST_BLOCK_TYPE),
336 MessageMacroParameters.class);
337 {{/code}}
338
Eleni Cojocariu 18.1 339 The description is the help text of the content field and the boolean makes the content mandatory. The type decides how the WYSIWYG editor edits it: ##Block.LIST_BLOCK_TYPE## declares wiki content, edited in place like the rest of the page, while the default ##String## declares raw text, edited in a text area of the "Edit Macro" dialog. When the content accepts less than the rest of the page, the description says what it accepts, so the restriction is visible before the macro fails to render it. Declaring the type is only half of it: the macro must also mark which of the blocks it returns are editable, as [[Make a Macro Editable Inline>>doc:documentation.xs.dev.rendering-macros.make-macro-editable-inline.WebHome]] describes.
Lucas Charpentier 17.8 340
Eleni Cojocariu 9.1 341 == Java Macro or Wiki Macro ==
342
Eleni Cojocariu 15.1 343 A macro can also be written as a wiki page carrying an ##XWiki.WikiMacroClass## object, with no Java and no build, see [[Wiki Macros>>doc:documentation.xs.dev.rendering-macros.wiki-macros.WebHome]]. That object holds the same metadata the Java descriptor does, plus the macro code itself and the visibility that decides which component manager the macro is registered in.
Eleni Cojocariu 9.1 344
345 |=Characteristic|=Java macro|=Wiki macro
346 |Easy to debug, and to write an automated test for|(/)|(x)
347 |Optimized for performance|(/)|(x)
Eleni Cojocariu 15.1 348 |[[Advanced parameter metadata>>doc:documentation.xs.dev.rendering-macros.wiki-macros.wiki-macro-fields.WebHome]], such as [[pickers>>doc:documentation.xs.dev.rendering-macros.macro-parameter-pickers.WebHome]] and deprecation|(/)|(/)
Eleni Cojocariu 9.1 349 |Needs no development skills and no build|(x)|(/)
350 |Fast to write, and easy for a user to customize afterwards|(x)|(/)
351
Eleni Cojocariu 18.1 352 [[Write a Macro in Java>>doc:documentation.xs.dev.rendering-macros.write-java-macro.WebHome]] is the Java tutorial, and [[Write a Macro in a Wiki Page>>doc:documentation.xs.dev.rendering-macros.wiki-macros.write-wiki-macro.WebHome]] the wiki one.
Eleni Cojocariu 9.1 353
354 == Executing Content Is a Rights Decision ==
355
Eleni Cojocariu 12.1 356 A macro that renders or executes the content it is handed runs what a page author wrote, so it also needs a required-rights analyzer. The analyzer does not enforce anything; it reports what the macro's content will need, and without one nothing tells the author to declare those rights or shows a reviewer what the page will run.
Eleni Cojocariu 9.1 357
358 A macro whose result may be reused across requests extends ##AbstractExecutedContentMacro## rather than driving the asynchronous renderer by hand; it then takes the standard ##async##, ##cached## and ##context## parameters.

Get Connected