cogDefines the ability to store macros into wiki pages
TypeJAR
Developed by

XWiki Development Team

Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Standard

Installable with the Extension Manager

Description

How to use

You simply need to add an object of type XWiki.WikiMacroClass to your wiki page, as shown below:

Macro.png

You should follow our wiki macro tutorial to learn more about writing wiki macros.

To see a list of wiki macros installed on your wiki, check the Help Center, the Syntax Help or navigate to the XWiki.XWikiSyntaxMacrosList page.

Alternatively, you can also navigate to the XWiki.WikiMacroClass page:

WikiMacroClass.png

Bindings

There are several bindings that are available in the code content for the macro.

Starting with XWiki 10.11.9, 11.3.2 and 11.6RC1 all of them are available through $wikimacro:

  • wikimacro.parameters: The list of all parameters passed to the macro with value converted to the given type, e.g. wikimacro.parameters.myparam would return the value for the myparam parameter in {{mymacro myparam="myvalue" ...}}.
  • wikimacro.content: The macro content
  • wikimacro.context: The Macro Transformation Context (MacroTransformationContext) which provides access to information such as the current XDOM Block (and thus access to all parent blocks too. For example a TOC macro would need to find all the Heading blocks), the syntax of the content of the macro, whether the macro is inline or not, etc. This binding is not set if the wikimacro is executed asynchronously.
  • wikimacro.result: This is an output parameter into which the result of the macro can be stored if you wish to directly return the desired list of rendering blocks without having to render them first to let them be parsed back by the macro transformation. The benefits are that it could be a lots quicker and most of all it means supporting syntaxes which does not provide any renderer. It also makes it possible to generate some XDOM which is impossible to write in some syntaxes.
  • wikimacro.doc: The com.xpn.xwiki.api.Document instance of the document in which the macro is defined.

Some bindings are also available through $xcontext.macro but they are now considered as deprecated:

  • xcontext.macro.params: The list of all parameters passed to the macro, e.g. xcontext.macro.params.myparam would return the String value for the myparam parameter in {{mymacro myparam="myvalue" ...}}.
  • xcontext.macro.content: The macro content
  • xcontext.macro.context: The Macro Transformation Context (MacroTransformationContext) which provides access to information such as the current XDOM Block (and thus access to all parent blocks too. For example a TOC macro would need to find all the Heading blocks), the syntax of the content of the macro, whether the macro is inline or not, etc.
  • xcontext.macro.result: This is an output parameter into which the result of the macro can be stored if you wish to directly return the desired list of rendering blocks without having to render them first to let them be parsed back by the macro transformation. The benefits are that it could be a lots quicker and most of all it means supporting syntaxes which does not provide any renderer. It also makes it possible to generate some XDOM which is impossible to write in some syntaxes.
  • xcontext.macro.doc: The com.xpn.xwiki.api.Document instance of the document in which the macro is defined.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-rendering-wikimacro-store 11.9):

  • org.xwiki.platform:xwiki-platform-rendering-wikimacro-api 11.9
  • org.xwiki.platform:xwiki-platform-rendering-wikimacro-macro-wikimacrocontent 11.9
  • org.xwiki.platform:xwiki-platform-oldcore 11.9
  • org.xwiki.platform:xwiki-platform-wiki-default 11.9
  • org.xwiki.platform:xwiki-platform-rendering-parser 11.9
  • org.xwiki.platform:xwiki-platform-component-wiki 11.9
  • org.xwiki.platform:xwiki-platform-rendering-async-default 11.9
  • org.xwiki.rendering:xwiki-rendering-api 11.9
  • org.xwiki.rendering:xwiki-rendering-transformation-macro 11.9
Tags:
Created by Vincent Massol on 2018/02/12 15:31
    

Get Connected