Skip to Content

Scripting

Version 15.1 by Raluca Stavro on 2009/10/26
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.Scripting.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

XWiki's Velocity API

The concept of the 'context' is central to Velocity. The context is a 'carrier' of data between the Java layer of the XWiki engine and the template or page layer. The programmers of the XWiki core have gathered objects of various types and placed them in the Velocity context. These objects, and their methods and properties, are accessible via template elements called references and effectively form an API for XWiki.

The API is documented in Javadoc format and can be accessed here: XWiki API Javadoc. If you are not familiar with Java or object oriented programming, you will probably be confused by the API documentation. It is not within the scope of our documentation to teach you all the details about Velocity, Java, or object oriented programming. You can find all of that information already online. You should then refer to the Velocity User Guide as an ongoing reference. Finally, you can explore the page code found throughout the Code Zone area to see how others have figured out how to achieve a variety of results.

You can access in your velocity script to:

  • The current document: $doc
  • The Context of the request: $context
  • the request object: $request
  • the response object: $response
  • the XWiki Object: $xwiki

In addition the following Velocity tools are also available in the Velocity context:

Information

If you wish to add new Velocity tools you'll need to edit your xwiki.properties file and follow the instructions in there.

You can also use HQL to query the XWiki database from your velocity scripts.

To include Velocity scripts in other Velocity scripts, see How to include a velocity page into another page.

Other Velocity Variables

Information

These variables can be used but are subject to change in the future.

Controlling whether to display Comments/History/Attachment/Information sections or not

It's possible to control whether to display these sections by setting some velocity variable to "no":

#set ($showcomments = "no")
#set ($showattachments = "no")
#set ($showhistory = "no")
#set ($showinformation = "no")

To remove them all you can set:

#set($docextras = [])

XWiki's Groovy API

Currently Groovy is only allowed for admins of a wiki (or users having the 'programming' right).

Groovy Example

The following example demonstrates how to use a groovy script directly inside your page. This example performs a reverse DNS lookup from the velocity variable $address and store the result into the variable $hostname.

#set ($address = "172.20.12.61")

IP Address: $address

<%

import java.net.InetAddress;

vcontext = context.get("vcontext");
hostname = vcontext.get("address");

InetAddress addr = InetAddress.getByName(hostname);
hostname = addr.getHostName().toLowerCase();

%>

Hostname: $hostname

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected