Wiki source code of Available Skins
Last modified by Eleni Cojocariu on 2026/09/23 12:16
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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>>doc:documentation.xs.admin.skins.levels.WebHome]]. | ||
| 2 | |||
| 3 | == The skins shipped with XWiki == | ||
| 4 | |||
| 5 | XWiki ships one skin, **Flamingo**, and one wiki skin page built on it, **XWiki.DefaultSkin**. | ||
| 6 | |||
| 7 | 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. | ||
| 8 | |||
| 9 | == The three kinds of skin == | ||
| 10 | |||
| 11 | |=Kind |=Where it lives |=How it is named | ||
| 12 | |Filesystem skin |One directory per skin, under ##webapps/xwiki/skins/## on the server |By its directory name, for example ##flamingo## | ||
| 13 | |Wiki skin |A wiki page holding an ##XWiki.XWikiSkins## object |By its page reference, for example ##XWiki.DefaultSkin## | ||
| 14 | |Extension skin |A ##skins## folder inside a JAR installed on the wiki, with one directory per skin |By its directory name | ||
| 15 | |||
| 16 | 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. | ||
| 17 | |||
| 18 | A wiki skin reaches an instance the way any other pages do: by importing a XAR, or by installing it with the Extension Manager. | ||
| 19 | |||
| 20 | == Where skins are stored == | ||
| 21 | |||
| 22 | 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: | ||
| 23 | |||
| 24 | {{code language="none"}} | ||
| 25 | webapps/xwiki/skins/ | ||
| 26 | flamingo/ | ||
| 27 | skin.properties the skin's own settings | ||
| 28 | *.vm Velocity templates | ||
| 29 | less/ LESS sources, where the styling is written | ||
| 30 | css/, *.css stylesheets | ||
| 31 | *.js scripts | ||
| 32 | logo.svg, logo.png the default logo | ||
| 33 | {{/code}} | ||
| 34 | |||
| 35 | That 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. | ||
| 36 | |||
| 37 | == What a skin is made of == | ||
| 38 | |||
| 39 | A skin is a set of files, not a single setting: | ||
| 40 | |||
| 41 | |=Part |=What it does | ||
| 42 | |Velocity templates (##.vm##) |Build the pages of the interface. Overriding one of them is how a wiki skin changes the interface. | ||
| 43 | |LESS sources (##.less##) |Where the styling of the skin is written. In Flamingo the appearance is maintained here rather than directly in the stylesheets. | ||
| 44 | |Stylesheets (##.css##) |The styles the browser finally loads. | ||
| 45 | |Scripts (##.js##) |The behaviour of the interface widgets. | ||
| 46 | |Images |The logo and the pictures the templates refer to. | ||
| 47 | |##skin.properties## |The skin's own settings. | ||
| 48 | |||
| 49 | ##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: | ||
| 50 | |||
| 51 | {{code language="properties"}} | ||
| 52 | parent= | ||
| 53 | outputSyntax=html/5.0 | ||
| 54 | {{/code}} | ||
| 55 | |||
| 56 | An 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. | ||
| 57 | |||
| 58 | Each action is built by a template of its own, and the styling has a single entry point: | ||
| 59 | |||
| 60 | |=What it builds |=File in the skin | ||
| 61 | |The view of a page |##view.vm## | ||
| 62 | |The editor of a page |##edit.vm## | ||
| 63 | |The main stylesheet |##style.css## | ||
| 64 | |Its LESS source |##less/style.less.vm## | ||
| 65 | |||
| 66 | == The settings of a wiki skin == | ||
| 67 | |||
| 68 | 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: | ||
| 69 | |||
| 70 | {{image reference="skin-document-properties.png" size="extra" alt="The Skin Properties block of the XWiki.DefaultSkin page, holding the Name, Base Skin, Logo and Output Syntax fields"/}} | ||
| 71 | |||
| 72 | |=Setting |=What it holds | ||
| 73 | |Name |The name of the skin. It is the title the skin page is displayed under. | ||
| 74 | |Base Skin |The skin this one falls back to. It holds ##flamingo## on ##XWiki.DefaultSkin##. | ||
| 75 | |Logo |An attachment of the skin page to use as the logo, picked with the //Choose an attachment// button. | ||
| 76 | |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. | ||
| 77 | |||
| 78 | //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. | ||
| 79 | |||
| 80 | {{info}} | ||
| 81 | The //Logo// setting is used only when the color theme in use declares no logo of its own. The color theme an out-of-the-box wiki uses declares one, so the logo displayed comes from the color theme and this setting has no visible effect. Change the logo in the color theme instead. | ||
| 82 | {{/info}} | ||
| 83 | |||
| 84 | 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>>doc:documentation.xs.admin.skins.customize.WebHome]] explains why not to use. | ||
| 85 | |||
| 86 | == How a skin is identified == | ||
| 87 | |||
| 88 | 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##. | ||
| 89 | |||
| 90 | {{info}} | ||
| 91 | Skin names are case-sensitive. The value is used exactly as written, either as a path under ##webapps/xwiki/skins/## or as a page reference, and both are case-sensitive. | ||
| 92 | {{/info}} |
