Skins

Version 8.1 by Raluca Stavro on 2009/12/09
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.Tutorials.Skins.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

XWiki Skins

XWiki Skin used for?

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

What are the components that define a XWiki Skin?

  A XWiki Skin is composed of:

  All these components are stored on the server that hosts the XWiki Enterprise instance, inside the webapps/xwiki folder.
==How to change the Skin== ===A. The default XWiki Skins===
  A XWiki Enterprise instance contains by default a list of Skins like: 

  • the albatross Skin
  • the toucan Skin
  • the colibri Skin and
  • 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 webapps/xwiki/skins folder )
     ===B. The usage level for a XWiki Skin===
      A Skin can be used at different levels:
  • for the entire XWiki Enterprise instance ( if there is no Skin set other levels, the pages will use the global instance Skin )
  • for a space inside the XWiki Enterprise instance ( it has a higher priority then the instance level Skin )
  • for a specific user (it has a higher priority then the space level Skin) and
  • for other 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 )
    ===C. Changing the Skin===
    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.
    ====1. How to preview a Skin  applied on a page====
        To check how a page looks on changing the Skin, you can add a parameter named skin to the page URL. For example, to preview the wiki main page on using the 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 MySpace.MySkinDoc, use the following URL: http://localhost:8080/xwiki/bin/view/Main/WebHome/?skin=MySpace.MySkinDoc .
    ====2. Changing the Skin at instance level====
        Each XWiki Enterprise instance contains a document ( 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:
  1. go into the Administration interface
  2. go into the Presentation section
  3. check the Skin property that stores the full name of the document

1.png

To change the current Skin, follow these steps:

      

  1. click on the CUSTOMIZE button right beside the Skin property, to open the document
  2. click on the Edit this skin button to edit the document, or go to the top menu and select EDIT -> OBJECTS
  3. change the Skin property ( the property is set to colibri by default ) with the name of another Skin ( for example, albatross )
  4. save the document

2.png

    You can now open any page inside the wiki instance and you will notice the layout difference.
====3. Changing the Skin at space level====
    A XWiki space can use it's own Skin. For example, if you want to set as Skin for the space Main as being the albatross Skin, follow these steps:

  1. go on any page inside the Main space ( for example, go on the home page: http://localhost:8080/xwiki/bin/view/Main/ )
  2. from the top right menu, choose Administration -> Administer space: Main to open the Administration interface for the space Main
  3. go into the Presentation section
  4. follow the steps 4, 5, 6 and 7 from inside the section C-2

3.png

    You can now open any page inside the Main space and you will notice the layout difference.
  )))
====4. Changing the Skin at user level====
  For example, if you want to use the toucan Skin for a specific user, follow these steps:

  1. go to the user's profile page
  2. edit the document's objects ( if you are in edit mode, use the right panel and choose the Objects editor, or, if you are in view mode, use the top-left menu: EDIT -> OBJECTS)
  3. set the value of the skin property as being toucan
  4. save the document

  Now, all the pages inside the instance will have the toucan Skin applied on them for that user.
 
==How to create a new Skin==
To create a new Skin, you must have access to the server side of the XWiki Enterprise instance.
  To create a new Skin, you have to create a new direcory 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:

  1. inside the webapps/xwiki/skins folder, create a folder named myskin
  2. change the Skin at instance level and set it as myskin ( see the section C-2 for more informations about how to change the Skin )
  3. open any page in view mode and you will notice that myskin layout is the same as the albatross layout ( this happens because on having no Skin set as the Skin, the default Skin is considered to be albatross )
  4. change the global template:
    • copy the webapps/templates/global.vm template and paste it inside the myskin folder
    • to remove the logo, modify the global template under the new Skin and delete the line:
      <img src="$!logourl" alt="XWiki" width="200" height="70"/>
  5. 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.

==How to override a Skin==
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.
  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===
