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

XWiki Rendering Macros Overview

Definition

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.

Visibility

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

Parameters

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.

Invocation

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

Search this space

 

External Links