Track: Styling XWiki
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 containing a table with some data. You want to have a red background for an important column or cell. For this case, you should use a StyleSheet Skin Extension, usually a SSX, that you can add to that page.
Task 1.1: Using CSS
For this task, you should write some CSS that changes the background color of your table cells to 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 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 the page that contains the object.
Play 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, which we will try in another task.
Task 1.4: Using Velocity
You've learned about our Scripting languages in a previous Track. If you want to add conditions, make your styling rules more dynamic, or use XWiki API, you can combine Velocity with CSS / LESS. 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 a JSX. JSXs can also be parsed by combining Velocity with your JavaScript.
Task 2: Reusing colors (Color Themes)
XWiki supports multiple Color Themes that allow 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
Practice changing the Color Themes and find a new one 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 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 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 suggests 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 change your XWiki instance's interface radically, you should use the Skin mechanism.
A Skin defines a base CSS that could be built 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 could be overridden and inherited by other filesystem skins or by skins defined in a wiki document.
For this task, we will modify XWiki.DefaultSkin, which is a Skin defined on a page, inherits the default filesystem skin. You should not modify this page on production instances 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 to all the page footers. You'll need to change the use of the Content Footer user interface extension to do so.
You could add or remove sections from the interface, change their location, and 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 building a completely new skin. Instead of overriding skin templates, you can just insert new content in 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 a UI Extension for the Applications Panel.
