Skins Extensions

The XWiki skins extensions is a mechanism that allows you to customize the layout or just some pages of your wiki, without the need of changing the skin templates or the stylesheets. The "Skin Extension" plugin provides you with the ability to send to the browser extra JavaScript and CSS files that are not part of the actual skin of the wiki. The code for these extensions is defined in wiki objects.

The two supported extensions types are "JavaScript extensions" incarnated by "XWiki.JavaScriptExtension" objects and "StyleSheet extensions" incarnated by "XWiki.StyleSheetExtension" objects.

Create a JavaScript Extension

Go to the wiki page you want to create your extension in and edit it in "Objects". Choose the "XWiki.JavaScriptExtension" class from the drop-down list near "New object" and click on the "Add" button.


The "Use this extension" field has 3 options:

  • On this wiki which indicates that the code will apply on all the pages. In order to execute an extension with this option selected you need to have programming rights.
  • On this page or on demand
  • On demand only which will force you to call the extension explicitly to see it executed as shown below

The "Parse content" option set to "No" allows you to write Velocity code. Finally, you can specify a "Caching policy", to tune the HTTP headers that will be returned with the generated JavaScript file.


Given that we have chosen to execute this extension "On demand", we will have to make a call to the Skin Extension plugin by editing the page in wiki mode and adding the following lines:


You should then see an alert box:


Create a StyleSheet Extension

StyleSheet extensions modify the graphical appearance of the wiki pages and they work just like JavaScript extensions, except for the fact that the code is written in CSS.

Example for Versions Prior to 6.4

Create a new page named "XWiki.StyleSheetExtensionTest", add a "XWiki.StyleSheetExtension" object and enter "My First StyleSheet extension" in the "Name" input. Set the "Use this extension" option to "Always on this page", the "Parse content" option to "No" and select a default cache policy. Next, copy the following lines in the "Code" input:

#xwikicontent {
  background-color: lightBlue;

In case you need to use the same background color as the current color theme, you need to include the "colorThemeInit.vm" template. This will allow you to access the "ColorThemeClass" properties using the Velocity $theme variable:


.myCustomClass {
 background-color: $theme.menuBackgroundColor;
 color: $theme.pageContentBackgroundColor;


When including the "colorThemeInit.vm" template, make sure the "Parse content" option is set to "Yes". Otherwise, the Velocity code inside the template won't be interpreted.

If you want to use StyleSheet extension on demand, the principle is the same as for JavaScript, except that the name of the plugin is ssx, not jsx:



Example for Versions Starting with 6.4

Starting with version 6.4 XWiki has integrated the LESS Module, allowing to write LESS CSS inside a skin extension by setting the field "Content Type" to "LESS".


Since you cannot use LESS in a StyleSheet Extension with a skin that does not have a less directory (such as Colibri) a good practice is to have 2 SSX objects: a first one containing pure CSS and a second one containing LESS code that overwrites the CSS rules of the first object.

So, the equivalent of the previous example will be:


Note how this time you won't have to call the "colorThemeInit.vm" template anymore.

A document can have as many ssx or jsx object as it needs, but a skin extension is identified by the name of the document, so in the end an extension is a document. The content of a skin extension is the concatenation of the objects in that document, so it is not possible to write two different extensions in a single document, only different parts of the same extension.

Read about Skins eXtensions with addSizes.js.

Refer a File from a Skin Extension

In case you need to use some image for styling, the solution is to refer it from a Style Sheet extension. If the image is stored on the file system in the skin folder, you can obtain the path to the file using $xwiki.getSkinFile():

.myCustomClass {
  background-image: url($xwiki.getSkinFile("icons/silk/page_white_picture.gif");

The file will be looked on the disk in the following order:

  • the current skin folder
  • the base skin folder
  • the default skin folder
  • the "templates" folder

For images attached to wiki pages, there are 2 possibilities. If the image is attached to the page containing the "XWiki.StyleSheetExtension" object, you can use: background-image: url("page_white_picture.gif"));.

For an image attached to another wiki document use: background-image: url($xwiki.getDocument("Sandbox.LogoPage").getAttachmentURL("logo.png"));. Also, in order for the Velocity code to be interpreted and executed, the field "Parse Content" should be set to "Yes".

Debug LESS Code

To display the compilation errors for a Style Sheet extension containing LESS code, append the minify=false query string to the SSX URL. For instance, if the path to the SSX is xwiki/bin/ssx/Sandbox/WebHome, the URL will become xwiki/bin/ssx/Sandbox/WebHome?minify=false.


Related Pages

Search this space