Wiki source code of Style variables
Last modified by Lucas Charpentier (Sereza7) on 2025/04/04
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
5.1 | 1 | {{toc/}} |
| 2 | |||
| 3 | == What is a style variable? == | ||
| 4 | |||
| 5 | A style variable represents a value shared across all of XWiki's style sheets. These values are meant to be used instead of hard-coding them in stylesheets. Our [[CSS codestyle>>doc:dev:Community.CodeStyle.XhtmlCssCodeStyle.WebHome||anchor="HCSS"]] makes the use of these variables mandatory in XWiki Standard development. It's recommended to rely on those for your own custom developments too :) | ||
| 6 | |||
| 7 | They provide some level of consistency in the UI: | ||
| 8 | |||
| 9 | * It will be harder for customizations to have unwanted effects | ||
| 10 | * XWiki can provide colors that work well together by default. Among other things, it can help make sure all your components respect some minimum contrast. | ||
| 11 | * It's straightforward for your custom development components to be compatible with the color themes applied on multiple wikis | ||
| 12 | |||
| 13 | == How to use style variables? == | ||
| 14 | |||
| 15 | Currently, XWiki Standard with its Flamingo Skin support three kinds of style variables. They are (ranging from the oldest to the newest): | ||
| 16 | |||
| 17 | * The old colorTheme variables | ||
| 18 | * The LESS variables (Flamingo colorTheme + design system inherited from bootstrap + Misc additions from the Flamingo skin) | ||
| 19 | * {{version since="17.3.0RC1"}}The CSS properties{{/version}} | ||
| 20 | |||
| 21 | {{info}} | ||
| 22 | There's some documentation about the first two at: https://extensions.xwiki.org/xwiki/bin/view/Extension/Color%20Theme%20Application#HUsingColorThemesvariables | ||
| 23 | {{/info}} | ||
| 24 | |||
| 25 | (% class="wikigeneratedid" %) | ||
| 26 | All of these variables are supposed to be used in .css files, .less files and their respective StyleSheet Extensions,. | ||
| 27 | |||
| 28 | === Using CSS properties === | ||
| 29 | |||
| |
5.2 | 30 | ==== In a CSS stylesheet ==== |
| 31 | |||
| 32 | {{code language="css"}} | ||
| 33 | .box.box-custom { | ||
| 34 | color: var(--brand-color); | ||
| 35 | } | ||
| 36 | {{/code}} | ||
| 37 | |||
| 38 | ==== In a LESS stylesheet ==== | ||
| 39 | |||
| 40 | {{warning}} | ||
| 41 | It's recommended to use CSS variables in CSS stylesheets. LESS stylesheets are less versatile and more computationally costly. | ||
| 42 | {{/warning}} | ||
| 43 | |||
| 44 | {{code language="css"}} | ||
| 45 | .box.box-custom { | ||
| 46 | color: ~"var(--brand-color)"; | ||
| 47 | } | ||
| 48 | {{/code}} | ||
| 49 | |||
| 50 | === Using LESS variables === | ||
| 51 | |||
| 52 | ==== In a CSS stylesheet ==== | ||
| 53 | |||
| 54 | {{error}} | ||
| 55 | It's not possible to use LESS variables in CSS stylesheets. Those variables need LESS compilation to work. | ||
| 56 | {{/error}} | ||
| 57 | |||
| 58 | ==== In a LESS stylesheet ==== | ||
| 59 | |||
| 60 | {{code language="lesscss"}} | ||
| 61 | .box.box-custom { | ||
| 62 | color: @brand-color; | ||
| 63 | } | ||
| 64 | {{/code}} | ||
| 65 | |||
| 66 | === Using old colorTheme variables === | ||
| 67 | |||
| 68 | {{error}} | ||
| 69 | Those variables are deprecated, avoid using them in any new development. | ||
| 70 | {{/error}} | ||
| 71 | |||
| 72 | In a CSS stylesheet | ||
| 73 | |||
| |
5.1 | 74 | == Migrating from LESS to CSS properties == |
| 75 | |||
| 76 | This section contains a few points that could be important when migrating LESS styles to using the CSS properties. Those are not community rules to be followed, but just indications to make it easier to migrate :) | ||
| 77 | |||
| 78 | {{warning}} | ||
| 79 | Today, there is no way to migrate any LESS mixin to CSS one to one. In order to migrate any advanced use of mixins, an additional class should be added for the styles on the HTML. | ||
| 80 | {{/warning}} | ||
| 81 | |||
| 82 | |||
| 83 | === Syntax sugar === | ||
| 84 | |||
| 85 | Native CSS is a bit more wordy than LESS: | ||
| 86 | |||
| 87 | * Variables start with a double dash (~-~-) instead of an arobase (@) | ||
| 88 | * All use of a CSS variable should be made in a ##var## block. | ||
| 89 | * All operations that you could write in your LESS must be made in a ##calc## block. | ||
| 90 | |||
| 91 | |||
| 92 | |||
| 93 | {{code language="css"}} | ||
| 94 | --popover-arrow-color: var(--popover-bg); | ||
| 95 | --popover-arrow-outer-width: calc(var(--popover-arrow-width) + 1px); | ||
| 96 | {{/code}} | ||
| 97 | |||
| 98 | === Units in CSS calculus === | ||
| 99 | |||
| 100 | LESS doesn't have any clearly defined unit system. CSS has a very strict unit system (some improvements to make it a bit looser and easier to use are discussed though). If a formula doesn't work in CSS, it's probably because the units do not respect the constraint of the operators: | ||
| 101 | |||
| 102 | * Addition and substraction, both values must have the same unit | ||
| 103 | * Multiplications and divisions, only one value has an unit, the second one is unitless. | ||
| 104 | |||
| 105 | [[The exact rules>>https://developer.mozilla.org/en-US/docs/Web/CSS/calc#description]] are more precise than that. | ||
| 106 | |||
| 107 | === Migrating color functions === | ||
| 108 | |||
| 109 | To migrate LESS ##color functions##, you can use the CSS color or hsl functions: | ||
| 110 | |||
| 111 | {{code language="css"}} | ||
| 112 | hsl(from var(--well-bg) h s calc(l - 0.07)) | ||
| 113 | {{/code}} | ||
| 114 | |||
| 115 | HSL is useful for most operations, color is really only useful for transparency calculations. | ||
| 116 | LESS color functions work directly with additions: darken(@well-bg, 7%) is the same as the snippet above. This is slightly different from calc( l * (1-0.07)) which was how I assumed LESS handled its operations at first. | ||
| 117 | |||
| 118 | {{info}} | ||
| 119 | You can also use the CSS ##color-mix## with black or white to darken or lighten a color. | ||
| 120 | {{/info}} | ||
| 121 | |||
| 122 | === Using CSS variables in LESS === | ||
| 123 | |||
| 124 | Sometimes you want to start migrating a file without being able to move it all at once. In this kind of situation, you'll need to know about how to use CSS variables in a LESS file. | ||
| 125 | |||
| 126 | The LESS parser we use in XWiki standard is not maintained enough to ensure a good compatibility with current CSS. It does not work well with CSS variables directly. The usual solution to escape things in LESS works well for most cases: a tilde and the escaped content in between quotes. | ||
| 127 | |||
| 128 | {{code language="lesscss"}} | ||
| 129 | -/**/-navbar-default-bg: ~"var(--brand-primary)"; | ||
| 130 | -/**/-navbar-default-border: ~"color-mix(in srgb, var(--navbar-default-bg), black 6.5%)"; | ||
| 131 | {{/code}} | ||
| 132 | |||
| 133 | But, a quirk of the parser is that this syntax does not work when we're trying to use it for an assignation. One hack that's not too bad looking that works for those variable assignations is to add an empty comment block in the middle. It prevents the LESS parser from associating the two dashes together and assume this is the end of an HTML comment. You can see this workaround in the example above. | ||
| 134 | |||
| 135 | {{warning}} | ||
| 136 | Contrary to LESS variables that are global by default, CSS properties should be defined in a block. Either their own with the ##@property## query, or inside a ruleset. Typically, in order to make CSS properties global, just put their assignations in a ##:root { }## block. | ||
| 137 | {{/warning}} | ||
| 138 | |||
| 139 |
