Skins (XWiki.org)

1.1

13

A XWiki Skin is used to customize the interface of a XWiki Enterprise instance.

14

15

==What are the components that define a XWiki Skin?==

16

A XWiki Skin is composed of:

17

* (% class="sectionblockcodecolored"%)[[Velocity templates>>platform:DevGuide.Scripting#velocity]](%%)

18

* (% class="sectionblockcodecolored"%)[[{{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} stylesheets>>platform:AdminGuide.CSS files]](%%)

19

* (% class="sectionblockcodecolored"%)[[Javascript files>>platform:DevGuide.JavaScriptAPI]](%%) and

20

* (% class="sectionblockcodecolored"%)Images(%%)

21

22

All these components are stored on the server that hosts the XWiki Enterprise instance, inside the (% class="sectionblockcodecolored directory"%)webapps/xwiki(%%) folder.

23

{{id name="s3" /}} ==How to change the Skin== {{id name="3a" /}}===A. The default XWiki Skins===

24

A XWiki Enterprise instance contains by default a [[list of Skins>>code:Skins.WebHome]] like:

25

* the (% class="sectionblockcodecolored"%)[[albatross>>code:Skins.AlbatrossSkin]](%%) Skin

26

* the (% class="sectionblockcodecolored"%)[[toucan>>code:Skins.ToucanSkin]](%%) Skin

27

* the (% class="sectionblockcodecolored"%)[[colibri>>code:Skins.ColibriSkin]](%%) Skin and

28

* other skins ( the full list of XWiki Skins that are included in your XWiki Enterprise instance can be found on the server filesystem, inside the (% class="sectionblockcodecolored directory"%)webapps/xwiki/skins(%%) folder )

29

{{id name="3b" /}}===B. The usage level for a XWiki Skin===

30

A Skin can be used at different levels:

31

* for the entire XWiki Enterprise (% class="sectionblockcodecolored"%)instance(%%) ( if there is no Skin set other levels, the pages will use the global (% class="sectionblockcodecolored"%)instance(%%) Skin )

32

* for a (% class="sectionblockcodecolored"%)space(%%) inside the XWiki Enterprise instance ( it has a higher priority then the (% class="sectionblockcodecolored"%)instance(%%) level Skin )

33

* for a specific (% class="sectionblockcodecolored"%)user(%%) (it has a higher priority then the (% class="sectionblockcodecolored"%)space(%%) level Skin) and

34

* for other (% class="sectionblockcodecolored"%)custom(%%) levels that can be created by modifying the Velocity templates from inside the Skin ( for example, a Skin can be set for a specific page, for a specific group of users and so on )

35

{{id name="3c" /}} ===C. Changing the Skin===

36

37

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.

38

39

{{id name="3c1" /}}====1. How to preview a Skin applied on a page====

40

To check how a page looks on changing the Skin, you can add a parameter named (% class="sectionblockcodecolored"%)skin(%%) to the page URL. For example, to preview the wiki main page on using the (% class="sectionblockcodecolored"%)toucan(%%) Skin, use the following URL: http://localhost:8080/xwiki/bin/view/Main/WebHome/?skin=toucan . If you want to preview the page on using a Skin document named (% class="sectionblockcodecolored"%)MySpace.MySkinDoc(%%), use the following URL: http://localhost:8080/xwiki/bin/view/Main/WebHome/?skin=MySpace.MySkinDoc .

41

{{id name="3c2" /}}====2. Changing the Skin at (% class="sectionblockcodecolored"%)instance(%%) level====

42

Each XWiki Enterprise instance contains a document ( (% class="sectionblockcodecolored"%)Skin Document(%%) ) that stores the Skin for the instance. To find out which document is used to store the current Skin, the user has to follow these steps:

43

|(% style="width:60%;color:#222"%)(((

44

1. go into the (% class="sectionblockcodecolored"%)Administration(%%) interface

45

1. go into the (% class="sectionblockcodecolored"%)Presentation(%%) section

46

1. check the (% class="sectionblockcodecolored"%)Skin(%%) property that stores the full name of the document

47

)))|((([[[[image:1.png||width="100%" style="border:3px solid #ddd;"]]>>attach:1.png]])))

48

49

{{id name="3c2steps" /}}To change the current Skin, follow these steps:

50

|(% style="width:60%;color:#222"%)(((

51

(% start="4" %)

52

1. click on the (% class="sectionblockcodecolored"%)CUSTOMIZE(%%) button right beside the (% class="sectionblockcodecolored"%)Skin(%%) property, to open the document

53

1. click on the (% class="sectionblockcodecolored"%)Edit this skin(%%) button to edit the document, or go to the top menu and select (% class="sectionblockcodecolored"%)EDIT -> OBJECTS(%%)

54

1. change the (% class="sectionblockcodecolored"%)Skin(%%) property ( the property is set to (% class="sectionblockcodecolored"%)colibri(%%) by default ) with the name of another Skin ( for example, (% class="sectionblockcodecolored"%)albatross(%%) )

55

1. save the document

56

)))|((([[[[image:2.png||width="100%" style="border:3px solid #ddd;"]]>>attach:2.png]])))

57

58

You can now open any page inside the wiki instance and you will notice the layout difference.

59

{{id name="3c3" /}}====3. Changing the Skin at (% class="sectionblockcodecolored"%)space(%%) level====

60

A XWiki space can use it's own Skin. For example, if you want to set as Skin for the space (% class="sectionblockcodecolored"%)Main(%%) as being the (% class="sectionblockcodecolored"%)albatross(%%) Skin, follow these steps:

61

|(% style="width:60%;color:#222"%)(((

62

1. go on any page inside the (% class="sectionblockcodecolored"%)Main(%%) space ( for example, go on the home page: http://localhost:8080/xwiki/bin/view/Main/ )

63

1. from the top right menu, choose (% class="sectionblockcodecolored"%)Administration -> Administer space: Main(%%) to open the (% class="sectionblockcodecolored"%)Administration(%%) interface for the space (% class="sectionblockcodecolored"%)Main(%%)

64

1. go into the (% class="sectionblockcodecolored"%)Presentation(%%) section

65

1. follow the steps 4, 5, 6 and 7 from inside the section [[C-2>>#3c2]]

66

)))|((([[[[image:3.png||width="100%" style="border:3px solid #ddd;"]]>>attach:3.png]])))

67

68

You can now open any page inside the (% class="sectionblockcodecolored"%)Main(%%) space and you will notice the layout difference.

69

)))

70

{{id name="3c4" /}}====4. Changing the Skin at (% class="sectionblockcodecolored"%)user(%%) level====

71

For example, if you want to use the (% class="sectionblockcodecolored"%)toucan(%%) Skin for a specific (% class="sectionblockcodecolored"%)user(%%), follow these steps:

72

1. go to the user's (% class="sectionblockcodecolored"%)profile(%%) page

73

1. edit the document's objects ( if you are in edit mode, use the right panel and choose the (% class="sectionblockcodecolored"%)Objects(%%) editor, or, if you are in view mode, use the top-left menu: (% class="sectionblockcodecolored"%)EDIT -> OBJECTS(%%))

74

1. set the value of the (% class="sectionblockcodecolored"%)skin(%%) property as being (% class="sectionblockcodecolored"%)toucan(%%)

75

1. save the document

76

77

Now, all the pages inside the instance will have the (% class="sectionblockcodecolored"%)toucan(%%) Skin applied on them for that user.

78

79

{{id name="s4" /}}==How to create a new Skin==

80

81

To create a new Skin, you must have access to the server side of the XWiki Enterprise instance.

82

83

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:

84

1. inside the (% class="sectionblockcodecolored directory"%)webapps/xwiki/skins(%%) folder, create a folder named (% class="sectionblockcodecolored"%)myskin(%%)

85

1. change the Skin at (% class="sectionblockcodecolored"%)instance(%%) level and set it as (% class="sectionblockcodecolored"%)myskin(%%) ( see the section [[C-2>>#3c2]] for more informations about how to change the Skin )

86

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(%%) )

87

1. change the (% class="sectionblockcodecolored"%)global(%%) template:

88

1*. copy the (% class="sectionblockcodecolored directory"%)webapps/templates/global.vm(%%) template and paste it inside the (% class="sectionblockcodecolored"%)myskin(%%) folder

89

1*. to remove the logo, modify the (% class="sectionblockcodecolored"%)global(%%) template under the new Skin and delete the line:(% class="overflow-auto" %)((({{code language="xml"}}<img src="$!logourl" alt="XWiki" width="200" height="70"/>{{/code}} )))

90

1. save the template

91

92

Open any page in view mode and you will notice that the XWiki logo is not displayed anymore.

93

Congratulations! You have created a new minimal XWiki Skin.

94

95

{{id name="s5" /}}==How to override a Skin==

96

97

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.

98

99

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.

100

To override a Skin, you have to use the same document that is used to store the Skin.

101

{{id name="5a" /}}===A. Creating a Skin document===

102

{{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}}

103

To create a new Skin document, follow these steps:

104

|(% style="width:60%;color:#222"%)(((

105

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:

106

1*. go to (% class="sectionblockcodecolored"%)Administration -> Panel Wizard(%%)

107

1*. select the (% class="sectionblockcodecolored"%)Tools(%%) category

108

1*. add the (% class="sectionblockcodecolored"%)New Page(%%) panel on the interface by using drag&drop

109

1*. click on (% class="sectionblockcodecolored"%)Save the new layout(%%) to save your changes

110

1*. open any page in view mode and

111

1*. use the (% class="sectionblockcodecolored"%)New Page(%%) panel to create a page

112

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 -> OBJECTS(%%))

113

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(%%))

114

1. save the document

115

)))|((([[[[image:4.png||width="100%" style="border:3px solid #ddd;"]]>>attach:4.png]])))

116

117

{{id name="5b" /}}===B. Working with the (% class="sectionblockcodecolored"%)XWiki.XWikiSkins(%%) class===

118

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.

119

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.

120

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:

121

|(% style="width:60%;color:#222"%)(((

122

1. go to the (% class="sectionblockcodecolored"%)XWiki.XWikiSkins(%%) document

123

1. click on the (% class="sectionblockcodecolored"%)add or modify the class properties(%%) link

124

( or follow this link: http://localhost:8080/xwiki/bin/edit/XWiki/XWikiSkins?editor=class )

125

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(%%)

126

1. save the document

127

)))|((([[[[image:5.png||width="100%" style="border:3px solid #ddd;"]]>>attach:5.png]])))

128

129

{{id name="5c" /}}===C. Using a Skin document===

130

To use a Skin document, follow these steps:

131

1. go to the (% class="sectionblockcodecolored"%)Skin(%%) property from inside the (% class="sectionblockcodecolored"%)Administration(%%) interface

132

1. set the value of the property as being the full name of the Skin document

133

1. save the preferences

134

135

{{id name="5d" /}}===D. Overriding the Skin components===

136

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:

137

|(% style="width:60%;color:#222;overflow-x:auto;"%)(((

138

1. add a (% class="sectionblockcodecolored"%)TextArea(%%) property named (% class="sectionblockcodecolored"%)global.vm(%%) to the (% class="sectionblockcodecolored"%)XWiki.XWikiSkins(%%) class

139

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

140

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:

141

1*. http://localhost:8080/xwiki/skins/mybaseskin/global.vm ( where mybaseskin is the current Skin used in the Skin document ), or

142

1*. if the previous link is not valid, go to http://localhost:8080/xwiki/templates/global.vm

143

1. replace the following code: (% style="overflow-x:auto;" %)((({{code language="xml"}}<a class="glink"

144

href="$!xwiki.getURL($context.user, 'view')"

145

id="headeruser">

146

$!xwiki.getUserName($context.user, false)

147

</a>{{/code}})))with (% style="overflow-x:auto;" %)((({{code language="xml"}}<a class="glink"

148

href="$!xwiki.getURL($context.user, 'view')"

149

id="headeruser">

150

HELLO,

151

$!xwiki.getUserName($context.user, false)

152

</a>{{/code}})))

153

1. save the document

154

)))|((([[[[image:6.png||width="100%" style="border:3px solid #ddd;"]]>>attach:6.png]])))

155

156

Now, open any document in view mode and you will notice the nice "HELLO," before your username.

157

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 ).

158

159

{{id name="5e" /}}===E. Adding new components to the Skin===

160

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:

161

* attach the files to the Skin document and reffer them by their URL, or

162

* add new properties to the (% class="sectionblockcodecolored"%)XWiki.XWikiSkins(%%) object from inside the Skin document, and refer them by their name

163

164

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:

165

|(% style="width:60%;color:#222"%)(((

166

1. attach the {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} file to the Skin document

167

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:(% class="overflow-auto" %)((({{code language="xml"}}<link rel="stylesheet"

168

type="text/css"

169

href="$xwiki.getSkinFile('mynewfile.css')"

170

/>{{/code}})))

171

1. save the document

172

)))|((([[[[image:7.png||width="100%" style="border:3px solid #ddd;"]]>>attach:7.png]])))

173

174

OR

175

|(% style="width:60%;color:#222"%)(((

176

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

177

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:(% class="overflow-auto" %)((({{code language="css"}}@import "mynewfile.css";{{/code}} ))) 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

)))|((([[[[image:8.png||width="100%" style="border:3px solid #ddd;"]]>>attach:8.png]])))

180

181

Open any document in view mode and you will notice that the stylesheet is now applied.

182

183

{{id name="5f" /}}===F. Using (% class="sectionblockcodecolored"%)images(%%) in a Skin document==={{id name="5f1" /}}====1. Changing the (% class="sectionblockcodecolored"%)logo(%%)====

184

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:

185

1. attach the image to the Skin document

186

1. edit the document's objects ( use the top-left menu: (% class="sectionblockcodecolored"%)EDIT -> OBJECTS(%%) )

187

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(%%)

188

1. save the document

189

190

Open any page in view mode and you will notice that the logo is now changed.

191

192

193

====2. Adding images to the Skin interface====

194

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:

195

1. attach the image to the Skin document

196

1. choose one of these actions:

197

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 )

198

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(%%) )

199

1. paste the following code inside the {{html}}<acronym title="Cascading Style Sheets">CSS</acronym>{{/html}} component:(% class="codeblock overflow-auto addcode" %)((({{code language="css"}}body{

200

background-image: url($xwiki.getSkinFile("myimage.jpg"));

201

}{{/code}} )))

202

203

Open any page in view mode and you will notice that the the background of the page contains your image.

204

Have fun taking advantage of the power of XWiki Skins!

205

206

==Further reading==