Customize a Skin
Steps
A wiki skin can replace any template, stylesheet, script or image of the skin it is built on, with content held on the skin page itself and nothing changed on the server. The replacement applies to every page displayed with that skin. It can be held in two ways: typed into an override on the skin page, which this page describes and which suits a template, a stylesheet or a script you write yourself, or attached to that page as a file, which is what Override a Skin Resource with an Attachment covers. You need administration rights on the wiki, and Available Skins describes what a wiki skin is and which one an out-of-the-box wiki uses.
- Open the "Themes" section of the wiki administration, as described in Change the Skin of a Wiki.
- Click "Customize", beside the "Skin" field, to open the skin page that field names:
- Click "Edit this skin".
- Under "Overridden templates", type the path of the template to replace in the "Add a new overriding template" field (footer.vm, the footer of every page, for example), then click "Add". A file held in a directory keeps the / of its path here, as in less/style.less.vm:
- Write what that template is to produce in the "Content" field of the override that appears. Rather than starting from an empty field, open the file the Base Skin serves and edit a copy of it; its address is the name of that skin followed by the path of the file:
http://localhost:8080/xwiki/skins/flamingo/footer.vm
- Click "Save & View".
- Open any page displayed with that skin, and check that the part of the interface the template builds is the one you wrote:
FAQ
Can one template include another?
Yes, and that is how a skin is split across several files: #template('myTemplate.vm') inserts the template of that name at that point.
Which replacement is used when a template is defined more than once?
The skin takes the first one it finds, in this order: an override carrying that path under "Overridden templates"; the property of the same name under "Deprecated properties"; an attachment of the skin page named after the template, a template held in a subdirectory being attached under a name where the / is replaced by a .; and, if none of the three exists, whatever the skin named in "Base Skin" provides. An override, by contrast, keeps the / of the path.
Should I use the "Deprecated properties" section?
No. Its six text areas (Style, Header, Footer, View Header, View and Edit) are kept so that skins written before the "Overridden templates" mechanism go on working, and they replace those six files and nothing else, so a file held in a directory, a LESS source among them, cannot be replaced that way at all. They stay collapsed until you click the section heading:
How do I remove an override?
Open the skin page for editing, click the cross button beside the template's path, and confirm. The override leaves the skin page immediately, without waiting for a save, and the template the "Base Skin" provides is used again.
