Skin Levels
Explanation
A wiki has no single skin setting. The skin a page is displayed with is resolved from several sources (the reader's own profile, the space the page is in, the wiki, and the configuration files of the instance), and the first source that has a value wins. This page explains those levels, the order they are read in and where each one is stored. For what a skin is and which values these settings accept, see Available Skins.
Why there are several levels
The levels exist so that a skin can be chosen as narrowly as the wiki needs. An administrator gives the whole wiki its skin; a section of the wiki can depart from it by setting a skin on its space; and a single user can pick another skin for themselves without affecting anyone else. One consequence is worth keeping in mind: the same page can look different to two readers, because the skin depends on who is reading and not only on the page.
The order XWiki resolves the skin in
For every request, XWiki asks each source below in turn and stops at the first one that has a value. A setting closer to the reader therefore always wins over a more general one.
Four of these steps are not settings anyone edits in the administration:
- The request context holds the skin that code running earlier in the same request has already chosen. Nothing in the interface writes it, but an extension can.
- The skin URL parameter overrides every level below it, for that one request. This is what Preview a Skin does.
- Space preferences cascade. XWiki reads the preferences of the space the page is in, then those of its parent space, and so on up to the top-level space. A skin set on a parent space therefore applies to everything nested under it, unless a nested space sets its own.
- xwiki.properties is consulted for a skin property, but the shipped file defines none, so this step normally passes through to xwiki.cfg.
The two xwiki.cfg settings are the last word: xwiki.defaultskin names the skin of an instance where nothing else is set, and xwiki.defaultbaseskin the skin to fall back to for anything that skin does not provide. Both are shipped as flamingo, which is also the value XWiki uses if neither is defined.
Where each level is stored
| Level | Where the value is stored |
|---|---|
| User | The skin property of the XWiki.XWikiUsers object on the user's profile page |
| Space | The skin property of the XWiki.XWikiPreferences object on the WebPreferences page of the space |
| Wiki | The skin property of the XWiki.XWikiPreferences object on the XWiki.XWikiPreferences page |
| Instance | xwiki.defaultskin and xwiki.defaultbaseskin in xwiki.cfg |
Wiki skins a reader is not allowed to view
A skin can be a wiki page, and a wiki page has view rights. XWiki checks those rights in two places only: the skin named by xwiki.defaultskin, and the base skin a skin inherits from. If the current user cannot view that page, XWiki quietly uses the default skin instead of failing, so the reader gets a working interface rather than an error.
A skin set for a user, a space or the wiki goes through no such check. Restricting the view rights of a wiki skin page does not stop that skin from being applied, so rights are not a way to reserve a skin for some users.
FAQ
Why is the skin I set for the wiki not the one I see?
A level closer to the reader is winning. Check, in this order, whether the URL carries a skin parameter, whether your own profile sets a skin, and whether the space the page is in, or any of its parent spaces, sets one.
Can a skin be set for a single page, or for a group of users?
No. The only levels are the user, the space with its parent spaces, the wiki and the instance configuration. The skin URL parameter is the sole other override, and it lasts one request. Editing templates does not add a level either: the skin is resolved before any template is rendered.
