Skin Application

The Skin Application is provided by default starting with XWiki Enterprise 7.x 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".

AdministerWikiMenu.png

Next, click on the "Presentation" link from the vertical menu on the left,

PresentationLinkAdmin.png

then on the "Customize" button located above the "Skin" field

CustomizeDefaultSkin.png

which will launch the skin page in "Inline form" mode.

SkinPageInline.png

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

UploadLogo.png

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

LogoUpdated.png

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%;">
<h1>
#set ($title = "$!pdfdoc.display('title', 'rendered', '', $pdfobj)")
#if ($title == '')
  $escapetool.xml($!tdoc.plainTitle)
#else
  $escapetool.xml($title)
#end
</h1>
</div>

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.

PDFCoverTemplate.png

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.

PDFExportResult.png

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.

OverrideDefaultStylesheet.png

Override the Stylesheets

Back in the "Presentation" section of the wiki administration page, you might have noticed 2 properties:

  • Stylesheet represents the default or preferred stylesheet of the skin and it is set to "style.css".
  • Stylesheets may contain multiple mutually exclusive alternate stylesheets.

To create an alternate stylesheet, just copy your CSS code into a file named for instance "mynewstylesheet.css", then enter this string into the "Stylesheet" field.

Stylesheets.png

To override the default stylesheet, 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.

StyleProperty.png

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))
#end
## 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\{[^\}]*\}', ''))
#end
## Display the CSS
$!css

For more details about skin customization, refer to the "Create and Override a Skin" page linked under "Related Pages". Note that starting with version 7.2 it is possible to create skins in nested spaces.
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".

      

Search this space