Block styles (style.less)
How style.less is compiled: variables from the properties, background variables, conditions, scoping by instance class, CSS layers and precedence in the editor and the export, base font size, buttons and links, theme CSS versus block CSS.
Overview#
style.less is the style of one block. The program compiles it with LESS 4.9.1 every time the block is drawn, that is, on every change of a value in the properties panel. Instead of style.less the file may be called style.css; it runs through the same compiler.
padding-top: (@abstand * 1rem);
background: @kartenFarbe;
.titel { color: @akzent; }
@media (max-width: 767px) { padding-top: 0; }Three things distinguish this file from ordinary LESS:
- Variables: Every property from
<vn-parameters>is available as the variable@name, plus@bg-type,@bg-value,@bg-parallaxand a number of theme variables. - Root: The program wraps the whole content in
.<instance class> { … }. Declarations without a selector therefore apply to the root element, every rule only to elements inside the block. - Precedence: In the editor the CSS sits in a layer of its own; the rules for this are below.
Variables from the properties#
For every field with a name, the program declares a variable before your LESS. The value depends on the field type:
| Field type | LESS value | Example @name | Use |
|---|---|---|---|
range | number without unit | 4 | padding-top: (@abstand * 1rem); |
color | color | #4f46e5 | background: @akzent;, fade(@akzent, 20%) |
checkbox | true or false | true | & when (@schatten) { … } |
select, text, textarea, image | text in single quotes | 'center' | & when (@ausrichtung = 'center') { … }, url(@foto) |
| Background widget | no variable @bg, but the background variables |
An empty range value yields 0, an empty color #000000. In text, ' and @{ are escaped so that arbitrary input cannot break the LESS.
Outputting values as text in CSS#
Because text arrives as LESS text (with quotation marks), aspect-ratio: @ratio; yields the invalid output aspect-ratio: '16/9';. There are three ways to get the bare value (all checked):
aspect-ratio: ~"@{ratio}"; // property value without quotation marks
@cls: e(@mode); // names for selectors: .grid-x, &.is-grid
.@{cls}-x { … }
&.ansicht-@{cls} { … }| Notation | Result with @mode: 'grid' |
|---|---|
@mode as a value | 'grid' (with quotation marks) |
~"@{mode}" | grid |
e(@mode) | grid |
.@{mode}-x (without e()) | .'grid'-x (invalid) |
Texts in content or url(…) work directly: content: "@{label}"; and url(@foto) (both checked).
Comparisons and conditions#
With & when (…) { … } you include rules depending on values (LESS guards).
& when (@schatten) { box-shadow: 0 8px 24px rgba(0, 0, 0, .2); }
& when not (@schatten) { box-shadow: none; }
& when (@ansicht = 'liste') { .karten { display: block; } }
& when (@anzahl > 2) and (@schatten) { … }What works in a condition (checked)
| Notation | Result |
|---|---|
when (@checkbox) | true if on |
when (@checkbox = true) | true if on |
when (@checkbox = false) | true if off |
when not (@checkbox) | true if off |
when (@text = 'abc') and when (@text = "abc") | true if equal |
when (@text = abc) (without quotation marks) | never true |
when (@number > 2), when (@number = 2) | comparison with the number |
when (@number = "2") | never true (number against text) |
when (@a) and (@b), when (@a), (@b) | and, or |
when (default()) | error: only allowed in mixin guards, the whole CSS of the block is lost |
Calculating#
- Multiplication needs no parentheses:
@n * 1rem,@n * 10%,2 * @n; parentheses never hurt, though ((@n * 1rem)), and this is the standard in the blocks. - Division only in parentheses:
(@n / 2). The program wraps@variable / numberand@variable / @variablein parentheses itself (line-height: @n / 2;yields1.5). A division of literals is not rewritten:10px / 2stays as it is,(10px / 2)yields5px. - You attach units:
(@n * 1px),(@n * 1%),(@n * 1vw). - CSS functions with variables you write as LESS text:
font-size: ~"clamp(1rem, @{n}vw, 3rem)";,width: ~"calc(100% - @{n}rem)";.min()andmax()with parenthesized calculation also work directly:min((@n * 10px), 50%). - The color functions of LESS are available:
fade,lighten,darken,mix,contrast(checked).
Background variables#
If the block has a background widget, these variables are added (bg stands for the name of the widget; the names @bg-type, @bg-value, @bg-parallax are fixed, independent of the field name):
| Variable | Value | Meaning |
|---|---|---|
@bg-type | 'color', 'image' or 'video' | chosen kind |
@bg-value for color | color, e.g. #f3f4f6 | no quotation marks |
@bg-value for image | text, the image address | url(@bg-value) yields url("…") |
@bg-value for video | text, the video address | |
@bg-parallax | true or false | switch "Parallax effect" (on only for images) |
Pattern (from themes/vn-studio-src/components/header1, extended by parallax)
& when (@bg-type = 'color') { background-color: @bg-value; }
& when (@bg-type = 'image') {
background-image: url(@bg-value);
background-size: cover;
background-position: center;
& when (@bg-parallax = true) { background-attachment: fixed; }
}For an image with parallax switched on, the program additionally appends a rule of its own, .<instance class> { background-attachment: fixed; }. Parallax therefore also works if your LESS never queries @bg-parallax.
Theme variables#
In addition to the fields, every LESS knows these variables, so that blocks from theme packages do not fail on a missing variable without their theme:
| Variables | Default |
|---|---|
@primaryColor | #3B7DDD |
@secondaryColor | #6C757D |
@successColor | #28A745 |
@infoColor | #17A2B8 |
@warningColor | #FFC107 |
@dangerColor | #DC3545 |
@mainFont, @display1Font, @display2Font, @display4Font, @display5Font | Poppins |
@display7Font | Roboto |
@display1Size to @display7Size (1, 2, 4, 5, 7) | 4.25, 3, 0.875, 1.5, 1.06 |
@isRoundedButtons, @isGhostButtonBorder, @isAnimatedOnScroll, @isScrollToTopButton | false |
If the block belongs to a theme package whose params.json defines its own variables under theme.settings, their values replace the defaults, see Theme properties. A field of the block with the same name overrides both.
Scope and root#
The program wraps your LESS like this:
@abstand: 4; // … all variables
.vn-imp-meine-bloecke-bmw3s4eyec6ik { // instance class
/* Ihr style.less */
}The instance class is carried by each block instance individually (vn-imp-<alias>-<block ID>, see Packages); two blocks of the same type therefore do not interfere with each other.
What follows (all checked)
| You write | Result | Means |
|---|---|---|
padding: 2rem; | .root { padding: 2rem; } | the root element itself |
.titel { … } | .root .titel { … } | descendants in the block |
&.aktiv { … } | .root.aktiv { … } | the root element with an additional class |
> .direkt { … } | .root > .direkt { … } | direct children |
.karte { &:hover { … } &-titel { … } } | .root .karte:hover, .root .karte-titel | usual LESS nesting |
h1, h2 { … } and * { … } | .root h1, .root h2, .root * | applies only inside the block |
@media (…) { … } | @media (…) { .root … } | media query outside, rule inside |
@container, @layer, @supports | like @media | |
@keyframes, @font-face | without instance class | apply to the whole page |
body { … }, html { … }, :root { … } | .root body { … } | never matches anything |
Two quirks that the compiler smooths out:
- A leading language marker from pasted chat code (
css:or a first linecss) is removed; otherwise LESS would swallow the first property. - Line comments
// …are dropped in the output, block comments/* … */stay.
Errors in the LESS#
If the compilation fails (syntax error, unknown variable, guard default()), the following happens:
- The block gets the red label "⚠ CSS error" in the editor; the message is in the tooltip.
- The CSS of this block is empty (not only the faulty rule). Other blocks are not affected.
- A warning appears in the console of the developer tools.
Typical causes: a name with an umlaut or $ as a property name, @import, an unclosed block, when (default()).
Precedence: layers and order#
The editor and the export put the CSS together differently. You need to understand both when a block looks different in the editor from the finished page.
In the editor#
At startup the editor fixes the order of the CSS layers (later ones win):
@layer app-ui, bootstrap-base, theme-base, vn-blocks;| Layer | Content |
|---|---|
app-ui | the program's user interface |
bootstrap-base | Bootstrap 5.0.1 for the canvas (@scope (#canvas)) |
theme-base | theme CSS of the package (@scope (#canvas)), see Theme CSS |
vn-blocks | the CSS of all blocks, compiled, with instance class, without @scope |
| no layer | rules from the site settings (font, font size, typography, link style) and "Custom CSS" |
In the export#
There are no layers and no @scope. The page loads vendor/bootstrap.min.css and then style.css. In style.css come, in this order: theme CSS (unscoped), CSS of all blocks, font rules of the site settings, fixed helper rules of the program (menu, links, dialogs), finally "Custom CSS". The ordinary rules decide: importance, then specificity, then order.
Who wins (measured)#
All rows were measured in the running program (editor) and on a page built from the export (export).
| Case | Editor | Export |
|---|---|---|
Block rule against Bootstrap, both without !important | block (layer) | block (higher specificity, later) |
Block rule against theme CSS, both without !important | block | block (later) |
Block !important against Bootstrap !important (e.g. .text-white) | Bootstrap | block (higher specificity) |
Block !important against theme CSS !important | theme | specificity, then order |
Block !important against a site setting or "Custom CSS" with !important | block | specificity, then order |
Block without !important against "Custom CSS" without !important | Custom CSS (no layer) | specificity: usually block |
Block without !important against the site's font size (!important) | site | site |
The rule behind it: For ordinary declarations the later layer wins, and no layer wins over all layers. For !important the order is reversed: the earlier layer wins, and no layer loses. An !important declaration in the block therefore does not beat an !important rule from Bootstrap or the theme CSS in the editor.
The #canvas trap in the theme CSS#
In the editor the theme CSS sits in @scope (#canvas) { … }. Inside @scope, #canvas is the scope root node, and a selector #canvas .x matches nothing there (checked). For rules that should apply only in the editor, write :scope#canvas .x.
| Notation in the theme CSS | Editor | Export |
|---|---|---|
.x { … } | matches .x in the canvas | matches .x |
#canvas .x { … } | matches nothing | matches nothing (there is no #canvas) |
:scope#canvas .x { … } | matches .x (editor only) | matches nothing |
:scope { --farbe: red; } | sets the variable on #canvas | sets it on html |
html { … }, body { … }, :root { … } | no effect | applies normally |
In the editor, media queries use the window width of the program, not the width of the canvas. Check phone and tablet in the live preview ("Tablet" and "Phone" buttons).
Site settings that override your CSS#
Some settings of the project produce CSS with !important. They apply to all blocks and also act on your block LESS:
| Setting | Acts on | Consequence for the block LESS |
|---|---|---|
Font size of body text (new projects: 1.2rem) | body, p, li, td, th, blockquote, figcaption, label and the text classes of older packages (Older notations) | font-size on these elements with !important |
| Font for body text and menu, font for headings | texts, headings, menu, .btn | font-family |
| Typography per element (H1–H6, P, LI, buttons) | the elements named | font-family, font-size, font-weight, color, line-height with !important |
| Global button corners | .btn without its own shape | border-radius with !important |
| Link style | links in nav and outside | text-decoration (without !important) |
What this means for you (measured, see above):
p { font-size: 3rem; }in the block LESS stays without effect as long as the site's font size is set. Put fine sizes ondivorspan, or set!important(.klasse { font-size: 3rem !important; }).- The font size applies only to body text. Headings, menu, buttons and links are not touched by it.
Buttons and links#
The practical rule of the bundled blocks: set colors, borders and font of buttons and links in the block LESS with !important.
.tz-text .btn-primary {
background-color: @akzent !important;
border-color: @akzent !important;
color: #fff !important;
}Measured: A button rule without !important wins in the editor and in the export against Bootstrap (see the table above). !important protects against the rules that do not win there: theme CSS with higher specificity or !important and the site's font rules. For !important against Bootstrap !important note the warning above (editor and export differ).
The button dialog sets the color as a Bootstrap class (btn-primary …). If the user chooses "Own color", the color class is dropped and the colors sit on the element as an ordinary inline style (without !important, checked in the code). Therefore aim !important at the color class (.btn-primary), not at .btn: an !important rule on .btn overrides the user's own color.
Block CSS or theme CSS?#
Belongs in the block LESS (style.less) | Belongs in the theme CSS (plugins/theme/css/style.css) |
|---|---|
everything that depends on properties of the block (@name) | rules without variables that several blocks share (base typography of the theme, shared helper classes) |
| appearance of this block | .btn shapes and default colors of the theme |
@media, @container for this block | page-wide rules (body, :scope) |
@keyframes of the block (with an abbreviation in the name) | fonts (@font-face) with files from the package |
The block LESS is stored with the block and is output in the export only for blocks that are used. The theme CSS is loaded once per project; a later package update does not change it in existing projects (Only once per project). An error in the theme CSS is therefore harder to fix later than one in the block.
Example#
The example combines variables, conditions, background variables, a media query and the practical rule for buttons. It belongs to the teaser block from Input fields; the template is there as well.
position: relative;
padding-top: (@abstandOben * 1rem);
padding-bottom: (@abstandUnten * 1rem);
color: @textFarbe;
& when (@bg-type = 'color') { background-color: @bg-value; }
& when (@bg-type = 'image') {
background-image: url(@bg-value);
background-size: cover;
background-position: center;
& when (@bg-parallax = true) { background-attachment: fixed; }
}
.tz-inner { position: relative; z-index: 1; display: flex; gap: 2rem; align-items: center; }
.tz-foto { max-width: 40%; border-radius: 0.5rem; }
.tz-vorteile { white-space: pre-line; font-size: 1.1rem; }
&.tz-mitte .tz-inner { justify-content: center; text-align: center; }
.tz-text h2 { color: @akzent; }
.tz-text .btn-primary {
background-color: @akzent !important;
border-color: @akzent !important;
color: #fff !important;
}
@media (max-width: 767px) {
.tz-inner { flex-direction: column; }
.tz-foto { max-width: 100%; }
}Compiled, with abstandOben = 4 and an image background, this yields, among other things:
.vn-imp-beispiel-teaser-bmw3se032ai5q {
position: relative;
padding-top: 4rem;
padding-bottom: 4rem;
color: #1f2937;
background-image: url("assets/x.jpg");
background-size: cover;
background-position: center;
background-attachment: fixed;
}
.vn-imp-beispiel-teaser-bmw3se032ai5q .tz-inner { … }Checklist#
- Every variable
@namein the LESS is a field in<vn-parameters>(or a background/theme variable). @bg-…only if a background widget is present, and only inside a condition on@bg-type.- Compare select values as text (
@x = 'a'), in properties and selectors use~"@{x}"ore(@x). - No
body,html,:rootin the block LESS. - No BOM, no
@import, nodefault(). - Names in
@keyframes/@font-facewith an abbreviation. !importantonly where it is needed, and checked afterwards in the live preview.