Skip to Content

Wiki source code of Skins

Version 12.2 by Vincent Massol on 2010/12/10
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 {{id name="s4"/}}
15 == How to create a new Skin ==
MariusButuc 11.1 16 {{warning}}To create a new Skin, you must have access to the server side of the XWiki Enterprise instance.{{/warning}}
17 To create a new Skin, you have to create a new direcory inside the (% class="sectionblockcodecolored directory" %)webapps/xwiki/skins(%%) folder and then add Velocity templates, {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} 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:
18
19 1. inside the (% class="sectionblockcodecolored directory" %)webapps/xwiki/skins(%%) folder, create a folder named (% class="sectionblockcodecolored" %)myskin
20 1. change the Skin at (% class="sectionblockcodecolored" %)instance(%%) level and set it as (% class="sectionblockcodecolored" %)myskin(%%) ( see the section [[C-2>>AdminGuide.Skins#3c2]] for more informations about how to change the Skin )
21 1. open any page in view mode and you will notice that (% class="sectionblockcodecolored" %)myskin(%%) layout is the same as the (% class="sectionblockcodecolored" %)albatross(%%) layout ( this happens because on having no Skin set as the Skin, the default Skin is considered to be (% class="sectionblockcodecolored" %)albatross(%%) )
22 1. change the (% class="sectionblockcodecolored" %)global(%%) template:
23 1*. copy the (% class="sectionblockcodecolored directory" %)webapps/xwiki/templates/global.vm(%%) template and paste it inside the (% class="sectionblockcodecolored" %)myskin(%%) folder
24 1*. to remove the logo, modify the (% class="sectionblockcodecolored" %)global(%%) template under the new Skin and delete the line:(((
25 {{code language="xml"}}
26 <img src="$!logourl" alt="XWiki" width="200" height="70"/>
27 {{/code}}
28 )))
29 1. save the template
Raluca Stavro 1.1 30
31 Open any page in view mode and you will notice that the XWiki logo is not displayed anymore.
32 Congratulations! You have created a new minimal XWiki Skin.
33
hennejg 11.2 34 {{id name="s5"/}}
35 == How to override a Skin ==
MariusButuc 11.1 36 {{warning}}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.{{/warning}}
Raluca Stavro 1.1 37 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.
38 To override a Skin, you have to use the same document that is used to store the Skin.
hennejg 11.2 39 {{id name="5a"/}}
40 === A. Creating a Skin document ===
Raluca Stavro 1.1 41 {{warning}}You need to have the **advance edition mode** activated to access the object editor. Please refer to [[platform:Features.PageEditing]] for more information.{{/warning}}
42 To create a new Skin document, follow these steps:
43
MariusButuc 11.1 44 |(% style="width:60%;color:#222" %)(((
45 1. create a new page - if there is the option (% class="sectionblockcodecolored" %)CREATE -> PAGE(%%) on the main menu, use it to create a page, or, if there is no such option, add the (% class="sectionblockcodecolored" %)New Page(%%) panel on the interface by following these steps:
46 1*. go to (% class="sectionblockcodecolored" %)Administration -> Panel Wizard
47 1*. select the (% class="sectionblockcodecolored" %)Tools(%%) category
48 1*. add the (% class="sectionblockcodecolored" %)New Page(%%) panel on the interface by using drag&drop
49 1*. click on (% class="sectionblockcodecolored" %)Save the new layout(%%) to save your changes
50 1*. open any page in view mode and
51 1*. use the (% class="sectionblockcodecolored" %)New Page(%%) panel to create a page
52 1. edit the document's objects ( if you are in (% class="sectionblockcodecolored" %)edit(%%) mode, use the right panel and choose the (% class="sectionblockcodecolored" %)Objects(%%) editor, or, if you are in (% class="sectionblockcodecolored" %)view(%%) mode, use the top-left menu: (% class="sectionblockcodecolored" %)EDIT{{html}}&nbsp;->&nbsp;{{/html}}OBJECTS(%%))
53 1. add an object of type (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) to the document (use the **ADD OBJECT** panel from the right and select the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) class, then click on (% class="sectionblockcodecolored" %)ADD OBJECT FROM THIS CLASS(%%))
54 1. save the document
55 )))|(((
56 [[[[image:4.png||width="100%" style="border:3px solid #ddd;"]]>>attach:4.png]]
57 )))
58
hennejg 11.2 59 {{id name="5b"/}}
60 === B. Working with the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) class ===
MariusButuc 11.1 61 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 62 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 63 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:
64
65 |(% style="width:60%;color:#222" %)(((
66 1. go to the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) document
67 1. click on the (% class="sectionblockcodecolored" %)add or modify the class properties(%%) link
Raluca Stavro 1.1 68 ( or follow this link: http://localhost:8080/xwiki/bin/edit/XWiki/XWikiSkins?editor=class )
MariusButuc 11.1 69 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
70 1. save the document
71 )))|(((
72 [[[[image:5.png||width="100%" style="border:3px solid #ddd;"]]>>attach:5.png]]
73 )))
Raluca Stavro 1.1 74
hennejg 11.2 75 {{id name="5c"/}}
76 === C. Using a Skin document ===
Raluca Stavro 1.1 77 To use a Skin document, follow these steps:
MariusButuc 11.1 78
79 1. go to the (% class="sectionblockcodecolored" %)Skin(%%) property from inside the (% class="sectionblockcodecolored" %)Administration(%%) interface
80 1. set the value of the property as being the full name of the Skin document
81 1. save the preferences
Raluca Stavro 1.1 82
hennejg 11.2 83 {{id name="5d"/}}
84 === D. Overriding the Skin components ===
MariusButuc 11.1 85 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:
86
Raluca Stavro 12.1 87 ==== Method 1: By editing the XWiki.XWikiSkins properties on the Skin document ====
88
MariusButuc 11.1 89 |(% style="width:60%;color:#222;overflow-x:auto;" %)(((
90 1. add a (% class="sectionblockcodecolored" %)TextArea(%%) property named (% class="sectionblockcodecolored" %)global.vm(%%) to the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) class
91 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
92 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:
93 1*. http://localhost:8080/xwiki/skins/mybaseskin/global.vm ( where mybaseskin is the current Skin used in the Skin document ), or
94 1*. if the previous link is not valid, go to http://localhost:8080/xwiki/templates/global.vm
95 1. replace the following code:(((
96 {{code language="xml"}}
97 <a class="glink"
Raluca Stavro 1.1 98 href="$!xwiki.getURL($context.user, 'view')"
99 id="headeruser">
100 $!xwiki.getUserName($context.user, false)
MariusButuc 11.1 101 </a>
102 {{/code}}
103 )))with(((
104 {{code language="xml"}}
105 <a class="glink"
Raluca Stavro 1.1 106 href="$!xwiki.getURL($context.user, 'view')"
107 id="headeruser">
108 HELLO,
109 $!xwiki.getUserName($context.user, false)
MariusButuc 11.1 110 </a>
111 {{/code}}
112 )))
113 1. save the document
114 )))|(((
115 [[[[image:6.png||width="100%" style="border:3px solid #ddd;"]]>>attach:6.png]]
116 )))
Raluca Stavro 1.1 117
Raluca Stavro 12.1 118 ==== Method 2: By attaching files to the current Skin document ====
119 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:
120 1*. http://localhost:8080/xwiki/skins/mybaseskin/global.vm ( where mybaseskin is the current Skin used in the Skin document ), or
121 1*. if the previous link is not valid, go to http://localhost:8080/xwiki/templates/global.vm
122 1. replace the following code inside the copy of global.vm template:(((
123 {{code language="xml"}}
124 <a class="glink"
125 href="$!xwiki.getURL($context.user, 'view')"
126 id="headeruser">
127 $!xwiki.getUserName($context.user, false)
128 </a>
129 {{/code}}
130 )))with(((
131 {{code language="xml"}}
132 <a class="glink"
133 href="$!xwiki.getURL($context.user, 'view')"
134 id="headeruser">
135 HELLO,
136 $!xwiki.getUserName($context.user, false)
137 </a>
138 {{/code}}
139 )))
140 1. attach the copy of global.vm template to the current Skin document page
141
Raluca Stavro 1.1 142 Now, open any document in view mode and you will notice the nice "HELLO," before your username.
MariusButuc 11.1 143 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 144
hennejg 11.2 145 {{id name="5e"/}}
146 === E. Adding new components to the Skin ===
MariusButuc 11.1 147 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 148
MariusButuc 11.1 149 * attach the files to the Skin document and reffer them by their URL, or
150 * add new properties to the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) object from inside the Skin document, and refer them by their name
151
152 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:
153
154 |(% style="width:60%;color:#222" %)(((
155 1. attach the {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} file to the Skin document
156 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:(((
157 {{code language="xml"}}
158 <link rel="stylesheet"
Raluca Stavro 1.1 159 type="text/css"
160 href="$xwiki.getSkinFile('mynewfile.css')"
MariusButuc 11.1 161 />
162 {{/code}}
163 )))
164 1. save the document
165 )))|(((
166 [[[[image:7.png||width="100%" style="border:3px solid #ddd;"]]>>attach:7.png]]
167 )))
Raluca Stavro 1.1 168
169 OR
170
MariusButuc 11.1 171 |(% style="width:60%;color:#222" %)(((
172 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
173 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:(((
174 {{code language="css"}}
175 @import "mynewfile.css";
176 {{/code}}
177 )))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
178 1. save the document
179 )))|(((
180 [[[[image:8.png||width="100%" style="border:3px solid #ddd;"]]>>attach:8.png]]
181 )))
182
Raluca Stavro 1.1 183 Open any document in view mode and you will notice that the stylesheet is now applied.
184
hennejg 11.2 185 {{id name="5f"/}}
186 === F. Using (% class="sectionblockcodecolored" %)images(%%) in a Skin document ===
187 {{id name="5f1"/}}
188 ==== 1. Changing the (% class="sectionblockcodecolored" %)logo(%%) ====
MariusButuc 11.1 189 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 190
MariusButuc 11.1 191 1. attach the image to the Skin document
192 1. edit the document's objects ( use the top-left menu: (% class="sectionblockcodecolored" %)EDIT -> OBJECTS(%%) )
193 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
194 1. save the document
195
Raluca Stavro 1.1 196 Open any page in view mode and you will notice that the logo is now changed.
197
MariusButuc 11.1 198 {{id name="5f2"/}}
199
200 ==== 2. Adding images to the Skin interface ====
201
202 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:
203
204 1. attach the image to the Skin document
205 1. choose one of these actions:
206 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 )
207 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(%%) )
208 1. paste the following code inside the {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} component:(((
209 {{code language="css"}}
210 body{
Raluca Stavro 1.1 211 background-image: url($xwiki.getSkinFile("myimage.jpg"));
MariusButuc 11.1 212 }
213 {{/code}}
214 )))
Raluca Stavro 1.1 215
216 Open any page in view mode and you will notice that the the background of the page contains your image.
217 Have fun taking advantage of the power of XWiki Skins!
218
MariusButuc 11.1 219 == More about XWiki Skins ==
220
Raluca Stavro 9.1 221 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
222
MariusButuc 11.1 223 == Further reading ==
Raluca Stavro 1.1 224
MariusButuc 11.1 225 * the [[XWiki Data Model>>http://platform.xwiki.org/xwiki/bin/view/DevGuide/DataModel]]
Vincent Massol 12.2 226 * using the [[Skin Editor Application>>extensions:Extension.Skin Editor Application]]
MariusButuc 11.1 227 * [[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