Create, edit and manage Skins

Description

Offers the ability to edit an existing skin.

How to use it

1. Go to the Administration, in the "Presentation" section:

     

2. Enter the name of the skin to edit (by default: XWiki.DefaultSkin).
3. Click on "Customize".
4. You will get the skin edition page:

     

5. Here you can set the name of the skin, the parent of the skin (base skin) and you can change the logo. (The logo could be overrided by the Flamingo Theme Application).
6. Since 7.1M1. You can also select the output syntax your skin is using: HTML 5 for recent skins, and XHTML 1.0 for old ones. This setting is used by XWiki to know which renderer to use along with the skin, which is important to generate valid HTML code.

Templates customization

Principle

A skin is made of templates written in Velocity (*.vm files), JavaScript (*.js files), CSS and LESS. Each XWiki action is bound to a template, organized like this:

Inside a template, you can include an other template, so that you can split your skin in different files. The syntax is:

In XWiki, there is two types of skins:

• the file system skins, which are made of template files directly stored in the webapp folder
• the wiki skins, which are made of templates stored in the wiki.

The main skins (Flamingo, Colibri) are stored in the file system, so they can be used even when the database is empty. It is a logical choice for default skins.

The user skins are usually stored in the wiki (so in the database). They are based on existing skins but they just override some templates. They are also easier to install, since you just need to import a XAR or to install the skin with the Extension Manager.

How to override a template

There is 2 ways to override a template (+ a deprecated one):

1. By adding an overridden template object
2. By adding an attachment to the skin

Adding an overridden template object

1. Go to the "Overridden templates" section:
2. Enter the name of the template that you want to override (eg: view.vm, footer.vm, style.css, etc...). If the template is stored inside a directory, you can use the "/" character as separator (eg: less/style.less.vm, less/headers.less).
3. Click to the "add" button:

     

4. Here you can write the content of the template. We usually take the content of the existing template from the parent skin (by browsing the http://localhost:8080/xwiki/skins/flamingo/footer.vm URL) and we add some customization in it:

     

5. Save the skin

It's done, you have introduced an overridden template.

Note: for resources for which the URL needs to be fetched and used (using $xwiki.getSkinFile(), this mechanism of overwrite won't work, as the .getSkinFile() won't return properly an URL to the resource. This may apply to some css resources, for example print.css . In order to have an overwrite for these files, you need to overwrite by using an attachment, as described below. There is an open ticket about this, XWIKI-18297.

Adding an attachment

For resources files (images, fonts, etc) or for big templates, you can add the template as an attachment of the skin.

More informations about this.

The deprecated way

For retro-compatibility reason, we have introduced a "deprecated properties" section. In there, you can override some templates. See the documentation of this mechanism.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

1. Log in the wiki with a user having Administration rights
2. Go to the Administration page and select the Import category
3. Follow the on-screen instructions to upload the downloaded XAR
4. Click on the uploaded XAR and follow the instructions
5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-skin-ui 16.9.0):

• org.xwiki.platform:xwiki-platform-localization-script 16.9.0
• org.xwiki.platform:xwiki-platform-localization-macro 16.9.0
• org.xwiki.rendering:xwiki-rendering-macro-message 16.9.0
• org.xwiki.platform:xwiki-platform-rendering-macro-velocity 16.9.0
• org.xwiki.platform:xwiki-platform-csrf 16.9.0
• org.xwiki.rendering:xwiki-rendering-macro-html 16.9.0
• org.xwiki.platform:xwiki-platform-rendering-xwiki 16.9.0
• org.xwiki.platform:xwiki-platform-icon-script 16.9.0