Wiki source code of Write a Macro in a Wiki Page
Last modified by Eleni Cojocariu on 2026/10/13 13:33
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | This tutorial builds a ##hello## macro that greets the reader, from an empty page to a macro every page of the wiki can call. The macro itself does very little; what it walks through is the creation process, which is the same for every wiki macro. See [[Wiki Macros>>doc:documentation.xs.dev.rendering-macros.wiki-macros.WebHome]] for what a wiki macro is and with which rights it runs. | ||
| 2 | |||
| 3 | You need to be an [[advanced user>>doc:documentation.xs.user.base.page.edit.simple-advanced.WebHome]] to reach the [[object editor>>doc:documentation.xs.user.base.page.edit.edit-object-editor.WebHome]]. | ||
| 4 | |||
| 5 | 1. Create a page to hold the macro, and add an object of type ##XWiki.WikiMacroClass## to it in the object editor. | ||
| 6 | 1. Fill in the fields of that object: ##hello## in "Macro id", ##Hello## in "Macro name", a short text in "Macro description", "Current Wiki" in "Macro visibility" and "Optional" in "Macro content availability". Leave the other fields at their default value, see [[Wiki Macro Fields>>doc:documentation.xs.dev.rendering-macros.wiki-macros.wiki-macro-fields.WebHome]]. | ||
| 7 | 1. Write what the macro does in "Macro code", in the syntax of the page:((( | ||
| 8 | {{code language="velocity"}} | ||
| 9 | {{velocity}}Hello World!{{/velocity}} | ||
| 10 | {{/code}} | ||
| 11 | |||
| 12 | {{image reference="wiki-macro-object.png" size="large" alt="The object editor, showing the XWiki.WikiMacroClass object of the hello macro with its fields filled in"/}} | ||
| 13 | ))) | ||
| 14 | 1. Save the page. The macro is available under its id at once, with nothing to restart. | ||
| 15 | 1. Call the macro from any page, the way every other macro is called:((( | ||
| 16 | {{code language="xwiki"}} | ||
| 17 | {{hello/}} | ||
| 18 | {{/code}} | ||
| 19 | ))) | ||
| 20 | 1. View that page. It displays the greeting:((( | ||
| 21 | {{image reference="hello-macro-result.png" size="large" alt="A wiki page displaying Hello World!, the output of the hello macro"/}} | ||
| 22 | ))) | ||
| 23 | 1. Display the content the caller passes, by adding the ##~{~{wikimacrocontent}}## macro to "Macro code". That content then becomes editable in place in the WYSIWYG editor, see [[Wiki Macros>>doc:documentation.xs.dev.rendering-macros.wiki-macros.WebHome]].((( | ||
| 24 | {{code language="xwiki"}} | ||
| 25 | {{velocity}}Hello World!{{/velocity}} | ||
| 26 | |||
| 27 | {{wikimacrocontent/}} | ||
| 28 | {{/code}} | ||
| 29 | ))) | ||
| 30 | 1. Add a parameter, by adding an object of type ##XWiki.WikiMacroParameterClass## to the same page and setting its "Parameter name" to ##greetUser##:((( | ||
| 31 | {{image reference="wiki-macro-parameter-object.png" size="large" alt="The object editor, showing the greetUser XWiki.WikiMacroParameterClass object of the hello macro"/}} | ||
| 32 | ))) | ||
| 33 | 1. Read that parameter in "Macro code", to greet the current user when it is set:((( | ||
| 34 | {{code language="velocity"}} | ||
| 35 | {{velocity}} | ||
| 36 | #if ($wikimacro.parameters.greetUser && "XWiki.XWikiGuest" != "$xcontext.user") | ||
| 37 | Hello $services.rendering.escape($xwiki.user.email, 'xwiki/2.1')! | ||
| 38 | #else | ||
| 39 | Hello world! | ||
| 40 | #end | ||
| 41 | {{/velocity}} | ||
| 42 | {{/code}} | ||
| 43 | |||
| 44 | {{warning}} | ||
| 45 | A parameter is not bound as a variable of its own. ##$greetUser## is undefined; the value is read from ##$wikimacro.parameters.greetUser##. | ||
| 46 | {{/warning}} | ||
| 47 | |||
| 48 | {{info}} | ||
| 49 | A parameter value can also be displayed on its own, with no script, through the ##~{~{wikimacroparameter~}~}## macro: ##Hello ~{~{wikimacroparameter name="greetUser" /~}~}##. | ||
| 50 | {{/info}} | ||
| 51 | ))) | ||
| 52 | 1. Call the macro with the parameter:((( | ||
| 53 | {{code language="xwiki"}} | ||
| 54 | {{hello greetUser="true"/}} | ||
| 55 | {{/code}} | ||
| 56 | |||
| 57 | {{info}} | ||
| 58 | When the value comes from a variable, wrap the call in the ##velocity## macro, otherwise the variable reaches the macro as the literal text you wrote: | ||
| 59 | |||
| 60 | {{code language="velocity"}} | ||
| 61 | {{velocity}} | ||
| 62 | #set ($greet = true) | ||
| 63 | {{hello greetUser="$greet"/}} | ||
| 64 | {{/velocity}} | ||
| 65 | {{/code}} | ||
| 66 | {{/info}} | ||
| 67 | ))) | ||
| 68 | 1. View the page. The macro greets the current user, while the call without the parameter still displays the plain greeting:((( | ||
| 69 | {{image reference="hello-macro-parameter-result.png" size="large" alt="A wiki page displaying Hello world! and Hello [email protected]!, the output of the hello macro called without and with the greetUser parameter"/}} | ||
| 70 | ))) |
