Skin Application

The Skin Application is bundled with XWiki Standard and for the moment it only allows to edit an existing skin. In future versions, the application will have features for creating and managing multiple skins.

Edit the Skin Page

As detailed in the "Flamingo Skin" documentation page, the default XWiki skin is Flamingo. To edit it, click the DrawerMenuIcon.png button which opens the drawer menu, then on "Administer Wiki".


Next, click on "Look & Feel" -> "Themes" in the accordion menu on the left,


then on the "Customize" button in the "Skin" section


and finally on "Edit this skin", which will launch the default skin page in "Inline form" mode.


As shown in the "Base skin" input, the base skin is "flamingo" which is stored in the folder "/webapps/xwiki/skins/flamingo". In order to add a new logo, click on "Choose an attachment", select an image from your computer, then click on "Upload and Select".


You will then see the new logo in "Inline form" mode.


Note that by default, the displayed logo is the one defined in the color theme page used by the wiki. When the logo is not defined in the color theme, XWiki will display the one attached to the skin file. The reason for this is to allow you to have a different logo for each color theme. For more information, please refer to the Flamingo Color Theme Application documentation. 

The "Output Syntax" field has 2 options:

  • HTML 5 - recommended for new skins
  • XHTML 1.0 - added in order to keep backward compatibility with old skins like "colibri" and it is used by XWiki to know which renderer to use along with the skin. The renderer is important to generate valid HTML code.

Override Skin Resources

Skin resources are Velocity, JavaScript, CSS and LESS files located in the "/webapps/xwiki/templates/" folder or in the current skin folder "/webapps/xwiki/skins/flamingo/". The main CSS file is "style.css", whereas the main LESS file is "less/style.less.vm".

In case you need to replace a JavaScript resource, an image or even fonts, the best way is to attach it to the skin page, then to refer it using a Skin extension. More details are available in the "Skins extensions" tutorial linked under "Related Pages".

To customize for instance the "pdfcover.vm" template, enter the string pdfcover.vm in the input field under "Overridden templates", then click on "Add". You will then notice 2 new fields:

  • Path - representing the template name; this one is automatically filled and it should not be modified
  • Content - this is where you add the template Velocity code

What you will have to do first is to paste the default code into the "Content" field which is:

<div style="text-align: center; width: 100%;">
#set ($title = "$!pdfdoc.display('title', 'rendered', '', $pdfobj)")
#if ($title == '')

To display for instance the company logo on the PDF cover page, add the line <img src="$xwiki.getSkinFile("Telegram_logo_scaled.png")"/> right before the default code.


Don't forget to hit "Save & View" in order to submit your changes. If you then export a wiki page as PDF, the cover page should look like in the screen-shot below.


For the moment the UI doesn't support overriding the default "style.css" file using the aforementioned method. As a workaround, you can click on "Deprecated properties" and enter the custom CSS in the "Style" field or follow the instructions from the next section.


Override the Stylesheets

The default or preferred stylesheet of the skin is named "style.css". To override it, you have two possibilities: the easiest one is to add your rules to the "/webapps/xwiki/skins/flamingo/style.css" file, then attach it to the skin page. However, this method is not recommended because it will be quite hard to keep track of the subsequent changes history and make comparisons . 

This is why you should edit the skin page in "Objects" mode and locate the "Style" property in the "XWiki.XWikiSkins" object which by default is empty.


Before adding your own CSS rules that will override the default implementation, you first need to load the main CSS file of the current flamingo skin by pasting the below lines.

## Get the compiled LESS code
#set($css = $services.lesscss.compileSkinFile('style.less.vm'))
## Remove the useless part
#set($index = $css.indexOf('.not-sent-to-the-browser-from-this-point'))
#if($index >= 0)
  #set($css = $css.substring(0, $index))
## Remove from the CSS some rules that make IE9 crash using the WYSIWYG (XWIKI-10661)
## Only if the user agent contains the IE9 signature
## @TODO: Remove this when IE9 will no longer be supported.
#if($request.getHeader('User-Agent').contains('MSIE 9.0'))
  ## We removes css rules like ".className:empty{...}"
  ## "(?s)" means that the expression "." matches any character, including a line terminator
  #set($css = $css.replaceAll('(?s)\.[^\{]*:empty\{[^\}]*\}', ''))
## Display the CSS

For more details about skin customization, refer to the "Create and Override a Skin" page linked under "Related Pages". Also, if you are familiar with LESS, feel free to extend the .less files of the skin, according to the principles presented in the "LESS Module" documentation, linked in the "Related Pages".


Related Pages

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

Search this space