XWiki Scripting

Scrips allow you to create basic to complex web applications at the XWiki page layer without needing to compile code or deploy software components. In other words, the scripting syntax can be used in addition to wiki and HTML syntax as content of an XWiki page.

XWiki integrates jsr-223 scripting. There are several available languages by using one of the following macros:

  • Velocity Macro - installed by default in XWiki
  • Groovy Macro - installed by default in XWiki
  • Python Macro - installed by default in XWiki
  • Ruby Macro - not installed by default in XWiki
  • PHP Macro - not installed by default in XWiki

XWiki Scripting API


Some bindings are automatically provided: 

xwikicom.xpn.xwiki.api.XWikiRepresents the XWiki object.
xcontextcom.xpn.xwiki.api.ContextRepresents the Context of the request.
requestcom.xpn.xwiki.web.XWikiRequestThe servlet request. Generally used to get URL parameters.
responsecom.xpn.xwiki.web.XWikiResponseThe servlet response.
doccom.xpn.xwiki.api.DocumentThe current document.
cdoccom.xpn.xwiki.api.DocumentThis variable represent the current default document (not the translated) from which to access the Comments, Objects and Attachments.
tdoccom.xpn.xwiki.api.DocumentIt represents the translated document matching the requested language
utilcom.xpn.xwiki.api.UtilUtility APIs available to scripting environments under the util variable.
msgcom.xpn.xwiki.web.XWikiMessageToolProvides a internationalization service based on key/property values.
syntaxFactoryorg.xwiki.rendering.syntax.SyntaxFactoryAllows the creation of a wiki syntax that the user can use to enter wiki content.
officeimporterPuts a reference to Office Importer in newly created velocity contexts.

XWiki Component Access

You may directly access the XWiki components by using the following Groovy snippet:

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 needed methods for your application. You may access the XWiki core, but this presents an increased security risk and requires programming rights to run. Using the core should be avoided if possible.

def xc = xcontext.getContext();
def wiki = xc.getWiki();
def xdoc = doc.getDocument();

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.

Query the XWiki Model

You can query the full XWiki Model using a script. Check the Query Module for more information.

Velocity Specific Information

Velocity is the only scripting language which can be used without Admin or Programming Rights. This means Velocity scripts can be saved using a username with less permission so that an exploit of the script is less of a security breach.
You may access the XWiki core from Velocity but this will require programming rights. Strictly speaking, protected APIs are only available when the page containing them was last saved by someone with programming rights.

In Velocity, classes cannot be imported and direct access to XWiki components cannot be gained, as shown here. 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 Velocity, refer to the Velocity User Guide.

The following tools are also available in addition to the bindings:

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

To include Velocity scripts in other Velocity scripts, see the dedicated page.

Controlling Which Sections to Display

You can control whether to display or not the "Comments", "History", "Attachment" and "Information" sections by setting some Velocity variables to "no":

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

To remove them all you can set:

#set($docextras = [])

Information About the Current User

The following variables 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 whether the user is authenticated and the watch service is available
  • $hasAdmin: checks admin rights on the current document
  • $hasSpaceAdmin: checks the 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


#if ($hasAdmin)
  ## This link will only be visible to users that have admin rights on this document
  [[Do some admin action>>Some.Document]]

Information About the Current Wiki

The following variables are shortcuts for checking various information about the current wiki:

  • $isReadOnly
  • $isInServletMode
  • $isInPortletMode


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space