Wiki source code of Skin
Version 8.2 by Sergiu Dumitriu on 2009/11/06
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | #startfloatingbox() | ||
| 2 | *Contents* | ||
| 3 | #toc ("2" "3" "") | ||
| 4 | #endfloatingbox() | ||
| 5 | |||
| 6 | To just change the color of the Toucan skin, take a look [here>http://code.xwiki.org/xwiki/bin/view/Skins/ToucanSkin]. | ||
| 7 | |||
| 8 | 1 Skins | ||
| 9 | |||
| 10 | A skin is a set of images, [CSS files], [a layout>CSS Layout] and XWiki templates allowing to change the layout of the wiki. | ||
| 11 | |||
| 12 | A skin is usually developped by administrators and graphics designers and can be used to change the look of a XWiki installation for: | ||
| 13 | - one page | ||
| 14 | - one user | ||
| 15 | - one [space>xwiki:FAQ.WhatIsASpace] | ||
| 16 | - the whole wiki | ||
| 17 | |||
| 18 | A skin can have multiple Stylesheets which are switchable by the users and can stay active using a cookie. | ||
| 19 | |||
| 20 | 1.1 Changing the skin | ||
| 21 | |||
| 22 | There are several levels and ways to change the skin. Here's the order in which XWiki looks for a skin: | ||
| 23 | # 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 220 pix wide, and 80 pix high (else the logo will look bad). For example: call the file "mylogo220x80.gif". | ||
| 45 | *** There are no size constraints for the *Colibri* skin, the header will automatically adjust to the height of the image. | ||
| 46 | ** Click to edit this skin, and in the "objects" editor you will find an object XWiki.XWikiSkins. | ||
| 47 | ** Alter the XWiki.XWikiSkins object so that the "logo" property says: <tt>mylogo200x70.gif</tt> or <tt>mylogo220x80.gif</tt> (or what ever you chose to call the file name above) | ||
| 48 | |||
| 49 | #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).") | ||
| 50 | |||
| 51 | 1.1 Creating a skin | ||
| 52 | |||
| 53 | To create a skin, you need to have notions of one or more of: | ||
| 54 | * XHTML | ||
| 55 | * CSS (Cascading Style Sheets) | ||
| 56 | * [Velocity Templates>http://velocity.apache.org/engine/releases/velocity-1.5/user-guide.html] | ||
| 57 | * [The XWiki API>http://build.xpertnet.biz/doc/api/com/xpn/xwiki/api/package-summary.html] | ||
| 58 | |||
| 59 | With a skin, you can change (and therefore break) the layout of *everything* in XWiki. | ||
| 60 | |||
| 61 | 1.1.1 Modifying a skin | ||
| 62 | |||
| 63 | Usually you just want to change the basic layout of XWiki, and therefore you need to modify: | ||
| 64 | |||
| 65 | * the main styles file: style.css | ||
| 66 | * the header template: header.vm | ||
| 67 | * the footer template: footer.vm | ||
| 68 | * the main logo | ||
| 69 | |||
| 70 | To do this you need to: | ||
| 71 | |||
| 72 | * 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. | ||
| 73 | * Create an empty page | ||
| 74 | * Attach any images needed in the skin to this page | ||
| 75 | * Select "Edit Objects" in the Edit menu | ||
| 76 | * Add the objects from the class "XWiki.XWikiSkins" | ||
| 77 | * Modify the style.css (overriding standard rules) | ||
| 78 | * Modify header.vm and footer.vm content | ||
| 79 | |||
| 80 | You will find the original content at: | ||
| 81 | |||
| 82 | * 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). | ||
| 83 | |||
| 84 | To start, the best is to copy-paste the original content and make a slight modification. | ||
| 85 | |||
| 86 | 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. | ||
| 87 | |||
| 88 | 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) | ||
| 89 | |||
| 90 | 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 | ||
| 91 | |||
| 92 | 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) | ||
| 93 | |||
| 94 | 1.1.1 Creating a whole new skin | ||
| 95 | |||
| 96 | 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: | ||
| 97 | * view.vm | ||
| 98 | * edit.vm | ||
| 99 | * preview.vm | ||
| 100 | * save.vm | ||
| 101 | |||
| 102 | You can then create as many subtemplates as you want and call them from these main templates. | ||
| 103 | |||
| 104 | 1.1 Useful tools | ||
| 105 | |||
| 106 | * [Firebug>http://www.getfirebug.com/] is very useful for customizing quickly an XWiki skin | ||
| 107 | * On a Mac with OS X and Safari 4 the Web Console works similar to Firebug but it seems to be more precise when highlighting the space allocated by an element. |
