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:

• Velocity Macro (installed by default in XWiki Enterprise)
• Groovy Macro (installed by default in XWiki Enterprise)
• Python Macro (installed by default in XWiki Enterprise)
• Ruby Macro (not installed by default in XWiki Enterprise)
• PHP Macro (not installed by default in XWiki Enterprise)

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 Extensions wiki area to see how others have figured out how to achieve a variety of results.

Bindings

These objects are available to you in scripting languages.

• The current Document: doc
• The Context of the request: xcontext
• The Request object: request
• The Response object: response
• The XWiki object: xwiki
• The XWiki utils: util

XWiki Component Access

You can also gain direct access to XWiki components using the following code snippet (also see: Accessing components from Groovy):

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 requires Programming Rights to be able to save the page containing the script (Programming Rights are not required for viewing a page containing a script requiring Programming Rights, rights are only needed at save time). Using the core should be avoided if at all possible.

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

• The underlying XWikiContext behind the Context object: xc
• The underlying XWiki object which backs the xwiki object: wiki
• The underlying XWikiDocument behind the current Document: xdoc

You will find that many of the methods in wiki and xdoc require an instance of the XWikiContext, this is the underlying xcontext xc not the Api context xcontext.

Again, these methods are only for the rare cases when functionality is not provided by the public Api. We put a lot of effort into preserving the behavior of the public Api and much less into preserving the behavior of core methods so you may find that core methods are deprecated, removed, or their behavior is changed in subsequent versions.

Querying XWiki's Model

From your script you can query the full XWiki's Model. Check the Query Guide for more information.

Velocity Specific Information

Velocity is the only scripting language which can be used without Programming Access Rights. This means you can save velocity scripts using a user with less permission and an exploit of your script is less of a security breach. 

You can gain access to the XWiki core from Velocity but this will require Programming Rights. Strictly speaking, protected APIs are only available when the page that contains them was last saved by someone who had Programming Rights (see above).

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.

For more details on using Velocity check the Velocity Module Documentation which also contains the full list of Velocity Tools that you can use in your scripts.

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

Other Velocity Variables

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

To remove them all you can set:

Information about the current user

The following variables (set in the xwikivars.vm template) are shortcuts for checking various information for the current user:

• $isGuest: checks if the current user is XWiki.XWikiGuest
• $isSuperAdmin: checks if the current user is the special user superadmin

• $hasComment: checks comment rights on the current document
• $hasEdit: checks edit rights on the current document
• $hasWatch: checks if the user is authenticated and the watch service is available

• $hasAdmin: checks admin rights on the current document
• $hasSpaceAdmin: checks admin rights on the XWikiPreferences document of the current space
• $hasGlobalAdmin: checks admin rights on XWiki.XWikiPreferences

• $hasCreateSpace: checks edit rights on that page that does not exist, in a space that doesn't exist
• $hasCreatePage: checks edit rights on that page that does not exist, in the current space

• $hasProgramming: checks if the current user has programming rights

• $isAdvancedUser: advanced users: superadmin, users with the usertype property set to "Advanced", guest users with admin rights

Example:

Information about the current wiki

The following variables (set in the xwikivars.vm template) are shortcuts for checking various information about the current wiki:

• $isReadOnly
• $isInServletMode
• $isInPortletMode

Groovy Specific Information

• See Groovy snippets in the Extensions wiki (click on the "Groovy" tag in the Tag Cloud)
• Groovy web site

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.

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.

Python Specific Information

You can run Python code in XWiki just like Velocity or Groovy.

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 Groovy Macro (using {{groovy}} and {{/groovy}})
• Velocity is parsed in a page no matter what (there is no need to invoke the Velocity Macro 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.