VN-Designer Entwickler-Dokumentation
04

Direktiven und Markierungen

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 und weitere Attribute im Template, die Regeln der Ausdrücke und eine Liste der älteren Schreibweisen.

Überblick#

Direktiven sind Attribute, die das Programm beim Zeichnen eines Blocks auswertet und danach aus dem Markup entfernt. Sie machen ein statisches Template abhängig von den Werten der Eigenschaften: ein Element ein- oder ausblenden, Klassen oder Stile bedingt setzen.

So läuft das Zeichnen eines Blocks (makeGenericRenderer in src/renderer.js):

  1. <vn-parameters> wird entfernt.
  2. {{vn-id}} wird durch die Kennung der Instanz ersetzt.
  3. Jeder {{ausdruck}} wird ausgewertet und durch sein Ergebnis ersetzt (Platzhalter).
  4. Das Ergebnis wird als HTML gelesen.
  5. Die Direktiven laufen über alle Elemente in Dokumentreihenfolge. Je Element in dieser Reihenfolge: vn-if, vn-class, vn-style, vn-theme-style, dann die Regel für vn-overlay.
  6. Die Wurzel bekommt die Instanzklasse und, falls sie keine hat, eine id. Das LESS wird übersetzt.

Weil Schritt 3 vor Schritt 5 liegt, sind Platzhalter auch in Direktiven möglich, aber meist unnötig: der Ausdruck in vn-if kennt die Werte ohnehin.

DirektiveWirkung
vn-ifElement entfernen
vn-strict-ifMarkiert den Block: vn-if prüft streng
vn-classKlassen bedingt hinzufügen
vn-styleInline-Stile bedingt setzen
vn-theme-styleTheme-Klassen ergänzen
vn-overlayAbdunklungsfläche mit opacity und bg-color
vn-buttons, vn-menuMarker für vn-theme-style
vn-videoVideobaustein mit Adressfeld im Panel
vn-articleerweiterbare Liste
data-vn-iconSymbol-Element kennzeichnen

Ausdrücke#

Der Text einer Direktive (und jedes {{…}}) ist ein JavaScript-Ausdruck. Er sieht alle Werte des Blocks unter ihrem Namen und die Hilfen vnEnc und vnEmbed. Technisch ist er der Rumpf von new Function(…namen, 'return (' + ausdruck + ');') (evalExpr in src/parser.js).

Regeln (alle geprüft)

  • Ein Fehler im Ausdruck (Syntaxfehler, unbekannter Name, Zugriff auf undefined.x) wird abgefangen und ergibt undefined, ohne Meldung.
  • undefined ist nicht false: vn-if entfernt in der Standardart nur bei genau false. Siehe vn-if.
  • Die Standardobjekte von JavaScript (Math, String, Number, JSON …) stehen zur Verfügung.
  • In einem HTML-Attribut schreiben Sie && als &amp;&amp;, < als &lt;. Beim Lesen entschlüsselt der HTML-Parser diese Schreibweise. Mit Anführungszeichen wechseln Sie gegen die des Attributs (vn-if="mode == 'list'").
  • Werte von range-Feldern sind Text. Vergleichen Sie mit n > 3 (JavaScript wandelt) oder rechnen Sie mit n * 1; n + 1 hängt an. Siehe range.
  • Werte von checkbox-Feldern sind true oder false, das Hintergrund-Widget ist ein Objekt (bg.type, bg.value, bg.parallax).

Direktiven#

vn-if#

Entfernt ein Element samt Inhalt, wenn der Ausdruck false ergibt.

Syntax

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

Beispiel (aus themes/vn-studio-src/components/header1)

html
<div class="vs-dim" vn-if="dim" style="background-color:{{dimColor}};opacity:{{dimOpacity}}"></div>

Was ein Ausdruck ergibt und was daraus wird (geprüft, Standardart)

Ausdruck (Wert)ErgebnisElement
showText (true)truebleibt
showText (false)falseentfernt
mode == 'b' (Vergleich falsch)falseentfernt
!!titel (leerer Text)falseentfernt
titel (leerer Text)""bleibt
n (Text "4" oder "0")Textbleibt
gibtsNicht (unbekannter Name)Fehler, undefinedbleibt

vn-if wirkt beim Zeichnen. Eine Eigenschaft ist deshalb nicht „versteckt“, sondern das Element existiert nicht mehr im Markup (und nicht im Export).

vn-strict-if#

Ein Marker an einem beliebigen Element des Blocks (üblich: am Wurzelelement). Er schaltet alle vn-if des Blocks auf die strenge Art. Das Attribut selbst wird entfernt.

Syntax

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

Unterschiede zur Standardart (geprüft)

