Skin (XWiki.org)

# First XWiki checks if the request has a "skin" parameter. Thus to quickly apply a skin to a page, append ~~?skin=\<skin name\>~~ to the end of a XWiki URL. The default skin is named "default".

24

# Then the user's preference is checked for a "skin" element. This allows to have a different skin per user. Right now there's no inline view for that element so you'll need to edit your user's profile in "Edit Objects" mode (only available when using the Advanced View). For example to edit the objects for the JohnSmith user you would use the following URL: ~~http://\<server\>/xwiki/bin/edit/XWiki/JohnSmith?editor=object~~

25

# Then the Space preferences are checked for a "skin" element. This can be changed by using the "Administration" link.

26

# Then the global preferences are checked for a "skin" element. This can be changed by using the "Administration" link. Simply replace XWiki.DefaultSkin with the name of the skin you wish to use. If your skin is in your /skins directory, simply type its name in the field ("toucan" or "albatross" for instance.)

27

# Then the default base skin name is used if defined. It's defined in ~~xwiki.cfg~~ under the ~~xwiki.defaultbaseskin~~ property.

28

# Then the default skin is used if defined. It's defined in ~~xwiki.cfg~~ under the ~~xwiki.defaultskin~~ property.

29

# Then the skin named "default" is used. This is skin on the file system in the XWiki webapp, in the ~~skins/~~ directory

30

31

#info("The Default Base Skin is the skin used when you create a new skin using the XWiki.XWikiSkins objects (as explained below) and when you don't specify the 'base skin' field.")

32

33

1.1 Changing the logo for the Albatross/Toucan skins

34

35

By default the Albatross/Toucan skins look for a ~~logo.png~~ file either attached to your skin page (as an attachment) or in your skin directory (in \webapp\/skins/\). Thus there are 2 options for changing the logo:

36

37

* Replace the content of the logo.png file on the filesystem with your own logo. You'll need to have admin access to the XWiki server machine and stop/restart it.

38

*or*

39

* Create a new skin that inherits from the skin you wish to use, attach a logo file to edit and edit the logo property to point to, as described below

40

41

** Find the /xwiki/bin/view/XWiki/DefaultSkin page.

42

** Attach an image file, the size depends on the skin selected

43

*** If using the *Albatross* skin, the image file must be exactly 200 pix wide, and 70 pix high (else the logo will look bad). For example: call the file "mylogo200x70.gif".

44

*** If using the *Toucan* skin, the image file must be exactly 300 pix wide, and 100 pix high (else the logo will look bad). For example: call the file "mylogo300x100.gif".

45

** Click to edit this skin, and in the "objects" editor you will find an object XWiki.XWikiSkins.

46

** Alter the XWiki.XWikiSkins object so that the "logo" property says: mylogo200x70.gif or mylogo300x100.gif (or what ever you chose to call the file name above)

47

48

#info("If you're using an old XWiki.XWikiSkins page it may not have the logo property. In that case, create it by editing the XWiki.XWikiSkins class using the class editor (either by going to that page and choosing Edit > Class or by using the xwiki/bin/edit/XWiki/XWikiSkins?editor=class URL directly).")

1.1 Creating a skin

To create a skin, you need to have notions of one or more of:

53

* XHTML

54

* CSS (Cascading Style Sheets)

55

* [Velocity Templates>http://velocity.apache.org/engine/releases/velocity-1.5/user-guide.html]

56

* [The XWiki API>http://build.xpertnet.biz/doc/api/com/xpn/xwiki/api/package-summary.html]

57

58

With a skin, you can change (and therefore break) the layout of *everything* in XWiki.

59

60

1.1.1 Modifying a skin

61

62

Usually you just want to change the basic layout of XWiki, and therefore you need to modify:

63

64

* the main styles file: style.css

65

* the header template: header.vm

66

* the footer template: footer.vm

67

* the main logo

68

69

To do this you need to:

70

71

* Be using the Advanced mode if you're using XWiki 1.0 (beta1, beta2, etc). You'll need this to see the advanced edition menus. This entails going to your profile page and switching to the advanced mode.

72

* Create an empty page

73

* Attach any images needed in the skin to this page

74

* Select "Edit Objects" in the Edit menu

75

* Add the objects from the class "XWiki.XWikiSkins"

76

* Modify the style.css (overriding standard rules)

77

* Modify header.vm and footer.vm content

78

79

You will find the original content at:

80

81

* XWiki 1.0 files and templates can be found in your local XWiki installation (http://\<yourserver\>/xwiki/skins/xwiki10b1/ for XWiki 1.0 Beta 5 and before and http://\<yourserver\>/xwiki/skins/albatross/ for XWiki 1.0 Beta 6 and after).

82

83

To start, the best is to copy-paste the original content and make a slight modification.

84

85

If you want to derive your skin from another skin, you should write the name of the skin to derive in the "baseskin" textfield at the bottom of the page.

86

87

It is possible to modify the other templates. To do so you need to edit the XWiki.XWikiSkins class using the Class Editor (http://\<yourserver\>/xwiki/bin/edit/XWiki/XWikiSkins?xpage=editclass) and add a TextArea field that has the name of the template (for instance if you want to modify viewheader.vm which takes care of the action bar at the top, you need to create a TextArea field named viewheader.vm)

88

89

Once you have make some modifications, you can test your skin by adding the "skin=Main.MySkinPage" at the end of the URL. For example if you are creating a skin on \<yourserver\>, you can test the skin on the Home Page at http://\<yourserver\>/xwiki/bin/view/Main/WebHome?skin=Main.MySkinPage

90

91

Finally, when you are really happy with your skin, you can apply the skin to the whole wiki or to a space by modifying the "skin" field in the XWiki or Web Preferences. You should also modify the default and alternative styles (If you haven't created alternative styles, put 'style.css' in both fields)

92

93

1.1.1 Creating a whole new skin

94

95

If you want to really create a whole new skin, there are four templates that are needed, each corresponding to a different action as displayed in the URL:

* view.vm

* edit.vm

* preview.vm

* save.vm

You can then create as many subtemplates as you want and call them from these main templates.

102