Skin Application

The Skin Application is bundled with XWiki Standard and for the moment it only allows to edit an existing skin. In future versions, the application will have features for creating and managing multiple skins.

Edit the Skin Page

As detailed in the "Flamingo Skin" documentation page, the default XWiki skin is Flamingo. To edit it, click the DrawerMenuIcon.png button which opens the drawer menu, then on "Administer Wiki".

AdministerWikiMenu.png

Next, click on "Look & Feel" -> "Themes" in the accordion menu on the left,

PresentationGlobalAdmin.png

then on the "Customize" button in the "Skin" section

CustomizeDefaultSkin.png

and finally on "Edit this skin", which will launch the default skin page in "Inline form" mode.

SkinPageInline.png

As shown in the "Base skin" input, the base skin is "flamingo" which is stored in the folder "/webapps/xwiki/skins/flamingo". In order to add a new logo, click on "Choose an attachment", select an image from your computer, then click on "Upload and Select".

UploadLogo.png

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

LogoUpdated.png

Note that 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, please refer to the Flamingo Color Theme Application documentation. 

The "Output Syntax" field has 2 options:

  • HTML 5 - recommended for new skins
  • XHTML 1.0 - added in order to keep backward compatibility with old skins like "colibri" and it is used by XWiki to know which renderer to use along with the skin. The renderer is important to generate valid HTML code.

Override Skin Resources

Skin resources are Velocity, JavaScript, CSS and LESS files located in the "/webapps/xwiki/templates/" folder or in the current skin folder "/webapps/xwiki/skins/flamingo/". The main CSS file is "style.css", whereas the main LESS file is "less/style.less.vm".

In case you need to replace a JavaScript resource, an image or even fonts, the best way is to attach it to the skin page, then to refer it using a Skin extension. More details are available in the "Skins extensions" tutorial linked under "Related Pages".

To customize for instance the "pdfcover.vm" template, enter the string pdfcover.vm in the input field under "Overridden templates", then click on "Add". You will then notice 2 new fields:

  • Path - representing the template name; this one is automatically filled and it should not be modified
  • Content - this is where you add the template Velocity code

What you will have to do first is to paste the default code into the "Content" field which is:

<div style="text-align: center; width: 100%;">
<h1>
#set ($title = "$!pdfdoc.display('title', 'rendered', '', $pdfobj)")
#if ($title == '')
  $escapetool.xml($!tdoc.plainTitle)
#else
  $escapetool.xml($title)
#end
</h1>
</div>

To display for instance the company logo on the PDF cover page, add the line <img src="$xwiki.getSkinFile("Telegram_logo_scaled.png")"/> right before the default code.

PDFCoverTemplate.png

Don't forget to hit "Save & View" in order to submit your changes. If you then export a wiki page as PDF, the cover page should look like in the screen-shot below.

PDFExportResult.png

For the moment the UI doesn't support overriding the default "style.css" file using the aforementioned method. As a workaround, you can click on "Deprecated properties" and enter the custom CSS in the "Style" field or follow the instructions from the next section.

OverrideDefaultStylesheet.png

Override the Stylesheets

The default or preferred stylesheet of the skin is named "style.css". To override it, you have two possibilities: the easiest one is to add your rules to the "/webapps/xwiki/skins/flamingo/style.css" file, then attach it to the skin page. However, this method is not recommended because it will be quite hard to keep track of the subsequent changes history and make comparisons . 

This is why you should edit the skin page in "Objects" mode and locate the "Style" property in the "XWiki.XWikiSkins" object which by default is empty.

StyleProperty.png

Before adding your own CSS rules that will override the default implementation, you first need to load the main CSS file of the current flamingo skin by pasting the below lines.

## 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

For more details about skin customization, refer to the "Create and Override a Skin" page linked under "Related Pages". Also, if you are familiar with LESS, feel free to extend the .less files of the skin, according to the principles presented in the "LESS Module" documentation, linked in the "Related Pages".

      

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]