Tutorial

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 for what a wiki macro is and with which rights it runs.

You need to be an advanced user to reach the object editor.

1. Create a page to hold the macro, and add an object of type XWiki.WikiMacroClass to it in the object editor.
2. 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.
3. Write what the macro does in "Macro code", in the syntax of the page:

   {{velocity}}Hello World!{{/velocity}}

   

4. Save the page. The macro is available under its id at once, with nothing to restart.
5. Call the macro from any page, the way every other macro is called:

   {{hello/}}

6. View that page. It displays the greeting:

   

7. 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.

   {{velocity}}Hello World!{{/velocity}}
   
   {{wikimacrocontent/}}

8. Add a parameter, by adding an object of type XWiki.WikiMacroParameterClass to the same page and setting its "Parameter name" to greetUser:

   

9. Read that parameter in "Macro code", to greet the current user when it is set:

   {{velocity}}
   #if ($wikimacro.parameters.greetUser && "XWiki.XWikiGuest" != "$xcontext.user")
     Hello $services.rendering.escape($xwiki.user.email, 'xwiki/2.1')!
   #else
     Hello world!
   #end
   {{/velocity}}

   Warning

   A parameter is not bound as a variable of its own. $greetUser is undefined; the value is read from $wikimacro.parameters.greetUser.

   Information

   A parameter value can also be displayed on its own, with no script, through the {{wikimacroparameter}} macro: Hello {{wikimacroparameter name="greetUser" /}}.

10. Call the macro with the parameter:

    {{hello greetUser="true"/}}

    Information

    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:

    {{velocity}}
    #set ($greet = true)
    {{hello greetUser="$greet"/}}
    {{/velocity}}

11. View the page. The macro greets the current user, while the call without the parameter still displays the plain greeting:

    

FAQ

Why is $greetUser empty in my macro code?

Because a parameter is not bound as a variable of its own. Read it from $wikimacro.parameters.greetUser.

Why does the macro ignore the parameter I pass from a variable?

Because the variable is only resolved inside a script. Wrap the call in the velocity macro, otherwise the macro receives the name of the variable as text.

Related

• Wiki Macros
• Wiki Macro Fields
• Translate a Wiki Macro
• Write a Macro in Java