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


Most popular tags

Failed to execute the [groovy] macro
  1. access rights
  2. activity stream
  3. annotation
  4. attachment
  5. comment
  6. Document Tree Macro
  7. export
  8. Extension Manager
  9. Flamingo skin
  10. global user
  11. Groovy event listener
  12. group
  13. nested page
  14. search
  15. skin
  16. syntax
  17. user
  18. user profile
  19. velocity macros
  20. wiki
  21. wysiwyg
  22. XWiki Applications
  23. xwikiattachment_archive table
  24. xwikiattachment table
  25. xwikiattrecyclebin table
  26. xwikiproperties table

[Display all tags from this space]