User-Macros sind Codefragmente, die ein User im XWiki einmalig definieren und diese dann in beliebig viele Seiten nutzen kann. Das User-Macro selber wird in einer Wiki-Seite geschrieben und anschließend registriert. Leider schweigt sich die Dokumentation von XWiki darüber aus, wie Macros von einem User erstellt und registriert werden können.
Macro anlegen
Um ein Macros zu schreiben wird eine neue Seite angelegt. Das Macro in Velocity wird als Inhalt in die Seite geschrieben:
#macro(helloWorld,$param)
1 Hallo $param
#end
Bei dem Beispiel ist ‚helloWorld‘ der Name des Macros und $param der Name eine Parameters, welchen man später bei der Nutzung des Macros übergeben kann. Weiteres zu der Erstellung von Macros in Velocity Syntax erfährt man hier
Um das Macro zu nutzen muß es noch registriert werden. Dies erfolgt über die Admin-Oberfläche des XWikis unter dem Bereich ‚Programming‘. Dort wird der Name der Seite (inklusive Spacename) unter den Forumlarfeld ‚Velocity Macro Pages‘ eingetragen. In unserem Beispiel: ‚XWiki.helloworld‘.
Weiter unten, im Formularfeld ‚Macro Mapping‘ wird der Name des Macros registriert und zwar in der Form:
macroname=language:macro[:content][:parameter1[,parameterN]]
Für unser Beispiel gilt:
hallo=velocity:helloWorld:name
Es können logische Namen für Macro und Parameter verwendet werden. Wichtig ist die Einhaltung der Reihenfolge der Parameter.
Genutzt werden kann unser Macro dann in beliebigen Seiten mit:
{hallo:Tim}
oder
{hallo:name=Tim}
Content Macros
Content-Macros sind mehrzeilige Macros. Ein Content-Macro kann Text oder wiederum andere Macros enthalten. Um unserem Beispielmacro Zugriff auf den Content zu gewähren erhält das Macro einen zusätzlichen Parameter ‚$content’
#macro(helloWorld,$param,$content)
1 Hallo $param
$content
#end
Das Mapping für das Macro muß dahin angepasst werden, dass der Content an das Macro weitergegeben wird also:
hallo=velocity:helloWorld:content:name
Wichtig, ein Content Macro Mapping hat vier ‚:‘. Sonstige Parameter werden mit ‚,‘ getrennt.
Nun kann unser Macro wie folgt genutzt werden:
{hallo:name=Tim}
{rss:feed=/blogdata/public/feed/entries/rss|count=10}
{hallo}