Velocity Macro Filter (XWiki.org)

XWiki Platform 1.9 introduced the possibility to filter the Velocity macro content before and after the Velocity Engine execution.

6

7

You can set the default filter to use in xwiki.properties 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 as you can see in the previous table.

= Existing filters =

By default the provided filters are:

== ##none## ==

macro.velocity.filter=none

macro.velocity.filter=

Do nothing, it's what happened before XWiki Platform 1.9

== ##indent## ==

macro.velocity.filter=indent

Remove all first whites spaces of lines to support source code indentation without generating whitespace in the resulting HTML.

#if (test)

Some Text

#end

Is the same as

#if (test)

Some Text

#end

== ##html## ==

macro.velocity.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.

70

71

This is done by applying a html like cleaning on white spaces and new lines meaning that any group of spaces/new lines is replaced by a space except for some specific use cases which are:

72

* spaces and new lines following a velocity keyword like if/else/... are removed instead of replaced by a space

73

* spaces before a velocity keyword like if/else/... are removed

74

* white spaces and new lines before and after $nl are removed instead of replaced by a space

So for example:

The beginning of the line

#if (true)

#if (true)

followed by the end of the line.

#else

.

#end

#else

.

#end

will generate

{{code}}The beginning of the line followed by the end of the line. {{/code}}

instead of

The beginning of the line

102

103

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;followed by the end of the line.

The filter inject the mapping $sp and $nl to be able to force a space of a new line (like putting a in html).

109

110

= Create a custom filter =

111

112

The velocity macro content filter are xwiki components so to add one you just need to implements VelocityMacroFilter component interface and set the right component attributes. See [[xwiki:Documentation.DevGuide.WritingComponents]] for more details on XWiki components.

Wiki source code of Velocity Macro Filter

Quick Links

My Recent Modifications

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected

author	version	line-number	content
		1	{{box cssClass="floatinginfobox" title="Contents"}}
		2	{{toc/}}
		3	{{/box}}
		4
		5	XWiki Platform 1.9 introduced the possibility to filter the Velocity macro content before and after the Velocity Engine execution.
		6
		7	You can set the default filter to use in xwiki.properties 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 as you can see in the previous table.
		8
		9	= Existing filters =
		10
		11	By default the provided filters are:
		12
		13	== ##none## ==
		14
		15	{{code}}
		16	macro.velocity.filter=none
		17	{{/code}}
		18
		19	{{code}}
		20	macro.velocity.filter=
		21	{{/code}}
		22
		23	{{code}}
		24	{{macro filter="none"}}
		25	{{/code}}
		26
		27	{{code}}
		28	{{macro filter=""}}
		29	{{/code}}
		30
		31	Do nothing, it's what happened before XWiki Platform 1.9
		32
		33	== ##indent## ==
		34
		35	{{code}}
		36	macro.velocity.filter=indent
		37	{{/code}}
		38
		39	{{code}}
		40	{{macro filter="indent"}}
		41	{{/code}}
		42
		43	Remove all first whites spaces of lines to support source code indentation without generating whitespace in the resulting HTML.
		44
		45	{{code}}
		46	#if (test)
		47	Some Text
		48	#end
		49	{{/code}}
		50
		51	Is the same as
		52
		53	{{code}}
		54	#if (test)
		55	Some Text
		56	#end
		57	{{/code}}
		58
		59	== ##html## ==
		60
		61	{{code}}
		62	macro.velocity.filter=html
		63	{{/code}}
		64
		65	{{code}}
		66	{{macro filter="html"}}
		67	{{/code}}
		68
		69	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.
		70
		71	This is done by applying a html like cleaning on white spaces and new lines meaning that any group of spaces/new lines is replaced by a space except for some specific use cases which are:
		72	* spaces and new lines following a velocity keyword like if/else/... are removed instead of replaced by a space
		73	* spaces before a velocity keyword like if/else/... are removed
		74	* white spaces and new lines before and after $nl are removed instead of replaced by a space
		75
		76	So for example:
		77
		78	{{code}}
		79	{{velocity}}
		80	The beginning of the line
		81
		82	#if (true)
		83	#if (true)
		84	followed by the end of the line.
		85	#else
		86	.
		87	#end
		88	#else
		89	.
		90	#end
		91	{{/velocity}}
		92	{{/code}}
		93
		94	will generate
		95
		96	{{code}}<p>The beginning of the line followed by the end of the line. <p>{{/code}}
		97
		98	instead of
		99
		100	{{code}}
		101	<p>The beginning of the line
		102	<br/>
		103	&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;followed by the end of the line.
		104	<br/>
		105	<p>
		106	{{/code}}
		107
		108	The filter inject the mapping $sp and $nl to be able to force a space of a new line (like putting a <br/> in html).
		109
		110	= Create a custom filter =
		111
		112	The velocity macro content filter are xwiki components so to add one you just need to implements VelocityMacroFilter component interface and set the right component attributes. See [[xwiki:Documentation.DevGuide.WritingComponents]] for more details on XWiki components.