org.xwiki.commons:xwiki-commons-velocityXWiki Commons - Velocityjar00.0XWiki Commons - Velocity{{info}}
You can also check the [[XWiki Platform Developer's Guide>>xwiki:Documentation.DevGuide.Scripting||anchor="HVelocitySpecificInformation"]] for information about Velocity scripting in the XWiki Platform
{{/info}}
This module offers APIs to evaluate content with Velocity.
The following concepts are exposed:
* ##VelocityManager##: This is the main entry point for anyone who need to manipulate Velocity scripts
* ##VelocityTemplate##: {{version since="15.8"}}This is a helper to manipulate/cache/reuse a "compiled" version of a Velocity script{{/version}}
* ##VelocityEngine##: This is the object on which you call ##evaluate()##. In XWiki Standard, each skin has an associated ##ScriptEngine##. This allows each Skin to provide its own set of global Velocity macros.
* ##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. {{version since="15.9"}}Deprecated, used only ##VelocityManager##.{{/version}}
* ##VelocityContextInitializer##: A role to implement when you need to inject Velocity specific binding in the ##VelocityContext##. In most cases, it's recommended to implement ##org.xwiki.script.ScriptContextInitializer## so that the binding you inject is exposed to all scripting languages and not just Velocity.
= Velocity Tools =
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). 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:
* {{scm project="xwiki-commons" path="xwiki-commons-core/xwiki-commons-legacy/xwiki-commons-legacy-velocity/src/main/java/org/xwiki/velocity/tools/CollectionsTool.java"}}Collections Tool{{/scm}}: **##$collectionstool##** (since 4.0M1 and {{warning}}deprecated since 12.1RC1. Use ##$collectiontool## instead.{{/warning}})
* [[Comparison Date Tool>>https://github.com/xwiki/xwiki-commons/blob/master/xwiki-commons-core/xwiki-commons-velocity/src/main/java/org/xwiki/velocity/tools/ComparisonDateTool.java]] (extends the standard Velocity [[Comparison Date Tool>>http://velocity.apache.org/tools/3.0/apidocs/org/apache/velocity/tools/generic/ComparisonDateTool.html]], which in turn extends the [[Date Tool>>http://velocity.apache.org/tools/3.0/apidocs/org/apache/velocity/tools/generic/DateTool.html]]): **##$datetool##**
* [[Escape Tool>>https://github.com/xwiki/xwiki-commons/blob/master/xwiki-commons-core/xwiki-commons-velocity/src/main/java/org/xwiki/velocity/tools/EscapeTool.java]] (extends the standard Velocity [[escape tool>>http://velocity.apache.org/tools/3.0/apidocs/org/apache/velocity/tools/generic/EscapeTool.html]]): **##$escapetool##** (since 2.7RC1)
* [[JSON Tool>>https://github.com/xwiki/xwiki-commons/blob/master/xwiki-commons-core/xwiki-commons-velocity/src/main/java/org/xwiki/velocity/tools/JSONTool.java]]: **##$jsontool##** (since 4.0M2)
* [[Math Tool>>http://velocity.apache.org/tools/3.0/apidocs/org/apache/velocity/tools/generic/MathTool.html]]: **##$mathtool##**
* [[Number Tool>>http://velocity.apache.org/tools/3.0/apidocs/org/apache/velocity/tools/generic/NumberTool.html]]: **##$numbertool##**
* [[Regex Tool>>https://github.com/xwiki/xwiki-commons/blob/master/xwiki-commons-core/xwiki-commons-velocity/src/main/java/org/xwiki/velocity/tools/RegexTool.java]]: **##$regextool##** (since 2.0RC2)
* [[Sort Tool>>http://velocity.apache.org/tools/3.0/apidocs/org/apache/velocity/tools/generic/SortTool.html]]: **##$sorttool##** ({{warning}}deprecated since 12.0. Use ##$collectiontool## instead.{{/warning}})
* [[String Tool>>http://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/StringUtils.html]]: **##$stringtool##** (since 3.4M1). Also provides the {{scm project="xwiki-commons" path="xwiki-commons-core/xwiki-commons-text/src/main/java/org/xwiki/text/StringUtils.java"}}following APIs{{/scm}} (since 6.3M1). {{version since="15.7RC1"}}And it provides {{scm project="xwiki-commons" path="xwiki-commons-core/xwiki-commons-velocity/src/main/java/org/xwiki/velocity/tools/StringTool.java"}}the following APIs too.{{/scm}}{{/version}}
* {{scm project="xwiki-commons" path="xwiki-commons-core/xwiki-commons-velocity/src/main/java/org/xwiki/velocity/tools/URLTool.java"}}URL Tool{{/scm}}: **##$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)
* [[Exception Tool>>http://commons.apache.org/proper/commons-lang/javadocs/api-3.1/org/apache/commons/lang3/exception/ExceptionUtils.html]]: **##$exceptiontool##** provides useful helpers to manipulate exceptions (get root cause, transform into a String, etc) (since 6.3M1)
* {{scm project="xwiki-commons" path="xwiki-commons-core/xwiki-commons-velocity/src/main/java/org/xwiki/velocity/tools/nio/NIOTool.java"}}NIO Tool{{/scm}}: **##$niotool##** allows to use some non-dangerous NIO2 API from Velocity (since 7.4M2). Useful along with the [[VFS API>>Extension.VFS API]].
* [[Log Tool>>http://velocity.apache.org/tools/3.0/apidocs/org/apache/velocity/tools/generic/LogTool.html]]: **##$logtool##** allows logging from Velocity scripts (since 12.0)
* [[Object Tool>>http://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html]]: **##$objecttool##** offer object-related convenience APIs (such as checking for null and more) (since 12.1). Also provides the {{scm project="xwiki-commons" path="xwiki-commons-core/xwiki-commons-velocity/src/main/java/org/xwiki/velocity/tools/ObjectTool.java"}}following APIs{{/scm}}.
* {{scm project="xwiki-commons" path="xwiki-commons-core/xwiki-commons-velocity/src/main/java/org/xwiki/velocity/tools/CollectionTool.java"}}Collection Tool{{/scm}} (extends [[Velocity's CollectionTool>>https://velocity.apache.org/tools/3.0/apidocs/org/apache/velocity/tools/generic/CollectionTool.html]]): **##$collectiontool##** (since 12.1)
See more available variables at [[XWiki Scripting Reference Documentation>>xwiki:ScriptingDocumentation.WebHome]]
= Velocity Macros =
See [[available Velocity macros>>extensions:Extension.Web Resources for XWiki.WebHome]].
= Velocity Uberspectors =
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.:
{{code}}
$obj.someMethod('VALUE')
// will forward to
obj.someMethod(SomeEnum.VALUE)
// if obj has a method with signature someMethod(SomeEnum) and not someMethod(String)
{{/code}}
But this is not limited to enums. The conversion is done using the [[Properties Module]] which means you can create and register custom converters for data types specific to your application domain.
{{version since="13.7"}}
The strategies to select the right method when none exactly matches the passed parameters has been greatly improved:
* in case of different method name case, give priority to same case
* calculate a weight based on the compatibility between passed parameters and each method parameters:
** exact same type worth 10 per argument
** compatible type (the passed argument can be cast to the method argument type) worth 1 per argument
*** this includes unboxing (for example ##Boolean## to ##boolean##)
** two numbers of different types (which is a very common use case) worth 0.5
* as last resort compare the ##toString()## of each method to make sure the list is always stable across environments to reduce the "it worked on my machine" effect
{{/version}}
= Velocity Directives =
{{info}}Since 6.3M1{{/info}} XWiki provides a Velocity Directive to catch Exceptions from Velocity.
For example:
{{code language="velocity"}}
#try()
... velocity code here...
#end
...
#if ("$!exception" != '')
#displayException('some summary to display', $exception)
#else
...
#end
...
{{/code}}
{{version since='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:
{{code language="velocity"}}
{{velocity}}
#try("myexception")
$services.query.xwql("zzzzz").execute()
#end
#if ("$!myexception" != '')
... do something...
#end
{{/velocity}}
{{/code}}
{{/version}}GNU Lesser General Public License 2.1http://extensions.xwiki.org/xwiki/bin/view/Extension/Velocity%20ModuleXWiki Development Teamhttps://xwiki.org/xwiki/bin/view/XWiki/XWikiTeamgitgit://github.com/xwiki/xwiki-commons.git/xwiki-commons-pom/xwiki-commons-core/xwiki-commons-velocitygitgit@github.com:xwiki/xwiki-commons.git/xwiki-commons-pom/xwiki-commons-core/xwiki-commons-velocityhttps://github.com/xwiki/xwiki-commons/tree/master/xwiki-commons-pom/xwiki-commons-core/xwiki-commons-velocity/jirahttps://jira.xwiki.org/browse/XCOMMONSfalsemaven.groupidorg.xwiki.commonsmaven.artifactidxwiki-commons-velocitymaven.Modelorg.xwiki.commons:xwiki-commons-velocity:jar:18.6.0xwiki.extension.recommendedVersions.commonsorg.xwiki.commons:.*/[18.6.0]xwiki.extension.recommendedVersions${xwiki.extension.recommendedVersion.commons}4.2-milestone-3maven-xwikihttps://nexus.xwiki.org/nexus/content/groups/publicmaven