Track: Styling XWiki

Last modified by Alex Cotiugă on 2023/08/24 11:45

So you want to change the styling of your wiki, application or page. Welcome to the Styling Track.

Task 1: Small interface changes (Skin Extensions)

Depending on how generic or specific you want to make your change, there are certain mechanisms that can be used. Sometimes you want a change to be applied just for a page, sometimes for all the pages. For example, create a new page that contains a table with some data in it. You want to have a red background for an important column or cell. For this case you should use a StyleSheet Skin Extension, usually referred as a SSX, that you can add to that particular page. 

Task 1.1: Using CSS

For this task you should write some CSS that changes the background color of your table cells to the color red, following the Skin Extensions Tutorial.

Task 1.2: Using LESS

XWiki has support for the LESS preprocessor. This could help you use advanced functions on top of CSS. Use LESS in your SSX and make the background be a pinkish color.

Task 1.3: SSX visibility

By default the SSX objects come with the "On this page or on demand" visibility set. This means that their effect is localised only on the pages that call this skin extension or on this page that contains the object. 

Play a bit with the "Use this extension" property values to see it in action: apply your changes just for a page, then apply them for the wiki. SSXs should be used when you want to target specific pages or applications. Even though you could use SSXs, if you want to make more complex / global / wiki changes you should use the Skin mechanism that we will try in another task.

Task 1.4: Using Velocity

You've learned about our Scripting languages in a previous Track. In case you want to add conditions, make your styling rules more dynamic or use XWiki API, you can combine Velocity with CSS / LESS. For that you will need to set the SSX's "Parse content" property to "YES". See an example.

For this task you should write a condition that will display the written CSS / LESS only for your user.

Bonus Task: Using JavaScript

If you want to add custom JavaScript to your page you can use JavaScript Skin Extensions, usually referred as a JSX. JSXs can also be parsed, so you can combine Velocity with your JavaScript.

Task 2: Reusing colors (Color Themes)

XWiki supports multiple Color Themes that allows rapidly changing the look & feel of your wiki. You can play with the bundled themes, install new ones contributed by our community or create your own. Color Themes preserve the global layout and bring small changes to the interface, like headings size, new fonts, different colors for buttons, links, etc.

Task 2.1: Changing the current color theme

Play a bit changing the Color Themes and find a new one that you like.

Task 2.2: Creating a new color theme

It is a good exercise to create a new color theme in order to see exactly what you can customize.

Task 2.3: Using advanced variables

The Color Theme interface allows you to change the most common variables, but there are even more variables that you could change. You can manually modify the variables or add more CSS / LESS code from the "Advanced" section.

In this task you should change the border color to be red, by using an existing variable name.

Task 2.4: Reusing existing color variables

You can see that in order to have a consistent user experience, we are reusing the same color in the interface. We apply the same principles for margins, font-sizes, etc. 

Remember the red background color you've used in the first task? Find a suitable variable to reuse for that value. 

Note: You should take a look at @brand-* or $theme.notification* variables. Not sure what you need? Depending on where your code is (in a SSX, Skin or in a LESS file) you can use the old Color Themes variables (needs Velocity to be parsed) or the Flamingo Theme variables (needs LESS to be compiled).

Task 3: Reusing icons (Icon Themes)

Similar to colors, XWiki provides an Icon Themes mechanism to easily change the icons set used.

Task 3.1: Changing the current color theme

Change the Icon Themes from Administration and see what icons it affects.

Task 3.2: Reusing existing icon variables

In this task you should add an icon that suggest importance to your table cell that you've marked with the red background. Search for the icon in the icon set mapping list or in the Icon Theme definition.

Task 4: Complex interface changes (Skins)

SSXs are used to add styling to your applications or modify the look of individual pages. If you want to radically change the interface of your XWiki instance, you should use the Skin mechanism.

A Skin defines a base CSS that could be build with the LESS preprocessor and a set of Velocity templates. It can also provide its own JavaScript files or images.

You can read more details about Skins

The default skins are defined on the filesystem, and they could be overridden and inherited by other filesystem skins, or by skins defined in a wiki document.

For the purpose of this task we will modify XWiki.DefaultSkin, which is a Skin defined in a page, which inherits the default filesystem skin. On production instances you should not modify this page, but instead create your own skin.

4.1: Overriding a Template

Overwriting Velocity templates allows full customization of your XWiki instance. There are generic templates used by all skins and skin specific templates.

Follow the instructions on how to override a template and override the contentview.vm template. In order to customize it, copy its current version and then modify it. Remove the Tags functionality from the page's footer. Your change will apply automatically for all the pages footers. You'll need to change the use of the Content Footer user interface extension to do so.

Using this process you could add or remove sections from the interface, change their location, order and make XWiki bind to your will.

4.2: Overriding a LESS file

Similar to how you've overridden a template you can also override files that contain global styling. If you just want to add more styling, but take advantage of the Skin's mechanism that will make your change to be global, try and override the custom.less file. Add your CSS / LESS rule that changes the table background to the color red and see its effect. 

Task 5: Inserting custom content (User Interface Extensions)

User Interface Extensions, usually referred as UIXs, offer another way to contribute some small interface changes without requiring to build a completely new skin. Instead of overriding skin's templates, you can just insert new content in some predefined places. You can even create new UI Extension Points in your custom skins.

Task 5.1: Create an UIX

For this task you should insert a 'Hello' message after the Header of your page. You can follow a similar tutorial that creates an UI Extension for the Applications Panel.


Get Connected