Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.InplaceEditing]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.InplaceEditing]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:SyntaxHighlighting.EnableSyntaxHighlighting]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:CKEditor.EditMenuEntry]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:Licenses.Code.AvailableTemplateProvidersFilter]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.Ratings.RatingsUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.Ratings.RatingsUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

Velocity API

Last modified by Admin on 2022/08/17 08:15
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:Licenses.Code.MissingLicensesUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:Licenses.Code.MissingLicensesUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
cogAPIs to evaluate content with Velocity
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

XWiki 3.0M3+

Installable with the Extension Manager

  Download v14.6SourcesIssues

Table of contents

Description

You can also check the XWiki Platform Developer's Guide for information about Velocity scripting in the XWiki Platform

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 Velocity Module Javadoc

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 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:

See more available variables at XWiki Scripting Reference Documentation

Velocity Macros

See available Velocity macros.

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.:

$obj.someMethod('VALUE')
// will forward to
obj.someMethod(SomeEnum.VALUE)
// 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 the Properties Module which means you can create and register custom converters for data types specific to your application domain.

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

Velocity Directives

Since 6.3M1 XWiki provides a Velocity Directive to catch Exceptions from Velocity.

For example:

#try()
   ... velocity code here...
#end
...
 #if ("$!exception" != '')
   #displayException('some summary to display', $exception)
 #else
    ...
 #end
...

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:

{{velocity}}
#try("myexception")
$services.query.xwql("zzzzz").execute()
#end

#if ($myexception != '')
  ... do something...
#end
{{/velocity}}

Prerequisites & Installation Instructions

We recommend using the Extension Manager to 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 and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.commons:xwiki-commons-velocity 14.6):

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.Like.LikeUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:XWiki.PageTagsUIX]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
    

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected