|APIs to evaluate content with Velocity|
|License||GNU Lesser General Public License 2.1|
Table of contents
This module offers APIs to evaluate content with Velocity.
The following concepts are exposed:
- VelocityEngine: This is the object on which you call evaluate()
- VelocityConfiguration: Default Velocity configuration. Sets default configuration parameters and default tools (see below)
- VelocityContextFactory: Allows to create Velocity Context. Context are used when evaluating in order to expose some variable to the script content
- VelocityFactory: Allows to create several VelocityEngine based on a key you defined. For example XWiki Platform uses this to have one VelocityEngine per Skin. This allows each Skin to provide its own set of Velocimacros.
- VelocityContextInitializer: Allows to callback components that implements this Role when VelocityFactory is called to create a new Velocity Context. This allows your code to automatically bind new variables in the Velocity Context.
To see more of the API read the
For security reasons we're not exposing some APIs to Velocity scripting (such as Reflection or Threading APIs). In addition Velocity is a template language and doesn't have the full support a complete development language has (for example you cannot instantiate new classes or you cannot handle exceptions just to name 2). Thus we need to offer some Tools (i.e. API) that are meant to be used from Velocity to make it easy to create powerful scripts in Velocity code.
The following Velocity tools are made available:
- $collectionstool (since 4.0M1) :
- $datetool (extends the standard Velocity , which in turn extends the ):
- $escapetool (since 2.7RC1) (extends the standard Velocity ):
- $jsontool (since 4.0M2) :
- $listtool (deprecated; any methods provided by this tool can be used directly on arrays and lists now) :
- $mathtool :
- Message Tool: $msg This tool is used to provide internationalized messages based on keys. For more details see the .
- $numbertool :
- $regextool (since 2.0RC2) :
- $sorttool :
- String Tool
- $stringtool (since 6.3M1) :
- $stringtool (since 3.4M1) :
- $urltool allows to parse URL's; currently only a parseQuery method is supported to parse the query string of a given URL (since 6.3M1) :
- $exceptiontool provides useful helpers to manipulate exceptions (get root cause, transform into a String, etc) (since 6.3M1) :
- $niotool allows to use some non-dangerous NIO2 API from Velocity (since 7.4M2). Useful along with the . :
See more available variables at
The introspection behaviour in Velocity can be customized by implementing an uberspector. Velocity supports by default only one uberspector. To overcome this limitation we have implemented an uberspector that forwards all calls to a chain of uberspectors.
Method Arguments Uberspector
A chainable uberspector that tries to convert method arguments to formal parameter types when the passed arguments don't match the method signature. In other words, it looks for a method matching the passed arguments and if none is found then it tries the convert the arguments to match the available method signatures (the available methods with the same name and the same number of parameters but with different parameter types). E.g.:
// will forward to
// if obj has a method with signature someMethod(SomeEnum) and not someMethod(String)
But this is not limited to enums. The conversion is done using thewhich means you can create and register custom converters for data types specific to your application domain.
public boolean isRegularFile(Path path, LinkOption... options) that is bound through $niotool, then you can call it with $niotool.isRegularFile("path/to/a/file").This uberspector supports calling varargs methods. For example, if you have the following Java method
XWiki provides a Velocity Directive to catch Exceptions from Velocity.
#set($outputSyntax = $xwiki.getAvailableRendererSyntax($request.outputSyntax, $request.outputSyntaxVersion))
## If the passed syntax is not an HTML-compatible syntax we need to HTML-escape it so that it can be
## displayed fine in HTML (since at the point this vm file is called we're already inside an HTML page with
## panels on the side, header, etc).
#set($syntaxType = $outputSyntax.type.toIdString())
#if (($syntaxType == "xhtml") || ($syntaxType == "html"))
#set ($renderedContent = $tdoc.getRenderedContent($outputSyntax))
## Make sure to print correctly the result when it's not HTML
#set ($renderedContent = "<pre>$escapetool.html($tdoc.getRenderedContent($outputSyntax))</pre>")
#set ($renderedContent = $tdoc.getRenderedContent())
#if ("$!exception" != '')
Starting with XWiki 8.3M2/7.4.5/8.1.2, it's possible to name the Velocity variable in which the exception will be saved. For example:
#if ($myexception != '')
... do something...
Prerequisites & Installation Instructions
We recommend using theto 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).
You can also use the manual method which involves dropping the JAR file into the WEB-INF/lib folder and restarting XWiki.
- org.xwiki.commons:xwiki-commons-configuration-api 8.3
- org.xwiki.commons:xwiki-commons-script 8.3
- org.xwiki.commons:xwiki-commons-xml 8.3
- org.xwiki.commons:xwiki-commons-management 8.3
- org.apache.velocity:velocity 1.7
- org.apache.velocity:velocity-tools 2.0
- org.apache.commons:commons-lang3 3.4
- org.apache.commons:commons-collections4 4.1
- commons-codec:commons-codec 1.10
- com.fasterxml.jackson.core:jackson-core 2.8.3
- com.fasterxml.jackson.core:jackson-databind 2.8.3
- net.sf.json-lib:json-lib:jdk15 2.4
- org.json:json 20160810
- org.apache.httpcomponents:httpclient 4.5.2