XWiki Standard 9.8.1 Documentation » Programming Overview » Create and Override a Skin

Create and Override a Skin

Customize a Skin Located on the Filesystem

If the skin is stored on the filesystem, all your changes must be done in the skin folder which is located under "/xwiki/skins".

Create a Skin Document

To create a new Skin document, edit a wiki page in "Objects" mode, choose the "XWiki.XWikiSkins" class from the drop-down list near "New object", then click the "Add" button.

XWikiSkinsObject.png

The XWiki.XWikiSkins Class

The base element in overriding a skin is the "XWiki.XWikiSkins" class. By default, the skin class contains a set of properties allowing you to override some of the templates and files used by the skin and also to change the logo displayed in the header. 

XWikiSkinsClass.png

Properties

  • "name" represents the pretty name of the skin
  • "baseskin" is the base skin overridden by the custom skin; the default value is "colibri"
  • "style.css" is the preferred or default stylesheet of the skin
  • "header.vm" corresponds to the "/webapps/xwiki/templates/header.vm" template which defines the document headers
  • "footer.vm" corresponds to the "/webapps/xwiki/templates/footer.vm" template which defines the document footers
  • "viewheader.vm" corresponds to the "/webapps/xwiki/templates/viewheader.vm" template which defines the document headers in view mode: the language bar, the document information bar, the "More Actions" menu etc.
  • "view.vm" corresponds to the "/webapps/xwiki/templates/view.vm" template which is the general wrapper for view actions
  • "edit.vm" corresponds to the "/webapps/xwiki/templates/edit.vm" template which is the general wrapper for edit actions

To learn how to override the skin templates (like PDF templates) follow this link.

Set the Wiki Default Skin

The skin used by the wiki is defined in the wiki preferences page. To access it, click the "Home" menu, then click on "Administer Wiki". In the wiki administration page, click on the "Presentation" link from the vertical menu to the left.

PresentationLinkAdmin.png

In order to use your custom skin, enter its full name in the "Skin" input then click on the "Save" button. In case the skin is stored on the filesystem, in the "/webapps/xwiki/skins/" folder, you will have to use the skin folder name, like for instance "testskin" .

ChangeDefaultAdmin.png

Another way of doing this is by editing the wiki administration page in "Objects" mode (/xwiki/bin/edit/XWiki/XWikiPreferences?editor=object). Next, enter the full name of the skin document in the "Skin" property of the "XWiki.XWikiPreferences" object.

SkinProperty.png

If the skin is located on the filesystem, just enter the name of the folder that stores it, for instance colibrienhanced.

Create Alternate Stylesheets

The default or preferred stylesheet of the skin is "style.css" and it can be set in the "Stylesheet" field of the "Presentation" section.

DefaultStyleSheet.png

You may also use a number of mutually exclusive alternate stylesheets that you will specify in the "Stylesheets" field.

To create an alternate stylesheet, follow these steps:

  • Add a new "TextArea" property to the "XWiki.XWikiSkins" class and name it mynewstylesheet.css
  • Paste your custom CSS code into the mynewstylesheet.css property 
  • Enter the value "mynewstylesheet.css" in the "Stylesheets" field

Override the Preferred Stylesheet

In order to override the default stylesheet, style.css, follow these steps:

  • Add a new "TextArea" property to the "XWiki.XWikiSkins" class and name it mynewstylesheet.css
  • Paste your custom CSS code into the mynewstylesheet.css property 
  • Enter the value "mynewstylesheet.css" in the "Stylesheet" field
  • Override the style.css property of the "XWiki.XWikiSkins" class and add the following code:
@import "mynewfile.css";
  • Create a file named "mynewfile.css" in your skin folder and add your custom CSS code to it

The important thing is to add a reference to the new component from an existing one.

Customize the Skin Page

To customize the skin page, go to the "Presentation" section of the wiki administration page and click on the "Customize" button next to the "Skin" property. In the skin page, click on "Edit this skin" which will open the document in "Inline" mode.

