VN-Designer Developer Documentation
04

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

  1. <vn-parameters> is removed.
  2. {{vn-id}} is replaced by the identifier of the instance.
  3. Every {{expression}} is evaluated and replaced by its result (Placeholders).
  4. The result is read as HTML.
  5. 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 for vn-overlay.
  6. 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.

DirectiveEffect
vn-ifremove the element
vn-strict-ifmarks the block: vn-if checks strictly
vn-classadd classes conditionally
vn-styleset inline styles conditionally
vn-theme-styleadd theme classes
vn-overlaydarkening layer with opacity and bg-color
vn-buttons, vn-menumarkers for vn-theme-style
vn-videovideo block with an address field in the panel
vn-articleextendable list
data-vn-iconmark 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 yields undefined, without a message.
  • undefined is not false: in the standard mode vn-if removes only on exactly false. See vn-if.
  • The standard JavaScript objects (Math, String, Number, JSON …) are available.
  • In an HTML attribute write && as &amp;&amp;, < as &lt;. When reading, the HTML parser decodes this notation. Swap quotation marks against those of the attribute (vn-if="mode == 'list'").
  • Values of range fields are text. Compare with n > 3 (JavaScript converts) or calculate with n * 1; n + 1 appends. See range.
  • Values of checkbox fields are true or false, 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

html
<p vn-if="showText">Beschreibung</p>
<div vn-if="overlay &amp;&amp; bg.type !== 'color'"></div>

Example (from themes/vn-studio-src/components/header1)

html
<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)ResultElement
showText (true)truestays
showText (false)falseremoved
mode == 'b' (comparison false)falseremoved
!!titel (empty text)falseremoved
titel (empty text)""stays
n (text "4" or "0")textstays
gibtsNicht (unknown name)error, undefinedstays

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

html
<section class="mein-block" vn-strict-if>
  <div vn-if="overlay">…</div>
</section>

Differences to the standard mode (checked)

Standardwith vn-strict-if
Element removed onexactly falseany falsy value: false, 0, empty text, null, undefined
Unknown nameelement staysname counts as undefined, element is removed
Error in the expressionelement stayselement is removed
Math, String …availableavailable

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

html
<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

ResultEffect
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 errornothing

Example (from themes/vn-studio-src/components/menu1)

html
<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

html
<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 or null sets nothing.
  • Custom properties (--name) are discarded: they cannot be set this way ({'--k': 1} has no effect). Write them as an ordinary style attribute 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)

html
<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

html
<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 isThe classes end up on
a container with vn-buttonsevery .btn in it
a container with vn-menuevery .nav-link and .dropdown-item in it
otherwisethe 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

html
<div class="vn-overlay" vn-if="overlay" opacity="{{overlayOpacity}}" bg-color="{{overlayColor}}"></div>

Attributes

NameValueMeaning
opacitynumber 0 to 1becomes the inline style opacity
bg-colorcolorbecomes 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.

html
<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.

html
<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

html
<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, a video or (for a container without a default video) the attribute data-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> (i counts 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 becomes player.vimeo.com/video/…; a file (.mp4, .webm, .ogv, .m4v, a file: address or assets/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

html
<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

html
<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-icon is therefore only needed for other elements.
  • On import the program assigns data-vn-icon-id="iconN" and removes the marker. All classes except bi and bi-… 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.

html
<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.

html
<a class="btn btn-primary" href="#" data-vn-popup-close>Schließen</a>

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

html
<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.

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.

html
<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.

AttributeSet onPurpose
data-vn-text-id="tN"every editable textstable identifier (key of the text changes)
data-vn-image-key="feld"<img src="{{feld}}"> and the root element with a background widgeta click opens the image selection for this field
data-vn-free-image-id="fiN"fixed images in the markupreplacement by a click
data-vn-button-id="btnN", data-vn-btn-extra-classesevery <a class="btn">button dialog; extra classes are kept
data-vn-icon-id="iconN", data-vn-icon-extra-classesevery iconicon 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 notationTodayNote
mbr-parametersvn-parameterstag; both are read
mbr-ifvn-if
mbr-classvn-class
mbr-stylevn-style
mbr-theme-stylevn-theme-styleon import only for themes with display font sizes; otherwise the attribute stays without effect
mbr-buttonsvn-buttons
mbr-menuvn-menu
mbr-videovn-video
mbr-icondata-vn-icon
mbr-articlevn-article
{{mbr-id}}{{vn-id}}both are replaced
class mbr-overlayclass vn-overlayboth 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:

ClassMeaning for the program
mbr-text, mbr-section-title, mbr-title, mbr-fonts-styletext 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-imagefallback image layer that the program inserts itself for data-bg-video
mbr-parallax-backgroundtriggers 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.