Wiki source code of Track: Styling XWiki

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

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 So you want to change the styling of your wiki, application or page. Welcome to the Styling Track.
6
7 = Task 1: Small interface changes (##Skin Extensions##) =
8
9 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>>extensions:Extension.Skin Extension Plugin]], usually referred as a ##SSX##, that you can add to that particular page.
10
11 == Task 1.1: Using ##CSS## ==
12
13 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>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial||anchor="HMinimalStyleSheetextension"]].
14
15 == Task 1.2: Using ##LESS## ==
16
17 XWiki has support for the [[##LESS##>>http://lesscss.org/]] preprocessor. This could help you use advanced [[functions>>http://lesscss.org/functions/]] on top of ##CSS##. [[Use ##LESS##>>extensions:Extension.Skin Extension Plugin||anchor="HUseLESS"]] in your ##SSX## and make the background be a pinkish color.
18
19 == Task 1.3: ##SSX## visibility ==
20
21 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.
22
23 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. ##SSX##s should be used when you want to target specific pages or applications. Even though you could use ##SSX##s, if you want to make more complex / global / wiki changes you should use the ##Skin## mechanism that we will try in another task.
24
25 == Task 1.4: Using ##Velocity## ==
26
27 You've learned about our [[Scripting>>xwiki:Documentation.DevGuide.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##>>http://velocity.apache.org/]] with ##CSS## / ##LESS##. For that you will need to set the ##SSX##'s "##Parse content##" property to "##YES##". See an [[example>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial||anchor="HMakingitlooknicewithSSX"]].
28
29 For this task you should write a condition that will display the written ##CSS## / ##LESS## only for your user.
30
31 == Bonus Task: Using ##JavaScript## ==
32
33 If you want to [[add custom JavaScript>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial||anchor="HMinimalJavaScriptextension"]] to your page you can use JavaScript Skin Extensions, usually referred as a ##JSX##. ##JSX##s can also be parsed, so you can combine ##Velocity## with your JavaScript.
34
35 = Task 2: Reusing colors (##Color Themes##) =
36
37 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>>extensions:Extension.WebHome]] 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.
38
39 == Task 2.1: Changing the current color theme ==
40
41 Play a bit [[changing>>extensions:Extension.Flamingo Theme Application||anchor="HHowtoselectatheme"]] the Color Themes and find a new one that you like.
42
43 == Task 2.2: Creating a new color theme ==
44
45 It is a good exercise to [[create a new color theme>>extensions:Extension.Flamingo Theme Application||anchor="HHowtocreateanewtheme"]] in order to see exactly what you can customize.
46
47 == Task 2.3: Using advanced variables ==
48
49 The Color Theme interface allows you to change the most common variables, but there are even more [[variables>>https://github.com/twbs/bootstrap/blob/v3.4.0/less/variables.less]] that you could change. You can manually modify the variables or add more ##CSS## / ##LESS## code from the "[[##Advanced##>>extensions:Extension.Flamingo Theme Application||anchor="HAdvanced:LESSCode"]]" section.
50
51 In this task you should change the border color to be red, by using an existing variable name.
52
53 == Task 2.4: Reusing existing color variables ==
54
55 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.
56
57 Remember the red background color you've used in the first task? Find a suitable variable to reuse for that value.
58
59 Note: You should take a look at ##@brand-*## or ##$theme.notification*## variables. [[Not sure>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial||anchor="HLESS"]] 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>>extensions:Extension.Color Theme Application||anchor="HUsingColorThemesvariables"]] (needs ##Velocity## to be parsed) or the [[Flamingo Theme variables>>extensions:Extension.Flamingo Theme Application||anchor="HUsingthemevariables"]] (needs ##LESS## to be compiled).
60
61 = Task 3: Reusing icons (##Icon Themes##) =
62
63 Similar to colors, XWiki provides an [[Icon Themes>>extensions:Extension.Icon Theme Application]] mechanism to easily change the icons set used.
64
65 == Task 3.1: Changing the current color theme ==
66
67 [[Change>>extensions:Extension.Icon Theme Application||anchor="HSelectingtheIconSet"]] the Icon Themes from Administration and see what icons it affects.
68
69 == Task 3.2: Reusing existing icon variables ==
70
71 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>>design:Proposal.IconSet]] list or in the Icon Theme definition.
72
73 = Task 4: Complex interface changes (##Skins##) =
74
75 ##SSX##s 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##>>xwiki:Documentation.UserGuide.Features.Skins]] mechanism.
76
77 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.
78
79 You can read more details about ##Skins##:
80
81 * [[Changing the current skin>>xwiki:Documentation.AdminGuide.Skins]]
82 * [[Creating a new skin>>xwiki:Documentation.DevGuide.Tutorials.Skins]]
83
84 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.
85
86 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.
87
88 == 4.1: Overriding a ##Template## ==
89
90 Overwriting ##Velocity## templates allows full customization of your XWiki instance. There are [[generic templates>>https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-web/src/main/webapp/templates]] used by all skins and [[skin specific templates>>https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-flamingo/xwiki-platform-flamingo-skin/xwiki-platform-flamingo-skin-resources/src/main/resources/flamingo]].
91
92 Follow the instructions on [[how to override a template>>extensions:Extension.Skin Application||anchor="HHowtooverrideatemplate"]] and override the [[##contentview.vm##>>https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-flamingo/xwiki-platform-flamingo-skin/xwiki-platform-flamingo-skin-resources/src/main/resources/flamingo/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##>>https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/ExtensionPoint/ContentFooterUIX/]] user interface extension to do so.
93
94 Using this process you could add or remove sections from the interface, change their location, order and make XWiki bind to your will.
95
96 == 4.2: Overriding a ##LESS## file ==
97
98 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##>>extensions:Extension.Flamingo Skin||anchor="HCustomisingstying"]] file. Add your ##CSS## / ##LESS## rule that changes the table background to the color red and see its effect.
99
100 = Task 5: Inserting custom content (##User Interface Extensions##) =
101
102 [[User Interface Extensions>>extensions:Extension.UIExtension Module]], usually referred as ##UIX##s, 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>>xwiki:Documentation.DevGuide.ExtensionPoint]]. You can even [[create new UI Extension Points>>doc:xwiki:Documentation.DevGuide.Tutorials.UIXTutorial.WebHome]] in your custom skins.
103
104 == Task 5.1: Create an ##UIX## ==
105
106 For this task you should insert a 'Hello' message after the Header of your page. You can follow a [[similar tutorial>>extensions:Extension.UIExtension Module||anchor="HWritingasimpleUIExtension"]] that creates an UI Extension for the Applications Panel.

Get Connected