Wiki source code of Skin Levels
Last modified by Eleni Cojocariu on 2026/09/23 12:16
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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>>doc:documentation.xs.admin.skins.available.WebHome]]. | ||
| 2 | |||
| 3 | == Why there are several levels == | ||
| 4 | |||
| 5 | 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. | ||
| 6 | |||
| 7 | == The order XWiki resolves the skin in == | ||
| 8 | |||
| 9 | 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. | ||
| 10 | |||
| 11 | {{plantuml}} | ||
| 12 | @startuml | ||
| 13 | !theme bluegray | ||
| 14 | start | ||
| 15 | partition "For one request" { | ||
| 16 | :""skin"" key in the request context; | ||
| 17 | -> not set; | ||
| 18 | :""skin"" parameter in the URL; | ||
| 19 | } | ||
| 20 | -> not set; | ||
| 21 | partition "In the wiki" { | ||
| 22 | :the current user's skin; | ||
| 23 | -> not set; | ||
| 24 | :the current page, then each of the pages it is nested under; | ||
| 25 | -> not set; | ||
| 26 | :the wiki; | ||
| 27 | } | ||
| 28 | -> not set; | ||
| 29 | partition "In the configuration files" { | ||
| 30 | :""skin"" in ""xwiki.properties""; | ||
| 31 | -> not set; | ||
| 32 | :""xwiki.defaultskin"" in ""xwiki.cfg""; | ||
| 33 | -> not set; | ||
| 34 | :""xwiki.defaultbaseskin"" in ""xwiki.cfg""; | ||
| 35 | } | ||
| 36 | -> none of them; | ||
| 37 | :""flamingo"", the built-in default; | ||
| 38 | stop | ||
| 39 | @enduml | ||
| 40 | {{/plantuml}} | ||
| 41 | |||
| 42 | Four of these steps are not settings anyone edits in the administration: | ||
| 43 | |||
| 44 | * 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. | ||
| 45 | * The **##skin## URL parameter** overrides every level below it, for that one request. This is what [[Preview a Skin>>doc:documentation.xs.admin.skins.preview.WebHome]] does. | ||
| 46 | * **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. | ||
| 47 | * **##xwiki.properties##** is consulted for a ##skin## property, but the shipped file defines none, so this step normally passes through to ##xwiki.cfg##. | ||
| 48 | |||
| 49 | 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. | ||
| 50 | |||
| 51 | == Where each level is stored == | ||
| 52 | |||
| 53 | |=Level |=Where the value is stored | ||
| 54 | |User |The ##skin## property of the ##XWiki.XWikiUsers## object on the user's profile page | ||
| 55 | |Page |The ##skin## property of the ##XWiki.XWikiPreferences## object on the page's ##WebPreferences## page | ||
| 56 | |Wiki |The ##skin## property of the ##XWiki.XWikiPreferences## object on the ##XWiki.XWikiPreferences## page | ||
| 57 | |Instance |##xwiki.defaultskin## and ##xwiki.defaultbaseskin## in ##xwiki.cfg## | ||
| 58 | |||
| 59 | A page's ##WebPreferences## belongs to the space that page is implemented as, which the FAQ of [[Content Organization>>doc:documentation.xs.admin.base.content-organization.WebHome]] explains. That is why XWiki still names this level after spaces in its configuration API, while the interface only ever speaks of pages. | ||
| 60 | |||
| 61 | == Wiki skins a reader is not allowed to view == | ||
| 62 | |||
| 63 | 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. | ||
| 64 | |||
| 65 | 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. |
