VN-Designer Developer Documentation
05

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.

less
padding-top: (@abstand * 1rem);
background: @kartenFarbe;
.titel { color: @akzent; }
@media (max-width: 767px) { padding-top: 0; }

Three things distinguish this file from ordinary LESS:

  1. Variables: Every property from <vn-parameters> is available as the variable @name, plus @bg-type, @bg-value, @bg-parallax and a number of theme variables.
  2. 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.
  3. 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 typeLESS valueExample @nameUse
rangenumber without unit4padding-top: (@abstand * 1rem);
colorcolor#4f46e5background: @akzent;, fade(@akzent, 20%)
checkboxtrue or falsetrue& when (@schatten) { … }
select, text, textarea, imagetext in single quotes'center'& when (@ausrichtung = 'center') { … }, url(@foto)
Background widgetno 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):

less
aspect-ratio: ~"@{ratio}";     // property value without quotation marks
@cls: e(@mode);                 // names for selectors: .grid-x, &.is-grid
.@{cls}-x { … }
&.ansicht-@{cls} { … }
NotationResult 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).

less
& 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)

NotationResult
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 / number and @variable / @variable in parentheses itself (line-height: @n / 2; yields 1.5). A division of literals is not rewritten: 10px / 2 stays as it is, (10px / 2) yields 5px.
  • 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() and max() 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):

VariableValueMeaning
@bg-type'color', 'image' or 'video'chosen kind
@bg-value for colorcolor, e.g. #f3f4f6no quotation marks
@bg-value for imagetext, the image addressurl(@bg-value) yields url("…")
@bg-value for videotext, the video address
@bg-parallaxtrue or falseswitch "Parallax effect" (on only for images)

Pattern (from themes/vn-studio-src/components/header1, extended by parallax)

less
& 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:

VariablesDefault
@primaryColor#3B7DDD
@secondaryColor#6C757D
@successColor#28A745
@infoColor#17A2B8
@warningColor#FFC107
@dangerColor#DC3545
@mainFont, @display1Font, @display2Font, @display4Font, @display5FontPoppins
@display7FontRoboto
@display1Size to @display7Size (1, 2, 4, 5, 7)4.25, 3, 0.875, 1.5, 1.06
@isRoundedButtons, @isGhostButtonBorder, @isAnimatedOnScroll, @isScrollToTopButtonfalse

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:

less
@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 writeResultMeans
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-titelusual 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, @supportslike @media
@keyframes, @font-facewithout instance classapply 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 line css) 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):

css
@layer app-ui, bootstrap-base, theme-base, vn-blocks;
LayerContent
app-uithe program's user interface
bootstrap-baseBootstrap 5.0.1 for the canvas (@scope (#canvas))
theme-basetheme CSS of the package (@scope (#canvas)), see Theme CSS
vn-blocksthe CSS of all blocks, compiled, with instance class, without @scope
no layerrules 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).

CaseEditorExport
Block rule against Bootstrap, both without !importantblock (layer)block (higher specificity, later)
Block rule against theme CSS, both without !importantblockblock (later)
Block !important against Bootstrap !important (e.g. .text-white)Bootstrapblock (higher specificity)
Block !important against theme CSS !importantthemespecificity, then order
Block !important against a site setting or "Custom CSS" with !importantblockspecificity, then order
Block without !important against "Custom CSS" without !importantCustom CSS (no layer)specificity: usually block
Block without !important against the site's font size (!important)sitesite

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 CSSEditorExport
.x { … }matches .x in the canvasmatches .x
#canvas .x { … }matches nothingmatches nothing (there is no #canvas)
:scope#canvas .x { … }matches .x (editor only)matches nothing
:scope { --farbe: red; }sets the variable on #canvassets it on html
html { … }, body { … }, :root { … }no effectapplies 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:

SettingActs onConsequence 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 headingstexts, headings, menu, .btnfont-family
Typography per element (H1–H6, P, LI, buttons)the elements namedfont-family, font-size, font-weight, color, line-height with !important
Global button corners.btn without its own shapeborder-radius with !important
Link stylelinks in nav and outsidetext-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 on div or span, 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.

The practical rule of the bundled blocks: set colors, borders and font of buttons and links in the block LESS with !important.

less
.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 blockpage-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.

less
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:

css
.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 @name in 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}" or e(@x).
  • No body, html, :root in the block LESS.
  • No BOM, no @import, no default().
  • Names in @keyframes/@font-face with an abbreviation.
  • !important only where it is needed, and checked afterwards in the live preview.