Skip to Content

Wiki source code of Skins

Version 14.5 by Sorin Burjan on 2011/04/13
Hide last authors
Raluca Stavro 1.1 1 {{velocity}}
2 $xwiki.ssx.use($doc.fullName)
3 {{/velocity}}
MariusButuc 11.1 4
5 (% class="floatinginfobox" %)
6 (((
Raluca Stavro 1.1 7 **Contents**
8
9 {{toc depth="3" start="2"/}}
10 )))
11
MariusButuc 11.1 12 = XWiki Skins =
13
hennejg 11.2 14 == How to create a new Skin ==
Sorin Burjan 13.3 15
Sorin Burjan 13.4 16 {{warning}}
17 To create a new Skin, you must have access to the server side of the XWiki Enterprise instance.
18 {{/warning}}
Sorin Burjan 13.3 19
Sorin Burjan 13.5 20 To create a new Skin, you have to create a new direcory inside the webapps/xwiki/skins folder and then add Velocity templates,CSS stylesheets, Javascript files and images inside it. For example, if you want to remove the logo from the header of the pages, follow these steps:
MariusButuc 11.1 21
Sorin Burjan 13.5 22 1. Inside the webapps/xwiki/skins folder, create a folder named myskin. Copy all files from webapps/xwiki/skins/colibri folder into your new skin directory.
23 1. Change the Skin at global or instance level and set it as myskin ( see [[this>>AdminGuide.Skins]] page for more informations about how to change the Skin )
Sorin Burjan 13.6 24 1. Open any page in view mode and you will notice that myskin layout is the same as the colibri layout (if the skin changes to albatross means that your theme wasn't used. Check the names of your skin directory. Note that skin names are case-sensitive)
Sorin Burjan 13.5 25 1. Change the global template:
26 1*. to remove the logo, modify the global.vm template under the new Skin and delete the line:(((
27 {{code language="html"}}
28 <img src="$!logourl" alt="Wiki Logo"/>
MariusButuc 11.1 29 {{/code}}
30 )))
Sorin Burjan 13.5 31 1. Save the template
Raluca Stavro 1.1 32
Sorin Burjan 13.5 33 Open any page in view mode and you will notice that the XWiki logo is not displayed anymore. Congratulations! You have created a new minimal XWiki Skin.
Sorin Burjan 13.4 34
hennejg 11.2 35 == How to override a Skin ==
Sorin Burjan 13.3 36
Sorin Burjan 13.4 37 {{warning}}
38 To change the Skin, the user must have administrating rights. In the case that you have these rights, make sure that you switch to the Advanced mode in your profile, to enable the advanced options on the top main menu.
39 {{/warning}}
Sorin Burjan 13.3 40
Raluca Stavro 1.1 41 An alternative for creating a new Skin is the possibility to override an existing Skin. The advantage of overriding an existing Skin is the fact that you don't need access to the server filesystem in order to modify the files used by the current Skin.
42 To override a Skin, you have to use the same document that is used to store the Skin.
hennejg 11.2 43 {{id name="5a"/}}
Sorin Burjan 13.4 44
hennejg 11.2 45 === A. Creating a Skin document ===
Sorin Burjan 13.3 46
Sorin Burjan 13.4 47 {{warning}}
Sorin Burjan 14.3 48 You need to have the **advanced edit mode** activated to access the object editor. Please refer to [[platform:Features.PageEditing]] for more information.
Sorin Burjan 13.4 49 {{/warning}}
Sorin Burjan 13.3 50
Raluca Stavro 1.1 51 To create a new Skin document, follow these steps:
52
Sorin Burjan 14.3 53 1. Create a new page. Name it MySkinPage(((
Sorin Burjan 14.4 54 [[image:createSkinPage.png||style="border:1px solid black; width:650px"]]
MariusButuc 11.1 55 )))
Sorin Burjan 14.2 56 1. Edit the document's objects (Edit -> Objects)
57 1. Add an object of type XWiki.XWikiSkins to the document
58 1. Click on add
Sorin Burjan 14.3 59 1. Set the base skin property to colibri. Now, you use colibri as a base skin. As you can see, no files were copied on the file system, but your skin uses colibri.(((
Sorin Burjan 14.4 60 [[image:addSkinObject.png||style="border:1px solid black; width:650px"]]
Sorin Burjan 14.3 61 )))
Sorin Burjan 14.2 62 1. Save the document
MariusButuc 11.1 63
hennejg 11.2 64 === B. Working with the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) class ===
Sorin Burjan 13.4 65
MariusButuc 11.1 66 The base element in overriding a Skin is the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) class ( http://localhost:8080/xwiki/bin/view/XWiki/XWikiSkins ). In order to modify the templates or the files used by a Skin, you have to work with the properties of this class.
Raluca Stavro 1.1 67 By default, the Skin class contains a set of properties that allows you to override some of the templates and files used by the Skin, and it also allows you to set the name of the logo displayed in the header of the interface.
MariusButuc 11.1 68 To override other templates or files, you have to add new properties to the Skin class. For example, if you want to override (% class="sectionblockcodecolored" %)myfile.vm(%%) ( or myfile.css, or myfile.js ), follow these steps:
69
Sorin Burjan 13.4 70 |(% style="width: 60%; color: rgb(34, 34, 34);" %)(((
MariusButuc 11.1 71 1. go to the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) document
72 1. click on the (% class="sectionblockcodecolored" %)add or modify the class properties(%%) link
Raluca Stavro 1.1 73 ( or follow this link: http://localhost:8080/xwiki/bin/edit/XWiki/XWikiSkins?editor=class )
MariusButuc 11.1 74 1. from the **ADD PROPERTY** panel in the right, set the name of the property as being (% class="sectionblockcodecolored" %)myfile.vm(%%), choose the (% class="sectionblockcodecolored" %)TextArea(%%) type, and click on (% class="sectionblockcodecolored" %)Add
75 1. save the document
76 )))|(((
Sorin Burjan 13.4 77 [[[[image:5.png||style="border: 3px solid rgb(221, 221, 221);" width="100%"]]>>attach:5.png]]
MariusButuc 11.1 78 )))
Raluca Stavro 1.1 79
Sorin Burjan 13.5 80 {{id name="5c"/}}
Sorin Burjan 13.4 81
hennejg 11.2 82 === C. Using a Skin document ===
Sorin Burjan 13.4 83
Raluca Stavro 1.1 84 To use a Skin document, follow these steps:
MariusButuc 11.1 85
86 1. go to the (% class="sectionblockcodecolored" %)Skin(%%) property from inside the (% class="sectionblockcodecolored" %)Administration(%%) interface
87 1. set the value of the property as being the full name of the Skin document
88 1. save the preferences
Raluca Stavro 1.1 89
hennejg 11.2 90 {{id name="5d"/}}
Sorin Burjan 13.4 91
hennejg 11.2 92 === D. Overriding the Skin components ===
Sorin Burjan 13.4 93
MariusButuc 11.1 94 Let's add a "HELLO," before the username on the top right menu, not by modifying the (% class="sectionblockcodecolored" %)global.vm(%%) template on the server, but overriding it inside the Skin document. Follow these steps:
95
Raluca Stavro 12.1 96 ==== Method 1: By editing the XWiki.XWikiSkins properties on the Skin document ====
97
Sorin Burjan 13.4 98 |(% style="width: 60%; color: rgb(34, 34, 34); overflow-x: auto;" %)(((
MariusButuc 11.1 99 1. add a (% class="sectionblockcodecolored" %)TextArea(%%) property named (% class="sectionblockcodecolored" %)global.vm(%%) to the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) class
100 1. edit the Skin document's objects ( use the top-left menu: (% class="sectionblockcodecolored" %)EDIT -> OBJECTS(%%) ) and open the properties of the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) object
Sorin Burjan 13.4 101 1. copy the original content of the (% class="sectionblockcodecolored" %)global.vm(%%) template and paste it in the property field named (% class="sectionblockcodecolored" %)global.vm(%%); if you don't have access to the server filesystem, open the template by following one of these links:
MariusButuc 11.1 102 1*. http://localhost:8080/xwiki/skins/mybaseskin/global.vm ( where mybaseskin is the current Skin used in the Skin document ), or
103 1*. if the previous link is not valid, go to http://localhost:8080/xwiki/templates/global.vm
104 1. replace the following code:(((
105 {{code language="xml"}}
106 <a class="glink"
Raluca Stavro 1.1 107 href="$!xwiki.getURL($context.user, 'view')"
108 id="headeruser">
109 $!xwiki.getUserName($context.user, false)
MariusButuc 11.1 110 </a>
111 {{/code}}
112 )))with(((
113 {{code language="xml"}}
114 <a class="glink"
Raluca Stavro 1.1 115 href="$!xwiki.getURL($context.user, 'view')"
116 id="headeruser">
117 HELLO,
118 $!xwiki.getUserName($context.user, false)
MariusButuc 11.1 119 </a>
120 {{/code}}
121 )))
122 1. save the document
123 )))|(((
Sorin Burjan 13.4 124 [[[[image:6.png||style="border: 3px solid rgb(221, 221, 221);" width="100%"]]>>attach:6.png]]
MariusButuc 11.1 125 )))
Raluca Stavro 1.1 126
Raluca Stavro 12.1 127 ==== Method 2: By attaching files to the current Skin document ====
Sorin Burjan 13.4 128
129 1. create a copy of the global.vm template; if you don't have access to the server filesystem, open the template by following one of these links:
Raluca Stavro 12.1 130 1*. http://localhost:8080/xwiki/skins/mybaseskin/global.vm ( where mybaseskin is the current Skin used in the Skin document ), or
131 1*. if the previous link is not valid, go to http://localhost:8080/xwiki/templates/global.vm
132 1. replace the following code inside the copy of global.vm template:(((
133 {{code language="xml"}}
134 <a class="glink"
135 href="$!xwiki.getURL($context.user, 'view')"
136 id="headeruser">
137 $!xwiki.getUserName($context.user, false)
138 </a>
139 {{/code}}
140 )))with(((
141 {{code language="xml"}}
142 <a class="glink"
143 href="$!xwiki.getURL($context.user, 'view')"
144 id="headeruser">
145 HELLO,
146 $!xwiki.getUserName($context.user, false)
147 </a>
148 {{/code}}
149 )))
150 1. attach the copy of global.vm template to the current Skin document page
151
Raluca Stavro 1.1 152 Now, open any document in view mode and you will notice the nice "HELLO," before your username.
MariusButuc 11.1 153 Follow the same process in order to override (% class="sectionblockcodecolored" %)Javascript(%%) and (% class="sectionblockcodecolored" %){{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}}(%%) files ( http://localhost:8080/xwiki/skins/colibri/myfile.css ).
Raluca Stavro 1.1 154
Marta Girdea 13.1 155 ==== 3. Overriding a skin resource ====
156
157 Just like templates, resource files such as images or css/js files can be overridden. To do that, the replacement must be attached to the Skin document, making sure it complies with the naming convention explained below. To find out the right name for your replacement resource, here is the trick:
Sorin Burjan 13.4 158
Marta Girdea 13.1 159 1. find the path on the filesystem of the resource to replace (you can easily obtain that information using development tools such as [[Firebug>>http://getfirebug.com/]]); for instance, let's say this path is either
Sorin Burjan 13.4 160 {{code}}/xwiki/resources/icons/silk/myicon.gif{{/code}}
Marta Girdea 13.1 161 for a resource found in the general resource directry, or
Sorin Burjan 13.4 162 {{code}}/xwiki/skins/colibri/myimage.png{{/code}}
Marta Girdea 13.1 163 if the resource is specific to a certain skin, in this case 'colibri'.
164 1. strip from this path everything from the beginning until 'resources/' or the name of the skin, included; in the previous examples, you will obtain in the first case
Sorin Burjan 13.4 165 {{code}}icons/silk/myicon.gif{{/code}}
Marta Girdea 13.1 166 and in the second case simply
Sorin Burjan 13.4 167 {{code}}myimage.png{{/code}}
Marta Girdea 13.1 168 1. in this path, replace '/' with '.'; after this operation, we will get {{code}}icons.silk.myicon.gif{{/code}} for the first image example, while the second one remains unchanged. **This is the name of the file corresponding to the resource that you need to attach to the Skin document in order to make the replacement**.
169 1. create a file named as explained above and attach it to your Skin
170
171 {{info}}
172 **Technical note**: This trick works for any resource whose URL is generated in the skin by the {{code}}$xwiki.getSkinFile(){{/code}}, {{code}}$xwiki.jsfx(){{/code}} or {{code}}$xwiki.ssfx(){{/code}} methods, for instance like this:
173
174 {{code language="none"}}
175 .infomessage {
176 background-image: url("$xwiki.getSkinFile('icons/silk/information.gif')");
177 }
178 {{/code}}
179
180 In this case, {{code}}$xwiki.getSkinFile('icons/silk/information.gif'){{/code}} will first search for an image called 'icons.silk.information.gif' attached to the configured Skin document, if any. If that image exists, it will generate its URL. Otherwise, it will continue to search for 'icons/silk/information.gif' in the base skins and finally in the general 'resources/' directory.
181 {{/info}}
182
183
Sorin Burjan 13.5 184 {{id name="5e"/}}
Sorin Burjan 13.4 185
hennejg 11.2 186 === E. Adding new components to the Skin ===
Sorin Burjan 13.4 187
MariusButuc 11.1 188 If you want to add new files to the skin, like (% class="sectionblockcodecolored" %){{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} (%%) or (% class="sectionblockcodecolored" %)Javascript(%%) files, you have two options:
Raluca Stavro 1.1 189
MariusButuc 11.1 190 * attach the files to the Skin document and reffer them by their URL, or
191 * add new properties to the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) object from inside the Skin document, and refer them by their name
192
193 For example, if you want to add a new {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} file to the Skin, named (% class="sectionblockcodecolored" %)mynewfile.css(%%), follow one of these set of steps:
194
Sorin Burjan 13.4 195 |(% style="width: 60%; color: rgb(34, 34, 34);" %)(((
MariusButuc 11.1 196 1. attach the {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} file to the Skin document
197 1. override the stylesheets.vm template ( check the section [[D>>#5d]] to learn how to override a Skin component ), and add the reference to your file in the template:(((
198 {{code language="xml"}}
199 <link rel="stylesheet"
Raluca Stavro 1.1 200 type="text/css"
201 href="$xwiki.getSkinFile('mynewfile.css')"
MariusButuc 11.1 202 />
203 {{/code}}
204 )))
205 1. save the document
206 )))|(((
Sorin Burjan 13.4 207 [[[[image:7.png||style="border: 3px solid rgb(221, 221, 221);" width="100%"]]>>attach:7.png]]
MariusButuc 11.1 208 )))
Raluca Stavro 1.1 209
210 OR
211
Sorin Burjan 13.4 212 |(% style="width: 60%; color: rgb(34, 34, 34);" %)(((
MariusButuc 11.1 213 1. add a new property to the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%), name it (% class="sectionblockcodecolored" %)mynewfile.css(%%) ( check the section [[B>>#5b]] for more information about how to work with this class ), edit the Skin document's objects ( use the top-left menu: (% class="sectionblockcodecolored" %)EDIT -> OBJECTS(%%) ), and paste the {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} code into the (% class="sectionblockcodecolored" %)mynewfile.css(%%) field
214 1. override the (% class="sectionblockcodecolored" %)style.css(%%) component ( see the section [[D>>#5d]] for more information about how to override a Skin compoment ) and add the following line to the content of the (% class="sectionblockcodecolored" %)style.css(%%) property:(((
215 {{code language="css"}}
216 @import "mynewfile.css";
217 {{/code}}
218 )))the important thing is to add a reference to the new component from a existing one; you must know most of the components content, so that you will take the best decision about which existing component will contain a reference to the new one
219 1. save the document
220 )))|(((
Sorin Burjan 13.4 221 [[[[image:8.png||style="border: 3px solid rgb(221, 221, 221);" width="100%"]]>>attach:8.png]]
MariusButuc 11.1 222 )))
223
Raluca Stavro 1.1 224 Open any document in view mode and you will notice that the stylesheet is now applied.
225
hennejg 11.2 226 {{id name="5f"/}}
Sorin Burjan 13.4 227
hennejg 11.2 228 === F. Using (% class="sectionblockcodecolored" %)images(%%) in a Skin document ===
Sorin Burjan 13.4 229
hennejg 11.2 230 {{id name="5f1"/}}
Sorin Burjan 13.4 231
hennejg 11.2 232 ==== 1. Changing the (% class="sectionblockcodecolored" %)logo(%%) ====
Sorin Burjan 13.4 233
MariusButuc 11.1 234 For example, if you want to add an image named (% class="sectionblockcodecolored" %)myimage.jpg(%%) as being the logo for the current Skin, follow these steps:
Raluca Stavro 1.1 235
MariusButuc 11.1 236 1. attach the image to the Skin document
237 1. edit the document's objects ( use the top-left menu: (% class="sectionblockcodecolored" %)EDIT -> OBJECTS(%%) )
238 1. use the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) object and set the (% class="sectionblockcodecolored" %)Logo(%%) property as being the name of the attached image: (% class="sectionblockcodecolored" %)myimage.jpg
239 1. save the document
240
Raluca Stavro 1.1 241 Open any page in view mode and you will notice that the logo is now changed.
242
Sorin Burjan 13.5 243 {{id name="5f2"/}}
MariusButuc 11.1 244
245 ==== 2. Adding images to the Skin interface ====
246
247 To add images to the interface, attach them to the Skin document and use them in the {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} code. For example, if you want to use (% class="sectionblockcodecolored" %)myimage.jpg(%%) as background image for the pages inside your XWiki Enterprise instance, follow these steps:
248
249 1. attach the image to the Skin document
Sorin Burjan 13.4 250 1. choose one of these actions:
MariusButuc 11.1 251 1*. add a new {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} component to the Skin, name it (% class="sectionblockcodecolored" %)pagebackground.css(%%) and add a reference to it from the (% class="sectionblockcodecolored" %)style.css(%%) component ( see the section [[E>>#5e]] for more information about how to add new components to the Skin )
252 1*. override the (% class="sectionblockcodecolored" %)mybaseskin.css(%%) component ( where mybaseskin is the name of the current Skin - for example: (% class="sectionblockcodecolored" %)albatross.css(%%), (% class="sectionblockcodecolored" %)toucan.css(%%) or (% class="sectionblockcodecolored" %)colibri.css(%%) )
253 1. paste the following code inside the {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} component:(((
254 {{code language="css"}}
255 body{
Raluca Stavro 1.1 256 background-image: url($xwiki.getSkinFile("myimage.jpg"));
MariusButuc 11.1 257 }
258 {{/code}}
259 )))
Raluca Stavro 1.1 260
261 Open any page in view mode and you will notice that the the background of the page contains your image.
262 Have fun taking advantage of the power of XWiki Skins!
263
MariusButuc 11.1 264 == More about XWiki Skins ==
265
Raluca Stavro 9.1 266 In order to find more about XWiki Skins, check the [[Skins Tutorial>>AdminGuide.Skins]] from inside the Admin Guide and the [[Skins Tutorial>>Features.Skins]] from inside the User Guide
267
MariusButuc 11.1 268 == Further reading ==
Raluca Stavro 1.1 269
MariusButuc 11.1 270 * the [[XWiki Data Model>>http://platform.xwiki.org/xwiki/bin/view/DevGuide/DataModel]]
Vincent Massol 12.2 271 * using the [[Skin Editor Application>>extensions:Extension.Skin Editor Application]]
MariusButuc 11.1 272 * [[edit only one object>>http://dev.xwiki.org/xwiki/bin/view/Drafts/EditOneObject]]

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected