XWiki Skins

How to create a new Skin

  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:

• 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.
• Change the Skin at global or instance level and set it as myskin ( see this page for more informations about how to change the Skin )
• 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)
• Change the global template:to remove the logo, modify the global.vm template under the new Skin and delete the line:
  <img src="$!logourl" alt="Wiki Logo"/>
• Save the template

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.

skin.properties

Since 6.4. Inside your new skin, you should have a file called skin.properties. This file contains some properties about the skin and looks like this:

How to override a Skin

  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.
  To override a Skin, you have to use the same document that is used to store the Skin.

A. Creating a Skin document

To create a new Skin document, follow these steps:

• Create a new page. Name it MySkinPage

  

• Edit the document's objects (Edit -> Objects)
• Add an object of type XWiki.XWikiSkins to the document
• Click on add
• 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.

  

• Save the document

B. Working with the XWiki.XWikiSkins class

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

• Go to the XWiki.XWikiSkins document
• Edit the document's class (Edit -> Class) or follow this link: http://localhost:8080/xwiki/bin/edit/XWiki/XWikiSkins?editor=class
• Add a new property myfile.vm as TextArea type
• Click on Add. The myfile.vm property should appear in the list

  

• Save the document

C. Using a Skin document

  To use a Skin document, follow these steps:

• Go to the skin property from inside the Administrationpage, Presentation section
• 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
• Save the preferences

D. Overriding the Skin components

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:

Method 1: By editing the XWiki.XWikiSkins properties on the Skin document

• Add a TextArea property named menuview.vm to the XWiki.XWikiSkins class

  

• Edit your skin document's objects (Edit -> Objects) and open the properties of the object
• 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/)
• Replace the following code:
   #xwikitopmenuentrystart($xwiki.getURL($xcontext.user, 'view') "$msg.get('core.menu.type.profile')__SEPARATOR__$!xwiki.getUserName($xcontext.user, false)" 'tmUser' 'hasIcon')

  with

    #xwikitopmenuentrystart($xwiki.getURL($xcontext.user, 'view') "$msg.get('Hello')__SEPARATOR__$!xwiki.getUserName($xcontext.user, false)" 'tmUser' 'hasIcon')
  

• Save the document

Method 2: By attaching files to the current Skin document

• 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
• Replace the following code:
   #xwikitopmenuentrystart($xwiki.getURL($xcontext.user, 'view') "$msg.get('core.menu.type.profile')__SEPARATOR__$!xwiki.getUserName($xcontext.user, false)" 'tmUser' 'hasIcon')

  with

    #xwikitopmenuentrystart($xwiki.getURL($xcontext.user, 'view') "$msg.get('Hello')__SEPARATOR__$!xwiki.getUserName($xcontext.user, false)" 'tmUser' 'hasIcon')
• Attach the copy of menuview.vm template to the current Skin document page

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

3. Overriding a skin resource

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

• Find the path on the filesystem of the resource to replace (you can easily obtain that information using development tools such as Firebug); for instance, let's say this path is either

/xwiki/resources/icons/silk/myicon.gif
for a resource found in the general resource directry, or
/xwiki/skins/colibri/myimage.png
if the resource is specific to a certain skin, in this case 'colibri'.

• 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 caseicons/silk/myicon.gif
  and in the second case simply
  myimage.png
• In this path, replace '/' with '.'; after this operation, we will get icons.silk.myicon.gif 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.
• Create a file named as explained above and attach it to your Skin

E. Adding new components to the Skin

  If you want to add new files to the skin, like CSS or Javascript files, you have two options:

• attach the files to the Skin document and reffer them by their URL, or
• add new properties to the XWiki.XWikiSkins object from inside the Skin document, and refer them by their name

  For example, if you want to add a new CSS  file to the Skin, named mynewfile.css, follow one of these set of steps:

• Attach the CSS file to the Skin document
• Override the stylesheets.vm template  and add the reference to your file in the template:
  <link rel="stylesheet"
    type="text/css"
    href="$xwiki.getSkinFile('mynewfile.css')"
  />
• Save the document