You need to have the advance edition mode activated to access the object editor. Please refer to PageEditing for more information.
To create a new Skin document, follow these steps:

  1. create a new page - if there is the option CREATE -> PAGE on the main menu, use it to create a page, or, if there is no such option, add the New Page panel on the interface by following these steps:
    • go to Administration -> Panel Wizard
    • select the Tools category
    • add the New Page panel on the interface by using drag&drop
    • click on Save the new layout to save your changes
    • open any page in view mode and 
    • use the New Page panel to create a page
  2. edit the document's objects ( if you are in edit mode, use the right panel and choose the Objects editor, or, if you are in view mode, use the top-left menu: EDIT&nbsp;->&nbsp;OBJECTS)
  3. add an object of type XWiki.XWikiSkins to the document (use the ADD OBJECT panel from the right and select the XWiki.XWikiSkins class, then click on ADD OBJECT FROM THIS CLASS)
  4. save the document

4.png

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

  1. go to the XWiki.XWikiSkins document
  2. click on the add or modify the class properties link
           ( or follow this link: http://localhost:8080/xwiki/bin/edit/XWiki/XWikiSkins?editor=class )
  3. from the ADD PROPERTY panel in the right, set the name of the property as being myfile.vm, choose the TextArea type, and click on Add
  4. save the document

5.png

  ===C. Using a Skin document===
  To use a Skin document, follow these steps:

  1. go to the Skin property from inside the Administration interface
  2. set the value of the property as being the full name of the Skin document
  3. 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 global.vm template on the server, but overriding it inside the Skin document. Follow these steps:
  1. add a TextArea property named global.vm to the XWiki.XWikiSkins class
  2. edit the Skin document's objects ( use the top-left menu: EDIT -> OBJECTS ) and open the properties of the XWiki.XWikiSkins object
  3. copy the original content of the global.vm template and paste it in the property field named global.vm; if you don't have access to the server filesystem, open the template by following one of these links:
  4. replace the following code:
    <a class="glink"
      href="$!xwiki.getURL($context.user, 'view')"
      id="headeruser">
          $!xwiki.getUserName($context.user, false)
    </a>
    with
    <a class="glink"
      href="$!xwiki.getURL($context.user, 'view')"
      id="headeruser">
          HELLO,
          $!xwiki.getUserName($context.user, false)
    </a>
  5. save the document

6.png

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

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

  1. attach the CSS  file to the Skin document
  2. override the stylesheets.vm template ( check the section D to learn how to override a Skin component ), and add the reference to your file in the template:
    <link rel="stylesheet"
      type="text/css"
      href="$xwiki.getSkinFile('mynewfile.css')"
    />
  3. save the document

7.png

  OR

  1. add a new property to the XWiki.XWikiSkins, name it mynewfile.css ( check the section B for more information about how to work with this class ), edit the Skin document's objects ( use the top-left menu: EDIT -> OBJECTS ), and paste the CSS  code into the mynewfile.css field
  2. override the style.css component ( see the section D for more information about how to override a Skin compoment ) and add the following line to the content of the style.css property:
    @import "mynewfile.css";
    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
  3. save the document

8.png

  Open any document in view mode and you will notice that the stylesheet is now applied.
 
 ===F. Using images in a Skin document=======1. Changing the logo====
    For example, if you want to add an image named myimage.jpg as being the logo for the current Skin, follow these steps:

  1. attach the image to the Skin document
  2. edit the document's objects ( use the top-left menu: EDIT -> OBJECTS )
  3. use the XWiki.XWikiSkins object and set the Logo property as being the name of the attached filename myimage.jpg
  4. save the document

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

    

2. Adding images to the Skin interface

    To add images to the interface, attach them to the Skin document and use them in the CSS  code. For example, if you want to use myimage.jpg as background image for the pages inside your XWiki Enterprise instance, follow these steps:

  1. attach the image to the Skin document
  2. choose one of these actions:
    • add a new CSS  component to the Skin, name it pagebackground.css and add a reference to it from the style.css component ( see the section E for more information about how to add new components to the Skin )
    • override the mybaseskin.css component ( where mybaseskin is the name of the current Skin - for example: albatross.css, toucan.css or colibri.css )
  3. paste the following code inside the CSS  component:
    body{
     background-image: url($xwiki.getSkinFile("myimage.jpg"));
    }

  Open any page in view mode and you will notice that the the background of the page contains your image.      
  Have fun taking advantage of the power of XWiki Skins!

Further reading

Tags:
   

Get Connected