Standardmit vn-strict-if
Element entfernt beigenau falsejedem falschen Wert: false, 0, leerer Text, null, undefined
Unbekannter NameElement bleibtName gilt als undefined, Element wird entfernt
Fehler im AusdruckElement bleibtElement wird entfernt
Math, String …verfügbarverfügbar

Ein range-Wert ist Text und gilt deshalb auch bei "0" als wahr: schreiben Sie Number(n) > 0. Die strenge Art gilt nur für vn-if; vn-class und vn-style bleiben unverändert. Sie wurde für Bausteine eingeführt, die aus anderen Projekten übernommen wurden, und wird von neuen Bausteinen selten gebraucht: schreiben Sie dort lieber eindeutige Ausdrücke.

vn-class#

Fügt einem Element Klassen hinzu, abhängig von den Werten. Bestehende Klassen bleiben; entfernen lässt sich damit nichts.

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>

Erlaubte Ergebnisse

ErgebnisWirkung
Objekt { 'klasse': wert }jeder Schlüssel mit wahrem Wert wird hinzugefügt; ein Schlüssel darf mehrere Klassen mit Leerzeichen enthalten
Liste [ … ]jedes Element wird wie ein einzelnes Ergebnis behandelt (Objekte, Texte, verschachtelte Listen)
Text 'a b'die Klassen werden hinzugefügt
alles andere (null, Zahl …) und ein Fehlernichts

