Directives and markers
vn-if, vn-class, vn-style, vn-strict-if, vn-theme-style, vn-overlay, vn-buttons, vn-menu, vn-video, vn-article, data-vn-icon and other attributes in the template, the rules for expressions and a list of the older notations.
Overview#
Directives are attributes that the program evaluates when it draws a block and then removes from the markup. They make a static template depend on the values of the properties: show or hide an element, set classes or styles conditionally.
This is how a block is drawn (makeGenericRenderer in src/renderer.js):
<vn-parameters>is removed.{{vn-id}}is replaced by the identifier of the instance.- Every
{{expression}}is evaluated and replaced by its result (Placeholders). - The result is read as HTML.
- The directives run over all elements in document order. For each element in this order:
vn-if,vn-class,vn-style,vn-theme-style, then the rule forvn-overlay. - The root gets the instance class and, if it has none, an
id. The LESS is compiled.
Because step 3 comes before step 5, placeholders in directives are possible but usually unnecessary: the expression in vn-if knows the values anyway.
| Directive | Effect |
|---|---|
vn-if | remove the element |
vn-strict-if | marks the block: vn-if checks strictly |
vn-class | add classes conditionally |
vn-style | set inline styles conditionally |
vn-theme-style | add theme classes |
vn-overlay | darkening layer with opacity and bg-color |
vn-buttons, vn-menu | markers for vn-theme-style |
vn-video | video block with an address field in the panel |
vn-article | extendable list |
data-vn-icon | mark an icon element |
Expressions#
The text of a directive (and of every {{…}}) is a JavaScript expression. It sees all values of the block under their name and the helpers vnEnc and vnEmbed. Technically it is the body of new Function(…names, 'return (' + expression + ');') (evalExpr in src/parser.js).
Rules (all checked)
- An error in the expression (syntax error, unknown name, access to
undefined.x) is caught and yieldsundefined, without a message. undefinedis notfalse: in the standard modevn-ifremoves only on exactlyfalse. See vn-if.- The standard JavaScript objects (
Math,String,Number,JSON…) are available. - In an HTML attribute write
&&as&&,<as<. When reading, the HTML parser decodes this notation. Swap quotation marks against those of the attribute (vn-if="mode == 'list'"). - Values of
rangefields are text. Compare withn > 3(JavaScript converts) or calculate withn * 1;n + 1appends. See range. - Values of
checkboxfields aretrueorfalse, the background widget is an object (bg.type,bg.value,bg.parallax).
Directives#
vn-if#
Removes an element including its content if the expression evaluates to false.
Syntax
<p vn-if="showText">Beschreibung</p>
<div vn-if="overlay && bg.type !== 'color'"></div>Example (from themes/vn-studio-src/components/header1)
<div class="vs-dim" vn-if="dim" style="background-color:{{dimColor}};opacity:{{dimOpacity}}"></div>What an expression yields and what becomes of it (checked, standard mode)
| Expression (value) | Result | Element |
|---|---|---|
showText (true) | true | stays |
showText (false) | false | removed |
mode == 'b' (comparison false) | false | removed |
!!titel (empty text) | false | removed |
titel (empty text) | "" | stays |
n (text "4" or "0") | text | stays |
gibtsNicht (unknown name) | error, undefined | stays |
vn-if acts while drawing. A property is therefore not "hidden": the element no longer exists in the markup (and not in the export).
vn-strict-if#
A marker on any element of the block (usually on the root element). It switches all vn-if of the block to the strict mode. The attribute itself is removed.
Syntax
<section class="mein-block" vn-strict-if>
<div vn-if="overlay">…</div>
</section>Differences to the standard mode (checked)
| Standard | with vn-strict-if | |
|---|---|---|
| Element removed on | exactly false | any falsy value: false, 0, empty text, null, undefined |
| Unknown name | element stays | name counts as undefined, element is removed |
| Error in the expression | element stays | element is removed |
Math, String … | available | available |
A range value is text and therefore counts as truthy even for "0": write Number(n) > 0. The strict mode applies to vn-if only; vn-class and vn-style stay unchanged. It was introduced for blocks taken over from other projects and is rarely needed by new blocks: write unambiguous expressions there instead.
vn-class#
Adds classes to an element depending on the values. Existing classes stay; nothing can be removed with it.
Syntax
<section vn-class="{'klasse-a': bedingung, 'klasse-b klasse-c': bedingung2}"> … </section>
<div vn-class="[{'a': x}, {'b': y}]"> … </div>
<div vn-class="'ansicht-' + mode"> … </div>Allowed results
| Result | Effect |
|---|---|
Object { 'class': value } | every key with a truthy value is added; a key may contain several classes separated by spaces |
List [ … ] | each element is treated like a single result (objects, texts, nested lists) |
Text 'a b' | the classes are added |
anything else (null, number …) and an error | nothing |
Example (from themes/vn-studio-src/components/menu1)
<nav global once="menu" class="navbar vn-menu" vn-class="{'navbar-expand-lg': !collapsed, 'sticky-top': sticky, 'vs-transparent': transparent}">vn-style#
Sets inline styles from an object.
Syntax
<h2 vn-style="{'font-size': sizeTitle + 'rem', color: titelFarbe}">Titel</h2>Rules (checked)
- Keys may be written in camelCase (
fontSize) or with a hyphen in quotation marks ('font-size'). - The value is assigned to the element as a style (
el.style[property] = value). Invalid values and unknown properties are silently ignored. An empty text ornullsets nothing. - Custom properties (
--name) are discarded: they cannot be set this way ({'--k': 1}has no effect). Write them as an ordinarystyleattribute with a placeholder:style="--k:{{k}}". - If the result is not an object (for example a text
'color:red'), nothing happens. - The style sits on the element (inline) and thus beats rules from the LESS, unless they carry
!important.
Example (following the pattern from gallery-content: font size per heading from a slider, in the program's notation)
<h2 class="titel" vn-style="{'font-size': sizeTitle + 'rem'}">Titel</h2>vn-theme-style#
Adds classes from the theme settings (for example display-7 for the font size of a theme with display classes).
Syntax
<h2 vn-theme-style="display-2">Titel</h2>
<div vn-buttons vn-theme-style="display-7"><a class="btn btn-primary" href="#">Eins</a></div>Effect (checked)
| The element is | The classes end up on |
|---|---|
a container with vn-buttons | every .btn in it |
a container with vn-menu | every .nav-link and .dropdown-item in it |
| otherwise | the element itself |
If a container has no matching children, it gets the classes itself. The attribute vn-theme-style is removed afterwards; vn-buttons and vn-menu stay in the markup as markers.
vn-overlay#
A layer that darkens or tints a background. vn-overlay is a class; two attributes control it.
Syntax
<div class="vn-overlay" vn-if="overlay" opacity="{{overlayOpacity}}" bg-color="{{overlayColor}}"></div>Attributes
| Name | Value | Meaning |
|---|---|---|
opacity | number 0 to 1 | becomes the inline style opacity |
bg-color | color | becomes the inline style background-color |
In addition the program always sets position: absolute; inset: 0; pointer-events: none. The two attributes are removed afterwards. If one is missing, the program does not set the corresponding style.
The fields overlay, overlayColor, overlayOpacity are created automatically by the program if the template contains the word overlay (Automatic overlay fields).
vn-buttons#
A marker on the container of a group of buttons. It has no effect of its own; it determines where a vn-theme-style on the same element writes its classes (onto every .btn). The attribute stays in the markup. More on buttons: Directly editable content.
<div vn-buttons vn-theme-style="display-7">
<a class="btn btn-primary" href="#">Eins</a>
<a class="btn btn-secondary" href="#">Zwei</a>
</div>vn-menu#
A marker on the container of menu items (<ul vn-menu>). It has no effect of its own; with vn-theme-style on the same element the classes go to every .nav-link and .dropdown-item. The program recognizes menu items independently of this by their classes, see Menus.
<ul class="navbar-nav" vn-menu vn-theme-style="display-4">
<li class="nav-item"><a class="nav-link" href="#">Start</a></li>
</ul>vn-video#
Marks a container with a video (iframe or video). The program turns it into an address field in the panel and converts the address into an embeddable address.
Syntax
<div vn-video class="ratio ratio-16x9">
<iframe src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"></iframe>
</div>Behavior (checked in the editor and in the export)
- The container only counts if it contains an
iframe, avideoor (for a container without a default video) the attributedata-vn-video-empty="1"with a value. - For each container the panel shows a group "Video" (with several: "Video 1", "Video 2" …) with an address field (YouTube, Vimeo or video file), "Choose video file…", "Start automatically" and "Loop". It is stored in
_videoUrl<i>,_videoAuto<i>,_videoLoop<i>(icounts the containers from 0). Without input the address in the template applies; defaults for autoplay and loop are read by the program from the address (?autoplay=1,?loop=1). - YouTube becomes
youtube-nocookie.com/embed/…, Vimeo becomesplayer.vimeo.com/video/…; a file (.mp4,.webm,.ogv,.m4v, afile:address orassets/videos/) becomes<video controls playsinline preload="metadata">. An empty address shows a hint in the editor that is missing in the export. - In the editor nothing starts on its own.
- In addition, every
iframe[data-src]in the block (video in a popup, loaded when it opens) is converted to the embeddable address.
vn-article#
Marks a list (ul or ol) as one editable field in which the Enter key creates a new list item. data-multiline is equivalent.
Syntax
<ul vn-article>
<li>Erster Punkt</li>
<li>Zweiter Punkt</li>
</ul>The items are then no text fields of their own. Nested lists: only the outermost is the field. Details: List fields.
data-vn-icon#
Marks an element as an icon that the user can replace by a click in the editor (symbol, size, color, link).
Syntax
<i class="bi bi-star-fill" data-vn-icon></i>
<span data-vn-icon class="mein-symbol"></span>Behavior (checked)
<i class="bi bi-…">and<span class="bi bi-…">are picked up even without the marker, except inside text, buttons and menu icons.data-vn-iconis therefore only needed for other elements.- On import the program assigns
data-vn-icon-id="iconN"and removes the marker. All classes exceptbiandbi-…are kept as "extra classes". - In the export the identifier is dropped; the icon appears there as
<i class="bi bi-…">.
More: Icons.
vn-parameters#
The block with the input fields. It is not a directive, but it is treated like one: it sits in the template, is removed when drawing and is never exported. See Input fields.
Further markers in the template#
An author may write these attributes in the template. The program or the bundled scripts evaluate them.
data-bg-video#
Carries the address of a background video on the root element. See Root attributes.
data-vn-editor-only#
The element appears only in the editor; the export removes it. In detail in Scripts in blocks.
<div class="vn-bgvid-empty" data-vn-editor-only vn-if="!videoFile">Noch kein Video gewählt …</div>data-vn-popup-close#
An element with this attribute closes the popup in which the block sits (for example a "No thanks" button). See Popup.
<a class="btn btn-primary" href="#" data-vn-popup-close>Schließen</a>data-vn-consent-category#
Blocks an iframe or script in the export until the visitor has agreed to the category in the VN Cookie Consent. It only applies if the project's cookie notice is switched on.
Syntax
<iframe src="https://example.com/karte" data-vn-consent-category="functional"></iframe>Values: functional, statistics, marketing. The program recognizes known services (maps, YouTube, analytics tools) itself; the attribute is the way for everything else. When blocking, it writes src to data-vn-cc-src and sets type="text/plain" on scripts. See Cookie consent and privacy.
data-vn-cookie-settings#
On a link (<a>): opens the cookie settings. The link dialog writes it itself when the user chooses "Open cookie settings". See Open cookie settings.
<a href="#" data-vn-cookie-settings>Cookie-Einstellungen</a>data-vn-anim and data-vn-anim-t#
An animation on a text or image. The tool "VN Animation" sets it; in the export there is data-vn-anim="fadeUp" (name of the animation) and data-vn-anim-t="scroll" (trigger: scroll, load or hover) together with the inline variables --vn-a, --vn-d, --vn-dl, --vn-e, --vn-n. From these markers the export creates the @keyframes and the small script for "when it becomes visible". Writing them by hand only makes sense if you also write the inline variables; use the tool for this.
data-multiline#
Like vn-article: turns a list into a field with line input. See vn-article.
Markers set by the program#
The program sets these attributes on import or when drawing. Do not write them yourself; they are in the stored template (and in the code editor) and disappear in the export.
| Attribute | Set on | Purpose |
|---|---|---|
data-vn-text-id="tN" | every editable text | stable identifier (key of the text changes) |
data-vn-image-key="feld" | <img src="{{feld}}"> and the root element with a background widget | a click opens the image selection for this field |
data-vn-free-image-id="fiN" | fixed images in the markup | replacement by a click |
data-vn-button-id="btnN", data-vn-btn-extra-classes | every <a class="btn"> | button dialog; extra classes are kept |
data-vn-icon-id="iconN", data-vn-icon-extra-classes | every icon | icon dialog |
All five groups are baked in and removed on export. How they arise and what they do: Directly editable content. Further, purely internal attributes (data-vn-text-color, data-vn-svg, data-vn-tip-*, data-vn-cms*, data-vn-drag*) are not covered in this chapter; they belong to the tools and to the CMS.
Older notations#
On import the program still accepts names from older packages and rewrites them; when drawing, it understands both notations. This list serves compatibility only. New blocks use the VN names.
| Older notation | Today | Note |
|---|---|---|
mbr-parameters | vn-parameters | tag; both are read |
mbr-if | vn-if | |
mbr-class | vn-class | |
mbr-style | vn-style | |
mbr-theme-style | vn-theme-style | on import only for themes with display font sizes; otherwise the attribute stays without effect |
mbr-buttons | vn-buttons | |
mbr-menu | vn-menu | |
mbr-video | vn-video | |
mbr-icon | data-vn-icon | |
mbr-article | vn-article | |
{{mbr-id}} | {{vn-id}} | both are replaced |
class mbr-overlay | class vn-overlay | both are evaluated (the class is not renamed on import) |
These classes stay unchanged on import because theme CSS and plugins address them. The program still knows them:
| Class | Meaning for the program |
|---|---|
mbr-text, mbr-section-title, mbr-title, mbr-fonts-style | text detection (in addition to the tags h1 to h6, p, li …) and target of the site-wide font rules |
mbr-iconfont, mbri-… | icon detection; the mbri-… class is removed, the icon stays empty until selected |
mbr-fallback-image | fallback image layer that the program inserts itself for data-bg-video |
mbr-parallax-background | triggers the parallax plugin in Bootstrap theme mode |
Attributes from older packages that the program does not evaluate and that remain in the markup without effect: data-app-selector, data-app-placeholder, data-toolbar, always-top, not-draggable, position-absolute and group="…" on the root element.