EditSkin.png

Override the Skin Templates

Skin resources include the .vm files located in the "/webapps/xwiki/templates/" folder or in the current skin folder:

  • /webapps/xwiki/skins/colibri/ OR
  • /webapps/xwiki/skins/flamingo/

One way of overriding a resource is to extend the "XWiki.XWikiSkins" class by adding a TextArea property with the name of the .vm file. Next, edit the wiki default skin in "Inline" mode and copy the default content of the file you wish to override i.e. the content of the file located on your server. Finally, after you are done with the modifications, just click on "Save & View".

Customize the "Style" Property

Before adding your own CSS rules that will override the default implementation, you first need to load the "style.css" file of the current skin. So, if the base skin is "colibri" just add the following lines in the "Style" input before the custom CSS rules:

@import "$xwiki.getSkinFile('css/microformats.css')";
########################################################
### Import the colibri CSS file with good parameters
########################################################
## 1. Get the parameters
#set ($urlParametersMap = {})
#if ($request.colorTheme)
  #set ($discard = $urlParametersMap.put("colorTheme", "$!request.colorTheme"))
#end
#if ($request.skin)
  #set ($discard = $urlParametersMap.put("skin", "$!request.skin"))
#end
#set ($urlParameters = $escapetool.url($urlParametersMap))
## 2. Import colibri.css
@import "$xwiki.getSkinFile('colibri.css', true)#if (!$urlParametersMap.isEmpty())?${urlParameters}#end";

If the base skin is "flamingo", just add:

## Get the compiled LESS code
#set($css = $services.lesscss.compileSkinFile('style.less.vm'))
## Remove the useless part
#set($index = $css.indexOf('.not-sent-to-the-browser-from-this-point'))
#if($index >= 0)
 #set($css = $css.substring(0, $index))
#end
## Remove from the CSS some rules that make IE9 crash using the WYSIWYG (XWIKI-10661)
## Only if the user agent contains the IE9 signature
## @TODO: Remove this when IE9 will no longer be supported.
#if($request.getHeader('User-Agent').contains('MSIE 9.0'))
 ## We removes css rules like ".className:empty{...}"
 ## "(?s)" means that the expression "." matches any character, including a line terminator
 #set($css = $css.replaceAll('(?s)\.[^\{]*:empty\{[^\}]*\}', ''))
#end
## Display the CSS
$!css

The second way is to attach the modified CSS or the .vm file to the default skin page. This method could seem easier because it doesn't require adding properties to the "XWiki.XWikiSkins" class.

In order to add  newlogo.jpg as logo for the current Skin follow these steps:

  • Edit the skin page in "Inline form" mode
  • Click on "Choose an Attachment".

SkinLogo.png

  • Select newlogo.jpg then click on "Upload and Select".

UploadLogo.png

You will then see the new logo in "Inline form" mode.

LogoInline.png

By default, the displayed logo is the one defined in the color theme page used by the wiki. When the logo is not defined in the color theme, XWiki will display the one attached to the skin file. The reason for this is to allow you to have a different logo for each color theme. For more information, go to the documentation page about how to change the Color Theme logo. 

      

Related Pages

Search this space

 

Most popular tags

Failed to execute the [groovy] macro
  1. access rights
  2. activity stream
  3. annotation
  4. attachment
  5. comment
  6. Document Tree Macro
  7. export
  8. Extension Manager
  9. Flamingo skin
  10. global user
  11. Groovy event listener
  12. group
  13. nested page
  14. search
  15. skin
  16. syntax
  17. user
  18. user profile
  19. velocity macros
  20. wiki
  21. wysiwyg
  22. XWiki Applications
  23. xwikiattachment_archive table
  24. xwikiattachment table
  25. xwikiattrecyclebin table
  26. xwikiproperties table

[Display all tags from this space]