Beispiel (aus 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#

Setzt Inline-Stile aus einem Objekt.

Syntax

html
<h2 vn-style="{'font-size': sizeTitle + 'rem', color: titelFarbe}">Titel</h2>

Regeln (geprüft)

  • Schlüssel dürfen camelCase (fontSize) oder mit Bindestrich in Anführungszeichen ('font-size') stehen.
  • Der Wert wird dem Element als Stil zugewiesen (el.style[eigenschaft] = wert). Ungültige Werte und unbekannte Eigenschaften werden still ignoriert. Ein leerer Text oder null setzt nichts.
  • Eigene Eigenschaften (--name) werden verworfen: sie lassen sich auf diesem Weg nicht setzen ({'--k': 1} bleibt ohne Wirkung). Schreiben Sie sie als normales style-Attribut mit Platzhalter: style="--k:{{k}}".
  • Ist das Ergebnis kein Objekt (zum Beispiel ein Text 'color:red'), geschieht nichts.
  • Der Stil steht am Element (Inline) und schlägt damit Regeln aus dem LESS, außer sie tragen !important.

Beispiel (nach dem Muster aus gallery-content: Schriftgröße je Überschrift aus einem Schieber, in der Schreibweise des Programms)

html
<h2 class="titel" vn-style="{'font-size': sizeTitle + 'rem'}">Titel</h2>

vn-theme-style#

Fügt Klassen aus den Theme-Einstellungen hinzu (zum Beispiel display-7 für die Schriftgröße eines Themes mit Display-Klassen).

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>

Wirkung (geprüft)

Das Element istDie Klassen landen auf
ein Behälter mit vn-buttonsjedem .btn darin
ein Behälter mit vn-menujedem .nav-link und .dropdown-item darin
sonstdem Element selbst

Enthält ein Behälter keine passenden Kinder, bekommt er die Klassen selbst. Das Attribut vn-theme-style wird danach entfernt; vn-buttons und vn-menu bleiben als Marker im Markup stehen.

vn-overlay#

Eine Fläche, die einen Hintergrund abdunkelt oder einfärbt. vn-overlay ist eine Klasse; zwei Attribute steuern sie.

Syntax

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

Attribute

NameWertBedeutung
opacityZahl 0 bis 1wird zum Inline-Stil opacity
bg-colorFarbewird zum Inline-Stil background-color

Zusätzlich setzt das Programm immer position: absolute; inset: 0; pointer-events: none. Die beiden Attribute werden danach entfernt. Fehlt eines, setzt das Programm den zugehörigen Stil nicht.

Die Felder overlay, overlayColor, overlayOpacity legt das Programm automatisch an, wenn das Template das Wort overlay enthält (Automatische Overlay-Felder).

vn-buttons#

Ein Marker am Behälter einer Button-Gruppe. Er hat keine eigene Wirkung; er legt fest, wohin ein vn-theme-style am selben Element seine Klassen schreibt (auf jeden .btn). Das Attribut bleibt im Markup stehen. Mehr zu Buttons: Direkt bearbeitbare Inhalte.

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#

Ein Marker am Behälter von Menüpunkten (<ul vn-menu>). Er hat keine eigene Wirkung; mit vn-theme-style am selben Element gehen die Klassen an jeden .nav-link und .dropdown-item. Menüpunkte erkennt das Programm unabhängig davon an ihren Klassen, siehe Menüs.

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#

Kennzeichnet einen Behälter mit einem Video (iframe oder video). Das Programm macht daraus ein Adressfeld im Panel und baut die Adresse zur einbettbaren Adresse um.

Syntax

html
<div vn-video class="ratio ratio-16x9">
  <iframe src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"></iframe>
</div>

Verhalten (geprüft im Editor und im Export)

  • Der Behälter zählt nur, wenn er ein iframe, ein video oder (für einen Behälter ohne Vorgabevideo) das Attribut data-vn-video-empty="1" mit einem Wert trägt.
  • Für jeden Behälter erscheint im Panel eine Gruppe „Video“ (bei mehreren „Video 1“, „Video 2“ …) mit Adressfeld (YouTube, Vimeo oder Videodatei), „Videodatei wählen…“, „Automatisch starten“ und „Endlos wiederholen“. Gespeichert wird in _videoUrl<i>, _videoAuto<i>, _videoLoop<i> (i zählt die Behälter ab 0). Ohne Eingabe gilt die Adresse im Template; Vorgaben für Autostart und Wiederholung liest das Programm aus der Adresse (?autoplay=1, ?loop=1).
  • YouTube wird zu youtube-nocookie.com/embed/…, Vimeo zu player.vimeo.com/video/…; eine Datei (.mp4, .webm, .ogv, .m4v, file:-Adresse oder assets/videos/) wird zu <video controls playsinline preload="metadata">. Eine leere Adresse zeigt im Editor einen Hinweis, der im Export fehlt.
  • Im Editor startet nichts von selbst.
  • Zusätzlich wird jede iframe[data-src] im Block (Video im Popup, wird beim Öffnen geladen) auf die einbettbare Adresse umgestellt.

vn-article#

Kennzeichnet eine Liste (ul oder ol) als ein bearbeitbares Feld, in dem die Eingabetaste einen neuen Listeneintrag anlegt. Gleichwertig ist data-multiline.

Syntax

html
<ul vn-article>
  <li>Erster Punkt</li>
  <li>Zweiter Punkt</li>
</ul>

Die Einträge sind dann keine eigenen Textfelder. Verschachtelte Listen: nur die äußerste ist das Feld. Einzelheiten: Listenfelder.

data-vn-icon#

Kennzeichnet ein Element als Symbol, das der Nutzer im Editor per Klick austauschen kann (Symbol, Größe, Farbe, Link).

Syntax

html
<i class="bi bi-star-fill" data-vn-icon></i>
<span data-vn-icon class="mein-symbol"></span>

Verhalten (geprüft)

  • <i class="bi bi-…"> und <span class="bi bi-…"> werden auch ohne Marker erfasst, ausgenommen innerhalb von Text, Buttons und Menüsymbolen. data-vn-icon ist deshalb nur für andere Elemente nötig.
  • Beim Import vergibt das Programm data-vn-icon-id="iconN" und entfernt den Marker. Alle Klassen außer bi und bi-… bleiben als „Zusatzklassen“ erhalten.
  • Im Export entfällt die Kennung; das Symbol steht dort als <i class="bi bi-…">.

Mehr: Symbole.

vn-parameters#

Der Block mit den Eingabefeldern. Er ist keine Direktive, wird aber wie eine behandelt: er steht im Template, wird beim Zeichnen entfernt und exportiert nie. Siehe Eingabefelder.

Weitere Markierungen im Template#

Diese Attribute darf ein Autor im Template schreiben. Das Programm oder die mitgelieferten Skripte werten sie aus.

data-bg-video#

Trägt die Adresse eines Hintergrundvideos am Wurzelelement. Siehe Wurzelattribute.

data-vn-editor-only#

Das Element erscheint nur im Editor; der Export entfernt es. Ausführlich in Skripte in Blöcken.

html
<div class="vn-video-empty" data-vn-editor-only vn-if="!videoFile">Noch kein Video gewählt …</div>

data-vn-popup-close#

Ein Element mit diesem Attribut schließt das Popup, in dem der Block steht (zum Beispiel ein „Nein danke“-Knopf). Siehe Popup.

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

Sperrt ein iframe oder script im Export, bis der Besucher der Kategorie im VN Cookie-Consent zugestimmt hat. Gilt nur, wenn der Cookie-Hinweis des Projekts eingeschaltet ist.

Syntax

html
<iframe src="https://example.com/karte" data-vn-consent-category="functional"></iframe>

Werte: functional, statistics, marketing. Das Programm erkennt bekannte Dienste (Karten, YouTube, Analysewerkzeuge) selbst; das Attribut ist der Weg für alles andere. Beim Sperren schreibt es src nach data-vn-cc-src und setzt type="text/plain" bei Skripten. Siehe Cookie-Consent und Datenschutz.

An einem Link (<a>): öffnet die Cookie-Einstellungen. Der Link-Dialog schreibt es selbst, wenn der Nutzer „Cookie-Einstellungen öffnen“ wählt. Siehe Cookie-Einstellungen öffnen.

html
<a href="#" data-vn-cookie-settings>Cookie-Einstellungen</a>

data-vn-anim und data-vn-anim-t#

Eine Animation an einem Text oder Bild. Das Werkzeug „VN Animation“ setzt sie; im Export steht data-vn-anim="fadeUp" (Name der Animation) und data-vn-anim-t="scroll" (Auslöser: scroll, load oder hover) samt Inline-Variablen --vn-a, --vn-d, --vn-dl, --vn-e, --vn-n. Aus diesen Markierungen erzeugt der Export die @keyframes und das kleine Skript für „beim Sichtbarwerden“. Von Hand zu schreiben ist das nur sinnvoll, wenn Sie die Inline-Variablen ebenfalls schreiben; benutzen Sie dafür das Werkzeug.

data-multiline#

Wie vn-article: macht eine Liste zu einem Feld mit Zeilen-Eingabe. Siehe vn-article.

Vom Programm gesetzte Markierungen#

Diese Attribute setzt das Programm beim Import oder beim Zeichnen. Schreiben Sie sie nicht selbst; sie stehen im gespeicherten Template (und im Code-Editor) und verschwinden im Export.

AttributGesetzt anZweck
data-vn-text-id="tN"jedem bearbeitbaren Textstabile Kennung (Schlüssel der Text-Änderungen)
data-vn-image-key="feld"<img src="{{feld}}"> und dem Wurzelelement bei einem Hintergrund-WidgetKlick öffnet die Bildauswahl für dieses Feld
data-vn-free-image-id="fiN"festen Bildern im MarkupAustausch per Klick
data-vn-button-id="btnN", data-vn-btn-extra-classesjedem <a class="btn">Button-Dialog; Zusatzklassen bleiben erhalten
data-vn-icon-id="iconN", data-vn-icon-extra-classesjedem SymbolSymbol-Dialog

Alle fünf Gruppen werden beim Export eingebacken und entfernt. Wie sie entstehen und was sie bewirken: Direkt bearbeitbare Inhalte. Weitere, rein interne Attribute (data-vn-text-color, data-vn-svg, data-vn-tip-*, data-vn-cms*, data-vn-drag*) stehen in diesem Kapitel nicht; sie gehören zu den Werkzeugen und zum CMS.

Ältere Schreibweisen#

Das Programm nimmt beim Import Namen aus älteren Paketen noch an und schreibt sie um; beim Zeichnen versteht es beide Schreibweisen. Diese Liste dient nur der Kompatibilität. Neue Bausteine verwenden die VN-Namen.

Ältere SchreibweiseHeuteAnmerkung
mbr-parametersvn-parametersTag; beide werden gelesen
mbr-ifvn-if
mbr-classvn-class
mbr-stylevn-style
mbr-theme-stylevn-theme-stylebeim Import nur bei Themes mit Display-Schriftgrößen; sonst bleibt das Attribut wirkungslos stehen
mbr-buttonsvn-buttons
mbr-menuvn-menu
mbr-videovn-video
mbr-icondata-vn-icon
mbr-articlevn-article
{{mbr-id}}{{vn-id}}beide werden ersetzt
Klasse mbr-overlayKlasse vn-overlaybeide werden ausgewertet (die Klasse wird beim Import nicht umbenannt)

Diese Klassen bleiben beim Import unverändert, weil Theme-CSS und Plugins sie ansprechen. Das Programm kennt sie weiterhin:

KlasseBedeutung für das Programm
mbr-text, mbr-section-title, mbr-title, mbr-fonts-styleFließtext-Erkennung (zusätzlich zu den Tags h1 bis h6, p, li …) und Ziel der seitenweiten Schriftregeln
mbr-iconfont, mbri-…Symbol-Erkennung; die mbri-…-Klasse wird entfernt, das Symbol bleibt bis zur Auswahl leer
mbr-fallback-imageErsatzbild-Ebene, die das Programm bei data-bg-video selbst einfügt
mbr-parallax-backgroundlöst im Bootstrap-Theme-Modus das Parallax-Plugin aus

Attribute aus älteren Paketen, die das Programm nicht auswertet und die ohne Wirkung im Markup stehen bleiben: data-app-selector, data-app-placeholder, data-toolbar, always-top, not-draggable, position-absolute und group="…" am Wurzelelement.