Velocity Macro

The Velocity macro executes a Velocity script and applies current page parser on the result.


See the example below:

The Velocity script is executed before anything else so if you put an Include macro inside the Velocity macro you will not be able to use any Velocity macro/variable defined in the included page because the include is done after the Velocity is executed. Take care of putting Include macro outside of Velocity macro.

Parameters definition

NameOptionalAllowed valuesDefault valueDescription
outputyestrue/falsetrueIndicate if the macro should print something or not.
filteryesnone/html/indentindentIndicate a filter to apply on Velocity content before and after script execution. The default filter (indent) removes all first whites spaces of the lines to support code indentation. See Velocity Macro Filter for more details.


#set($words = ["Some", "velocity", "code"])
#foreach($word in $words)
  $word ##

Velocity Macro Filter

It is possible to filter the Velocity macro content before and after the Velocity Engine execution. You can set the default filter to use in by the setting the property macro.velocity.filter. You can also set the filter to use directly when writing the macro by setting the macro filter parameter.

Existing Filters

By default the provided filters are:


macro.velocity.filter=none OR macro.velocity.filter= OR {{macro filter="none"}} OR {{macro filter=""}} means "Do nothing" because this was the behavior before XWiki Platform 1.9.


macro.velocity.filter=indent OR {{macro filter="indent"}}

Remove all first white spaces of the lines to support source code indentation without generating white space into the resulting HTML.

#if (test)
  Some Text

Is the same as:

#if (test)
Some Text


macro.velocity.filter=html OR {{macro filter="html"}}

The goal is to make the Velocity script more readable by supporting indentation and code organization with empty lines and putting if/else/.. on their own lines.

This is done by applying a html to clean the white spaces and new lines. Any group of spaces/new lines is replaced by a space, except for some specific use cases:

  • spaces and new lines following a Velocity keyword like if/else/... are removed instead of being replaced by a space.
  • spaces before a Velocity keyword like if/else/... are removed.
  • white spaces and new lines before and after $nl are removed instead of being replaced by a space.

So for instance:

The beginning of the line

#if (true)
  #if (true)
    followed by the end of the line.

will generate:

<p>The beginning of the line followed by the end of the line. <p>

instead of:

<p>The beginning of the line
&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;followed by the end of the line.

The filter injects the mapping $sp and $nl in order to be able to force a space of a new line (like putting a <br/> in html).

Create a Custom Filter

The Velocity Macro content filters are XWiki components. In order to add one, you just need to implement "VelocityMacroFilter" component interface and set the right component attributes.


Related Pages

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]