Available Skins
Reference
This page lists the skins an XWiki instance can use, the three kinds of skin, and how a skin is named in the configuration. To choose which skin a wiki, a page or a user gets, see Skin Levels.
The skins shipped with XWiki
XWiki ships one skin, Flamingo, and one wiki skin page built on it, XWiki.DefaultSkin.
An out-of-the-box wiki does not use flamingo directly. Its Skin setting holds XWiki.DefaultSkin, a page shipped with the wiki whose Base Skin is flamingo. That is what the Customize button in the administration opens, and what the Skin field already contains before anyone changes it.
The three kinds of skin
| Kind | Where it lives | How it is named |
|---|---|---|
| Filesystem skin | One directory per skin, under webapps/xwiki/skins/ on the server | By its directory name, for example flamingo |
| Wiki skin | A wiki page holding an XWiki.XWikiSkins object | By its page reference, for example XWiki.DefaultSkin |
| Extension skin | A skins folder inside a JAR installed on the wiki, with one directory per skin | By its directory name |
A skin does not have to define everything. Its Base Skin names the skin it falls back to for every template, stylesheet or image it does not provide itself, which is how XWiki.DefaultSkin can consist of almost nothing and still render a complete interface.
A wiki skin reaches an instance the way any other pages do: by importing a XAR, or by installing it with the Extension Manager.
Where skins are stored
Filesystem skins live under webapps/xwiki/skins/, one directory each. XWiki keeps its own skins there so that they can be used even when the database is empty, which a skin held in pages cannot be. This is the whole of that directory on a standard XWiki instance, and the layout of the skin it contains:
webapps/xwiki/skins/
flamingo/
skin.properties the skin's own settings
*.vm Velocity templates
less/ LESS sources, where the styling is written
css/, *.css stylesheets
*.js scripts
logo.svg, logo.png the default logoThat directory is not the full list of the skins an instance can use: it holds the filesystem skins only. Wiki skins are pages and extension skins sit inside JARs, and neither appears there.
What a skin is made of
A skin is a set of files, not a single setting:
| Part | What it does |
|---|---|
| Velocity templates (.vm) | Build the pages of the interface. Overriding one of them is how a wiki skin changes the interface. |
| LESS sources (.less) | Where the styling of the skin is written. In Flamingo the appearance is maintained here rather than directly in the stylesheets. |
| Stylesheets (.css) | The styles the browser finally loads. |
| Scripts (.js) | The behaviour of the interface widgets. |
| Images | The logo and the pictures the templates refer to. |
| skin.properties | The skin's own settings. |
skin.properties is what makes a directory a skin: a filesystem skin without one is not recognised at all. It declares the skin it inherits from and the syntax it produces, and in Flamingo it holds exactly two lines:
parent=
outputSyntax=html/5.0An empty parent means the skin explicitly has no parent, so it falls back to no other skin for anything, which is why Flamingo has to provide a complete interface on its own.
Each action is built by a template of its own, and the styling has a single entry point:
| What it builds | File in the skin |
|---|---|
| The view of a page | view.vm |
| The editor of a page | edit.vm |
| The main stylesheet | style.css |
| Its LESS source | less/style.less.vm |
The settings of a wiki skin
A wiki skin holds the equivalent of skin.properties in the XWiki.XWikiSkins object on its page, shown as Skin Properties when the skin page is opened for editing:
| Setting | What it holds |
|---|---|
| Name | The name of the skin. It is the title the skin page is displayed under. |
| Base Skin | The skin this one falls back to. It holds flamingo on XWiki.DefaultSkin. |
| Logo | An attachment of the skin page to use as the logo, picked with the Choose an attachment button. |
| Output Syntax | The syntax the skin produces, either HTML 5 for a recent skin or XHTML 1.0 for an old one. XWiki reads it to pair the skin with the renderer that produces valid markup for it. |
Output Syntax is left unset on XWiki.DefaultSkin, and a skin that sets none takes the one its Base Skin declares, which is the outputSyntax=html/5.0 of Flamingo above.
The same object carries six more properties, listed under Deprecated properties on the skin page: an older way of replacing a template, which Customize a Skin explains why not to use.
How a skin is identified
The Skin field in the administration and the skin property of a user both take the same kind of value: either the directory name of a filesystem skin, such as flamingo, or the page reference of a wiki skin, such as XWiki.DefaultSkin.
