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):
<vn-parameters>wird entfernt.{{vn-id}}wird durch die Kennung der Instanz ersetzt.- Jeder
{{ausdruck}}wird ausgewertet und durch sein Ergebnis ersetzt (Platzhalter). - Das Ergebnis wird als HTML gelesen.
- 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ürvn-overlay. - 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.
| Direktive | Wirkung |
|---|---|
vn-if | Element entfernen |
vn-strict-if | Markiert den Block: vn-if prüft streng |
vn-class | Klassen bedingt hinzufügen |
vn-style | Inline-Stile bedingt setzen |
vn-theme-style | Theme-Klassen ergänzen |
vn-overlay | Abdunklungsfläche mit opacity und bg-color |
vn-buttons, vn-menu | Marker für vn-theme-style |
vn-video | Videobaustein mit Adressfeld im Panel |
vn-article | erweiterbare Liste |
data-vn-icon | Symbol-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 ergibtundefined, ohne Meldung. undefinedist nichtfalse:vn-ifentfernt in der Standardart nur bei genaufalse. Siehe vn-if.- Die Standardobjekte von JavaScript (
Math,String,Number,JSON…) stehen zur Verfügung. - In einem HTML-Attribut schreiben Sie
&&als&&,<als<. 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 mitn > 3(JavaScript wandelt) oder rechnen Sie mitn * 1;n + 1hängt an. Siehe range. - Werte von
checkbox-Feldern sindtrueoderfalse, 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
<p vn-if="showText">Beschreibung</p>
<div vn-if="overlay && bg.type !== 'color'"></div>Beispiel (aus themes/vn-studio-src/components/header1)
<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) | Ergebnis | Element |
|---|---|---|
showText (true) | true | bleibt |
showText (false) | false | entfernt |
mode == 'b' (Vergleich falsch) | false | entfernt |
!!titel (leerer Text) | false | entfernt |
titel (leerer Text) | "" | bleibt |
n (Text "4" oder "0") | Text | bleibt |
gibtsNicht (unbekannter Name) | Fehler, undefined | bleibt |
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
<section class="mein-block" vn-strict-if>
<div vn-if="overlay">…</div>
</section>Unterschiede zur Standardart (geprüft)
| Standard | mit vn-strict-if | |
|---|---|---|
| Element entfernt bei | genau false | jedem falschen Wert: false, 0, leerer Text, null, undefined |
| Unbekannter Name | Element bleibt | Name gilt als undefined, Element wird entfernt |
| Fehler im Ausdruck | Element bleibt | Element wird entfernt |
Math, String … | verfügbar | verfü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
<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
| Ergebnis | Wirkung |
|---|---|
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 Fehler | nichts |
Beispiel (aus 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#
Setzt Inline-Stile aus einem Objekt.
Syntax
<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 odernullsetzt nichts. - Eigene Eigenschaften (
--name) werden verworfen: sie lassen sich auf diesem Weg nicht setzen ({'--k': 1}bleibt ohne Wirkung). Schreiben Sie sie als normalesstyle-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)
<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
<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 ist | Die Klassen landen auf |
|---|---|
ein Behälter mit vn-buttons | jedem .btn darin |
ein Behälter mit vn-menu | jedem .nav-link und .dropdown-item darin |
| sonst | dem 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
<div class="vn-overlay" vn-if="overlay" opacity="{{overlayOpacity}}" bg-color="{{overlayColor}}"></div>Attribute
| Name | Wert | Bedeutung |
|---|---|---|
opacity | Zahl 0 bis 1 | wird zum Inline-Stil opacity |
bg-color | Farbe | wird 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.
<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.
<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
<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, einvideooder (für einen Behälter ohne Vorgabevideo) das Attributdata-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>(izä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 zuplayer.vimeo.com/video/…; eine Datei (.mp4,.webm,.ogv,.m4v,file:-Adresse oderassets/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
<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
<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-iconist 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ßerbiundbi-…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.
<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.
<a class="btn btn-primary" href="#" data-vn-popup-close>Schließen</a>data-vn-consent-category#
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
<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.
data-vn-cookie-settings#
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.
<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.
| Attribut | Gesetzt an | Zweck |
|---|---|---|
data-vn-text-id="tN" | jedem bearbeitbaren Text | stabile Kennung (Schlüssel der Text-Änderungen) |
data-vn-image-key="feld" | <img src="{{feld}}"> und dem Wurzelelement bei einem Hintergrund-Widget | Klick öffnet die Bildauswahl für dieses Feld |
data-vn-free-image-id="fiN" | festen Bildern im Markup | Austausch per Klick |
data-vn-button-id="btnN", data-vn-btn-extra-classes | jedem <a class="btn"> | Button-Dialog; Zusatzklassen bleiben erhalten |
data-vn-icon-id="iconN", data-vn-icon-extra-classes | jedem Symbol | Symbol-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 Schreibweise | Heute | Anmerkung |
|---|---|---|
mbr-parameters | vn-parameters | Tag; beide werden gelesen |
mbr-if | vn-if | |
mbr-class | vn-class | |
mbr-style | vn-style | |
mbr-theme-style | vn-theme-style | beim Import nur bei Themes mit Display-Schriftgrößen; sonst bleibt das Attribut wirkungslos stehen |
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}} | beide werden ersetzt |
Klasse mbr-overlay | Klasse vn-overlay | beide 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:
| Klasse | Bedeutung für das Programm |
|---|---|
mbr-text, mbr-section-title, mbr-title, mbr-fonts-style | Fließ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-image | Ersatzbild-Ebene, die das Programm bei data-bg-video selbst einfügt |
mbr-parallax-background | lö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.