Skins

Contents

• Changing the skin
• Changing the logo for the Albatross/Toucan skins
• Creating a skin
  • Modifying a skin
  • Creating a whole new skin
• Useful tools

To just change the color of the Toucan skin, take a look here.

Skins

A skin is a set of images, CSS files, a layout and XWiki templates allowing to change the layout of the wiki.

A skin is usually developped by administrators and graphics designers and can be used to change the look of a XWiki installation for:

• one page
• one user
• one space
• the whole wiki

A skin can have multiple Stylesheets which are switchable by the users and can stay active using a cookie.

Changing the skin

There are several levels and ways to change the skin. Here's the order in which XWiki looks for a skin:

1. 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".
2. 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
3. Then the Space preferences are checked for a "skin" element. This can be changed by using the "Administration" link.
4. 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.)
5. Then the default base skin name is used if defined. It's defined in xwiki.cfg under the xwiki.defaultbaseskin property.
6. Then the default skin is used if defined. It's defined in xwiki.cfg under the xwiki.defaultskin property.
7. Then the skin named "default" is used. This is skin on the file system in the XWiki webapp, in the skins/ directory

Changing the logo for the Albatross/Toucan skins

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:

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

or

• 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
  • Find the /xwiki/bin/view/XWiki/DefaultSkin page.
  • Attach an image file, the size depends on the skin selected
    • 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".
    • 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".
  • Click to edit this skin, and in the "objects" editor you will find an object XWiki.XWikiSkins.
  • 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)

Creating a skin

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

• XHTML
• CSS (Cascading Style Sheets)
• Velocity Templates
• The XWiki API

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

Modifying a skin

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

• the main styles file: style.css
• the header template: header.vm
• the footer template: footer.vm
• the main logo

To do this you need to:

• 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.
• Create an empty page
• Attach any images needed in the skin to this page
• Select "Edit Objects" in the Edit menu
• Add the objects from the class "XWiki.XWikiSkins"
• Modify the style.css (overriding standard rules)
• Modify header.vm and footer.vm content

You will find the original content at:

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

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

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.

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)

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

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)

Creating a whole new skin

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.

Useful tools

• Firefbug is very useful for customizing quickly an XWiki skin