Explanation

A wiki macro is a rendering macro written as a wiki page instead of Java code: nothing to compile, no jar to package and no restart. Its author creates a page, attaches an XWiki.WikiMacroClass object to it, and the macro is available as soon as the page is saved.

Write a Macro in a Wiki Page walks through that, Wiki Macro Fields lists every field of the two XClasses involved, and the Wiki Macro Store is the reference documentation of the feature itself.

Visibility and rights

The "Macro visibility" field says where the macro can be used, and what rights its author needs for that:

A macro that uses protected API needs its author to have Programming Rights as well.

A wiki macro always executes with the rights of its own author, never with those of the author of the page that calls it. So the author of the macro is the only one who needs those rights, however many pages use it.

Bindings

The usual scripting bindings are available in the macro code, and the Wiki Macro Store documents the ones wiki macros add, such as $wikimacro.

They are bound to the page where the macro is called, not to the page that defines it: $doc is the calling page. That is what lets one macro produce a different result on every page that uses it.

In the WYSIWYG editor

A wiki macro is treated like any other rendering macro, and it is offered in the editor's macro list, under "Insert" then "Other Macros".

Picking it opens a form built from the macro's own fields: the content, described by the "Content description" field, and one entry per XWiki.WikiMacroParameterClass object. The name, the description and the labels it shows are the macro's own, unless they are translated into the language of the reader.

Editing the content and the parameters in place

A macro that displays its own content with {{wikimacrocontent/}}, or one of its parameters with {{wikimacroparameter name="..."/}}, lets the users of the macro edit those values in the page itself rather than in that form. See the CKEditor integration.

It works only where the content, or the parameter, is of type Wiki.

Macros that generate JavaScript

The editor executes the macro in edit mode too, and feeds the result back into the document being edited. JavaScript skin extensions are not loaded there, so a macro whose script rewrites the page can have its own output saved into the document. Guard that code with the current action:

{{velocity}}
#if("$xcontext.action" != "edit")
{{html}}
<script>
// the code that must not run while the page is being edited
</script>
{{/html}}
#end
{{/velocity}}

Returning blocks directly

Rather than rendering its result to wiki syntax that the macro transformation parses back, a macro can assign the rendering blocks themselves to $wikimacro.result. It is faster, it works for syntaxes that have no renderer, and it can produce an XDOM that no syntax is able to express.

This Groovy macro returns a link to a relative URL:

{{groovy}}
import org.xwiki.rendering.block.LinkBlock
import org.xwiki.rendering.block.WordBlock
import org.xwiki.rendering.listener.reference.ResourceReference
import org.xwiki.rendering.listener.reference.ResourceType

def reference = new ResourceReference("/xwiki/bin/edit/Main/WebHome", ResourceType.PATH)
def linkBlock = new LinkBlock(List.of(new WordBlock("Edit home page")), reference, false)

wikimacro.result = List.of(linkBlock)
{{/groovy}}

A macro can also parse content into an XDOM itself, through the rendering script service. This one wraps its own content in a styled group:

{{velocity output="no"}}
## read the content the macro was called with
#set($wikiresult = $wikimacro.content)
## wrap it
#set($wikiresult = "(% class='newstyle' %)((($wikiresult)))")
## parse it, and return the blocks of the result
#set($wikimacro.result = $services.rendering.parse($wikiresult, $xwiki.getCurrentContentSyntaxId()).getChildren())
{{/velocity}}

FAQ

Why does $doc point at another page than the macro?

Because the bindings are those of the page the macro is called from. The macro page itself is not $doc while the macro runs.

Why can the content of my macro not be edited in place?

Either its type is not Wiki, or the macro is used inside a sentence instead of on its own line.

More

To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.

Related

• Rendering Macros
• Macro Parameter Pickers