XWiki Standard 9.8.1 Documentation » Programming Overview » XWiki Rendering Macros Overview

XWiki Rendering Macros Overview


The XWiki rendering macros allow you to develop reusable and distributable macro modules, without the need for compiling or packaging. A wiki macro is defined by creating a new wiki page and attaching an "XWiki.WikiMacroClass" object to it which contains the following properties:

  • Macro id: The identifier used when invoking the macro.
  • Macro name: The macro name that will be displayed by the Wysiwyg editor.
  • Macro description: A short description of the macro that will be displayed by the Wysiwyg editor.
  • Default category: Default category under which this macro should be listed.
  • Supports inline mode: Whether the macro can be used in an inline context or not.
  • Macro Visibility
  • Macro content type: Whether this macro should support a body or not.
  • Content description: A short description about the macro content that will be displayed by the Wysiwyg editor.
  • Macro code: The actual wiki code that will be evaluated when the macro is executed. You can use any XWiki content as long as it has the same syntax as the document.


A wiki macro can have one of the following visibility types:

  • Global - in a multi-wiki environment, the macro will be available on all the wikis of the farm
  • Current Wiki - the macro will only be available on the wiki it was created on
  • Current User - the macro will only be available for its author

Required Rights

The required rights depend on the macro visibility:

  • for a macro available globally, the macro author needs to have programming rights
  • if the macro is only available on the current wiki, the macro author must have admin rights
  • a macro available for the current user does not require special permissions, except for the edit rights


In order for a wiki macro to have parameters, you need to add an "XWiki.WikiMacroParameterClass" object per parameter. The class contains several fields that allow you to define your parameter:

  • Parameter name: Name of the parameter, referred when invoking the macro with parameters.
  • Parameter description: A short description of the parameter, which will be made available on the Wysiwyg editor.
  • Parameter mandatory: Indicates if this particular parameter is mandatory. The wiki macro will fail to execute if a mandatory parameter is missing.
  • Parameter default value

Access a Macro Parameter

A macro parameter can be accessed from any scripting language within the macro code using the syntax $xcontext.macro.params.parameterName where "parameterName" is the name of the parameter as explained in the above section.


To test your wiki macro, use the syntax {{macroId parameter1="<valueParameter1>" parameter2="<valueParameter2>" /}} or insert it using the "Wysiwyg" editor.

Wiki Macros Bundled with XWiki Enterprise

per page of Page
The environment prevents the table from loading data.

Search this space