Version 21.2 by Vincent Massol on 2010/02/15
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.

The [toc] macro is a standalone macro and it cannot be used inline. Click on this message for details.

Scripting allows you to create basic to complex web applications at the XWiki page (or view) layer without the need for compiling code or deploying software components. In other words, you can use scripting syntax in addition to wiki and HTML syntax as the contents of an XWiki page.

XWiki integrates jsr-223 scripting. You can script using several available languages by using one of the following macros:

XWiki Scripting API


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 Java, or object oriented programming. You can find all of that information already online. You can also explore the page code found throughout the Code Zone area to see how others have figured out how to achieve a variety of results.


These objects are available to you in scripting languages.

XWiki Component Access

You can also gain direct access to XWiki components using the following code snippet:
Also see: Accessing components from Groovy
Note: This snippet is written in Groovy and will have to be converted to your scripting language.
def greeter = com.xpn.xwiki.web.Utils.getComponent(org.xwiki.component.HelloWorld.class);
println greeter.sayHello();

XWiki Core Access

Sometimes the XWiki Api doesn't provide the methods which you need for your application. you can gain raw access the core of XWiki but it presents an increased security risk and as such should be avoided if at all possible.
def xc = xcontext.getContext();
def wiki = xc.getWiki();
def xdoc = doc.getDocument();

After using this snippet, you will have 3 new objects:

You will find that many of the methods in wiki and xdoc require an instance of the XWikiContext, this is xc not xcontext.
Again, these methods are only for the rare cases when functionality is not provided by the public Api and using this trick will increase the damage in the event that your script contains a security flaw which is exploited so it should be avoided when possible.

Velocity Specific Information

Velocity is the only scripting language which can be used without Administration or Programming Access Rights. This means you can save velocity scripts using a username with less permission and an exploit of your script is less of a security breach. Also if you are administrating a virtual wiki and you don't have programming rights, you can still do scripting in Velocity.
You can gain access to the XWiki core from Velocity but this will require programming rights.

In Velocity you can't import classes and as such you cannot gain direct access to XWiki components as shown above. This leaves you with the provided bindings (NOTE: In Velocity, these bindings all start with $ as with all other Velocity variables)

For more information about programming in the Velocity language, you can refer to the Velocity User Guide.

The following Velocity tools are also available in addition to the bindings.

If you wish to add new Velocity tools you'll need to edit your 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

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

Controlling Which Sections to Display

You can control whether to display Comments/History/Attachment/Information sections or not 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 = [])

Groovy Specific Information

Currently all non Velocity scripting languages are only allowed for administrators of a wiki (or users having the 'programming' right).

Groovy Example

The following example demonstrates how to use a groovy script to interact with velocity code in your page. This example performs a DNS lookup from the velocity variable $hostname and stores the result in the variable $address.

Using XWiki Syntax 2.0:
Objects can be passed back and forth between scripting languages by storing them in commonly available objects. One such commonly available object which only lasts the length of the request is the context object, known as xcontext.
#set($hostname = "")
Host Name: $hostname
$xcontext.put("hostname", $hostname)
host = xcontext.get("hostname");
InetAddress addr = InetAddress.getByName(host);
String address = addr.getHostAddress();
xcontext.put("address", address);
IP Address: $xcontext.get("address")

Using XWiki Syntax 1.0:
Because Groovy and Velocity code are parsed together, variables defined in Groovy can be used directly in velocity without storing in and retrieving from the context.
#set ($hostname = "")
Host Name: $hostname
vcontext = context.get("vcontext");
host = vcontext.get("hostname");
InetAddress addr = InetAddress.getByName(host);
String address = addr.getHostAddress();
IP Address: $address

Python Specific Information

In Python, you have all of the powers available in Groovy but the default bindings are not available due to a bug in Jython There is a workaround snippet which manually loads the context, document, wiki object, request and response available here.

Example Snippet:
import com.xpn.xwiki.web.Utils as Utils
import org.xwiki.context.Execution as Execution
import com.xpn.xwiki.api.Context as Context
import com.xpn.xwiki.api.Document as Document
xcontext = Context(Utils.getComponent(Execution).getContext().getProperty("xwikicontext"))
doc = Document(xcontext.getDoc(), xcontext.getContext())
print "The full name of this document is " + doc.getFullName()

Scripting In XWiki Syntax 1.0

XWiki Syntax 1.0 is rendered by an old rendering engine which still supported but for which no further development is planned (it will eventually be removed). Syntax 1.0 has some idiosyncrasies which were solved by syntax 2.0.

  • The only scripting languages available to you are Velocity and Groovy.
  • In Groovy, the context is known as: context not xcontext
  • The beginning and end of Groovy scripts are denoted by <% and %> rather than through the GroovyMacro (using {{groovy}} and {{/groovy}})
  • Velocity is parsed in a page no matter what (there is no need to invoke the VelocityMacro using {{velocity}} and {{/velocity}})

The last part is important because it means you need to be careful of using $ and # in your document. This is still true inside of <% and %> so you have to be careful writing Groovy.

Get Connected