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 space 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.
Where skins are stored
Filesystem skins live under webapps/xwiki/skins/, one directory each. 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.
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.
