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 page and the pages it is nested under, 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 branch of the page tree can depart from it by setting a skin on its top page; 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.
- Page preferences cascade. XWiki reads the preferences of the page, then those of the page it is nested under, and so on up to the top-level page. A skin set on a page therefore applies to everything nested under it, unless a nested page 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 |
| Page | The skin property of the XWiki.XWikiPreferences object on the page's WebPreferences page |
| Wiki | The skin property of the XWiki.XWikiPreferences object on the XWiki.XWikiPreferences page |
| Instance | xwiki.defaultskin and xwiki.defaultbaseskin in xwiki.cfg |
A page's WebPreferences belongs to the space that page is implemented as, which the FAQ of Content Organization explains. That is why XWiki still names this level after spaces in its configuration API, while the interface only ever speaks of pages.
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 page 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 page, or any of the pages it is nested under, sets one.
Can a skin be set for one page only, or for a group of users?
No. A skin set on a page applies to that page and to everything nested under it, and a terminal page cannot carry the setting at all, since the administration reached from it is its parent's. There is no level for a group: the levels are the user, the page with the pages it is nested under, 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.
