Wiki source code of Skins

Last modified by Simon Urli on 2023/10/10

Show last authors
1 (% class="floatinginfobox box" %)
2 (((
3 **Contents**
4
5 {{toc depth="3" start="2"/}}
6 )))
7
8 = XWiki Skins =
9
10 == How to create a new Skin ==
11
12 {{warning}}
13 To create a new Skin, you must have access to the server side of the XWiki instance.
14 {{/warning}}
15
16 {{info}}
17 Usually, for most purposes, it is largely enough and better to override an existing skin and customize (only) the parts you need to customize instead of forking an existing one or creating one from scratch. See "How to override a Skin".
18 {{/info}}
19
20 To create a new Skin, you have to create a new directory 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:
21
22 * 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 * Change the Skin at global or instance level and set it as myskin ( see [[this>>xwiki:Documentation.AdminGuide.Skins]] page for more informations about how to change the Skin )
24 * 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)
25 * Change the global template:to remove the logo, modify the global.vm template under the new Skin and delete the line:(((
26 {{code language="html"}}
27 <img src="$!logourl" alt="Wiki Logo"/>
28 {{/code}}
29 )))
30 * Save the template
31
32 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.
33
34 === skin.properties ===
35
36 {{info}}Since 6.4.{{/info}} Inside your new skin, you should have a file called ##skin.properties##. This file contains some properties about the skin and looks like this:
37
38 {{code language="cfg"}}
39 parent=...
40 outputSyntax=...
41 {{/code}}
42
43 |=Property|=Description
44 |##parent##|Indicate another skin to inherit from. If it is set to an empty value (##parent=##) the skin will directly inherit from the WAR. If it is not set at all it will inherit from whatever is configured in ##xwiki.cfg##'s ##xwiki.defaultbaseskin## property.
45 |##outputSyntax##|{{info}}Since 7.1M1.{{/info}} Indicate the output syntax the skin is using. XWiki will use the correct renderer to generate valid HTML code. If it is set to an empty value (##outputSyntax=##) or not set at all, this setting will be inherited from the parent skin. If there is no parent, the syntax used is XHTML1.0 (for compatibility with old skins that did not set this property). Supported values are ##html/5.0## and ##xhtml/1.0##.
46
47 == How to override a Skin ==
48
49 {{warning}}
50 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.
51 {{/warning}}
52
53 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.
54 To override a Skin, you have to use the same document that is used to store the Skin.
55
56 === A. Creating a Skin document ===
57
58 {{warning}}
59 You need to have the **advanced edit mode** activated to access the object editor. Please refer to [[xwiki:Documentation.UserGuide.Features.PageEditing]] for more information.
60 {{/warning}}
61
62 To create a new Skin document, follow these steps:
63
64 * Create a new page. Name it MySkinPage(((
65 [[image:createSkinPage.png||style="border:1px solid black" width="650"]]
66 )))
67 * Edit the document's objects (Edit -> Objects)
68 * Add an object of type XWiki.XWikiSkins to the document
69 * Click on add
70 * Set the base skin property. The base skin property points to the skin you wish to override. You can use either the filesystem skin directory name (for a filesystem skin to override) or the page name where the skin is defined (for overriding a page-based skin). Set it to ##colibri## for using the ##colibri## skin as a base skin. As you can see, no files were copied on the file system, but your skin uses colibri.(((
71 [[image:addSkinObject.png||style="border:1px solid black" width="650"]]
72 )))
73 * Save the document
74
75 === B. Working with the XWiki.XWikiSkins class ===
76
77 {{warning}}
78 Since 7.0RC1, this mechanism is deprecated. You don't need to edit the XWiki.XWikiSkins class anymore. You should simply use the [[extensions:Extension.Skin Application]]).
79 {{/warning}}
80
81 The base element in overriding a Skin is the 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. 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.
82 To override other templates or files, you have to add new properties to the Skin class. For example, if you want to override myfile.vm ( or myfile.css, or myfile.js ), follow these steps:
83
84
85 * Go to the XWiki.XWikiSkins document
86 * Edit the document's class (Edit -> Class) or follow this link: http:~/~/localhost:8080/xwiki/bin/edit/XWiki/XWikiSkins?editor=class
87 * Add a new property myfile.vm as TextArea type
88 * Click on Add. The myfile.vm property should appear in the list(((
89 [[image:editXWikiSkins.png||style="border:1px solid black" width="650"]]
90 )))
91 * Save the document
92
93 === C. Using a Skin document ===
94
95 To use a Skin document, follow these steps:
96
97 * Go to the skin property from inside the Administrationpage, Presentation section
98 * Set the value of the files as being the full name of the Skin document. For our skin page created above, we will type Main.MySkinPage
99 * Save the preferences
100
101 === D. Overriding the Skin components ===
102
103 Let's add a "Hello" before the username on the top right menu, not by modifying the menuview.vm template on the server, but overriding it inside the Skin document. Follow these steps:
104
105 ==== Method 1: By editing the XWiki.XWikiSkins properties on the Skin document ====
106
107 {{warning}}
108 Since 7.0RC1, this method is deprecated. You don't need to edit the XWiki.XWikiSkins class anymore. You should simply use the [[extensions:Extension.Skin Application]]).
109 {{/warning}}
110
111 * Add a TextArea property named menuview.vm to the XWiki.XWikiSkins class(((
112 [[image:XWikiSkinsMenuView.png||style="border:1px solid black" width="650"]]
113 )))
114 * Edit your skin document's objects (Edit -> Objects) and open the properties of the object
115 * Copy the original content of the menuview.vm template and paste it in the property field named menuview.vm. If you don't have access to the server filesystem, open the template by following http:~/~/localhost:8080/xwiki/templates/menuview.vm (to access a template from the skin, use http:~/~/localhost:8080/xwiki/skins/colibri/)
116 * Replace the following code:(((
117 {{code language="html"}}
118 #xwikitopmenuentrystart($xwiki.getURL($xcontext.user, 'view') "$msg.get('core.menu.type.profile')__SEPARATOR__$!xwiki.getUserName($xcontext.user, false)" 'tmUser' 'hasIcon')
119 {{/code}}
120
121 with
122
123 {{code language="html"}} #xwikitopmenuentrystart($xwiki.getURL($xcontext.user, 'view') "$msg.get('Hello')__SEPARATOR__$!xwiki.getUserName($xcontext.user, false)" 'tmUser' 'hasIcon'){{/code}}
124 [[image:MySkinPageWithMenuView.png||style="border:1px solid black" width="650"]]
125 )))
126 * Save the document
127
128 ==== Method 2: By attaching files to the current Skin document ====
129
130 * Create a file on your computer called menuview.vm. Copy the original content of the menuview.vm into your local file. If you don't have access to the server filesystem, open the template by following http:~/~/localhost:8080/xwiki/skins/colibri/menuview.vm
131 * Replace the following code:(((
132 {{code language="html"}}
133 #xwikitopmenuentrystart($xwiki.getURL($xcontext.user, 'view') "$msg.get('core.menu.type.profile')__SEPARATOR__$!xwiki.getUserName($xcontext.user, false)" 'tmUser' 'hasIcon')
134 {{/code}}
135
136 with
137
138 {{code language="html"}}
139 #xwikitopmenuentrystart($xwiki.getURL($xcontext.user, 'view') "$msg.get('Hello')__SEPARATOR__$!xwiki.getUserName($xcontext.user, false)" 'tmUser' 'hasIcon')
140 {{/code}}
141 )))
142 * Attach the copy of menuview.vm template to the current Skin document page
143
144 Now, open any document in view mode and you will notice the nice "Hello" before your username. Follow the same process in order to override Javascript and CSS files ( http:~/~/localhost:8080/xwiki/skins/colibri/myfile.css ).
145
146 ==== 3. Overriding a skin resource ====
147
148 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
149
150 * 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
151
152 {{code}}/xwiki/resources/icons/silk/myicon.gif{{/code}}
153 for a resource found in the general resource directry, or
154 {{code}}/xwiki/skins/colibri/myimage.png{{/code}}
155 if the resource is specific to a certain skin, in this case 'colibri'.
156
157 * 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{{code}}icons/silk/myicon.gif{{/code}}
158 and in the second case simply
159 {{code}}myimage.png{{/code}}
160 * 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**.
161 * Create a file named as explained above and attach it to your Skin
162
163 {{info}}
164 **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:
165
166 {{code language="none"}}
167 .infomessage {
168 background-image: url("$xwiki.getSkinFile('icons/silk/information.gif')");
169 }
170 {{/code}}
171
172 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.
173 {{/info}}
174
175 === E. Adding new components to the Skin ===
176
177 If you want to add new files to the skin, like CSS or Javascript files, you have two options:
178
179 * attach the files to the Skin document and reffer them by their URL, or
180 * add new properties to the (% class="sectionblockcodecolored" %)XWiki.XWikiSkins(%%) object from inside the Skin document, and refer them by their name
181
182 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:
183
184
185 * Attach the CSS file to the Skin document
186 * Override the stylesheets.vm template and add the reference to your file in the template:(((
187 {{code language="html"}}
188 <link rel="stylesheet"
189 type="text/css"
190 href="$xwiki.getSkinFile('mynewfile.css')"
191 />
192 {{/code}}
193 )))
194 * Save the document
195
196 (((
197 OR
198 )))
199
200 (((
201 * Add a new property to the XWiki.XWikiSkins, name it mynewfile.css, edit the Skin document's objects ( Edit -> Objects ), and paste the CSS code into the mynewfile.css field
202 * Override the Style component and add the following line to the content of the Style property:(((
203 {{code language="css"}}
204 @import "mynewfile.css";
205 {{/code}}
206
207
208
209 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 .
210
211 [[image:importCSS.png||style="border:1px solid black" width="650"]]
212 )))
213
214 * Save the document
215
216 Open any document in view mode and you will notice that the stylesheet is now applied.
217
218
219 === F. Using images in a Skin document ===
220
221 ==== 1. Changing the logo ====
222
223 For example, if you want to add an image named myimage.jpg as being the logo for the current Skin, follow these steps:
224
225 * Attach the image to the Skin document
226 * Edit the document's objects
227 * Use the XWiki.XWikiSkins object and set the Logo property as being the name of the attached image myimage.jpg
228 * Save the document
229
230 Open any page in view mode and you will notice that the logo is now changed.
231
232
233 ==== 2. Adding images to the Skin interface ====
234
235 To add images to the interface, attach them to the Skin document and use them in the CSS code. For example, if you want to use myimage.jpg as background image for the pages inside your XWiki instance, follow these steps:
236
237 * Attach the image to the Skin document
238 * Choose one of these actions:
239 ** Add a new CSS component to the Skin, name it pagebackground.css and add a reference to it from the style.css component
240 ** Override the mybaseskin.css component (where mybaseskin is the name of the current Skin - for example: albatross.css, toucan.css or colibri.css)
241 * Paste the following code inside the CSS component:(((
242 {{code language="css"}}
243 body{
244 background-image: url($xwiki.getSkinFile("myimage.jpg"));
245 }
246 {{/code}}
247 )))
248
249 Open any page in view mode and you will notice that the the background of the page contains your image. Have fun taking advantage of the power of XWiki Skins!
250
251 == More about XWiki Skins ==
252
253 In order to find more about XWiki Skins, check the [[Skins Tutorial>>xwiki:Documentation.AdminGuide.Skins]] from inside the Admin Guide and the [[Skins Tutorial>>xwiki:Documentation.UserGuide.Features.Skins]] from inside the User Guide
254
255 == Further reading ==
256
257 * the [[XWiki Data Model>>xwiki:Documentation.DevGuide.DataModel]]
258 * using the [[Skin Editor Application>>extensions:Extension.Skin Editor Application]]
259 * [[edit only one object>>dev:Drafts.EditOneObject]]
260 )))

Get Connected