VN-Designer Entwickler-Dokumentation
02

Das Template (template.html)

Aufbau von template.html: Wurzelelement und seine Attribute, Platzhalter {{…}} mit Ausdrücken und Hilfsfunktionen, Bilder und Links, Bootstrap, seitenweite Blöcke und was im Editor und im Export geschieht.

Aufbau#

template.html beschreibt das Markup eines Blocks. Es besteht aus einem Wurzelelement, das alles andere umschließt. Im Wurzelelement stehen zuerst der Block <vn-parameters> (die Eingabefelder, siehe Eingabefelder) und danach das eigentliche Markup mit Platzhaltern und Direktiven.

html
<section class="mb-karte">
  <vn-parameters>
    <header>Größe</header>
    <input type="range" title="Abstand" name="abstand" min="0" max="8" step="1" value="3">
  </vn-parameters>
  <div class="container">
    <h2>Willkommen</h2>
    <p vn-if="abstand > 1">Text mit Abstand {{abstand}}</p>
  </div>
</section>

Das Wurzelelement#

Das erste Element der Datei ist die Wurzel (section, bei Menü und Fußzeile auch nav oder footer). Das Programm hängt an die Wurzel an, was den Block als Instanz kennzeichnet:

  • die Instanzklasse vn-imp-<alias>-<Block-Kennung> (auf ihr beruht das Block-CSS, siehe LESS: Bereich und Wurzel),
  • die id blk-<Block-Kennung>, oder die vom Nutzer gesetzte Anker-ID. Trägt die Wurzel selbst eine id, bleibt sie erhalten.

Der Parameterblock#

<vn-parameters> gehört in die Wurzel (nicht davor) und wird beim Zeichnen entfernt. Einzelheiten: Eingabefelder.

Markup#

Alles Weitere ist gewöhnliches HTML5 mit diesen Zusätzen:

  • Platzhalter {{…}} setzen Werte ein (Platzhalter).
  • Direktiven (vn-if, vn-class, vn-style …) machen Elemente von Werten abhängig (Direktiven).
  • Klassen von Bootstrap 5 und Bootstrap Icons stehen zur Verfügung (Bootstrap).
  • Skripte (<script> ohne src) bleiben im Markup; siehe Skripte in Blöcken.
  • Texte, Bilder, Knöpfe und Symbole werden im Editor automatisch bearbeitbar (Direkt bearbeitbare Inhalte).

Attribute am Wurzelelement#

Diese Attribute wertet das Programm am Wurzelelement aus.

global#

Macht den Block seitenweit: er steht einmal im Projekt und erscheint auf jeder Seite (Menü, Fußzeile).

Syntax

html
<nav global once="menu" class="navbar vn-menu"> … </nav>
<footer global once="footers" class="vn-footer"> … </footer>

Attribute

NameWertStandardBedeutung
globalSchalter–Block ist seitenweit. Muss am allerersten Element der Datei stehen (geprüft: ein vorgestellter <vn-parameters>-Block oder ein umschließendes div verhindert die Erkennung)

Alles Weitere (Gruppen, Lage im Export, Ersetzen) steht unter Seitenweite Blöcke.

once#

Name der Gruppe eines seitenweiten Blocks. Von jeder Gruppe gibt es höchstens einen Block im Projekt: ein neu eingefügter ersetzt den alten.

WertBedeutung
menuGruppe „Menü“: der Block steht im Export über dem Seiteninhalt
footersGruppe „Fußzeile“: der Block steht darunter
anderer TextGruppe mit diesem Namen; steht oben, wenn der Name menu, nav oder header enthält (Groß-/Kleinschreibung egal), sonst unten

once ohne global hat keine Wirkung (geprüft). Ohne once heißt die Gruppe global.

group#

group="Content" am Wurzelelement kommt in vielen Paketen vor. Das Programm wertet es nicht aus. Die Kategorie in der Auswahl kommt aus _group in params.json (Bezeichner). Sie dürfen das Attribut weglassen.

plugins#

plugins="DropDown, TouchSwipe" nennt die Plugin-Ordner, die ein Baustein aus einem Bootstrap-4-Theme braucht. Es wirkt nur im Bootstrap-Theme-Modus des Projekts und nur an einem <section>: der Export lädt dann zusätzlich die Skripte dieser Plugins (siehe Bootstrap-Modus). Für Bausteine auf dem mitgelieferten Bootstrap 5 ist es überflüssig.

data-bs-version#

data-bs-version="5.1" kennzeichnet einen Baustein als für Bootstrap 5 gebaut. Die einzige Wirkung: Kommt ein solcher Baustein in ein Projekt, das im Bootstrap-Theme-Modus (Bootstrap 4) läuft, zeigt das Programm einen Hinweis, dass er anders aussehen kann.

data-bg-video#

Trägt die Adresse eines Hintergrundvideos für den ganzen Block. Der Wert ist üblicherweise ein Platzhalter, der nur bei gewähltem Video eine Adresse ergibt.

Syntax

html
<section class="mein-header" data-bg-video="{{bg.type == 'video' &amp;&amp; bg.value.url}}">
  <vn-parameters>
    <fieldset name="bg">
      <input type="video" title="Video" value="">
      <input type="image" title="Bild (Ersatzbild)" value="../_images/ersatz.jpg" selected>
      <input type="color" title="Farbe" value="#111111">
    </fieldset>
  </vn-parameters>
  …
</section>

Verhalten (geprüft)

  • Ist der Wert leer oder false, undefined, null, 0, geschieht nichts (bei anderer Hintergrundart steht im HTML data-bg-video="false").
  • Sonst fügt das Programm als erstes Kind der Wurzel eine <div>-Ebene für das Ersatzbild ein (ihre Klasse steht unter Ältere Schreibweisen) und ergänzt CSS: Wurzel position: relative; overflow: hidden, Ebene absolut und füllend, .container/.container-fluid auf z-index: 2. Die Regeln stehen in :where(…), damit ein eigenes Theme-CSS Vorrang hat.
  • Im Export lädt die Seite vendor/vn-bgvideo/vn-bgvideo.js, wenn mindestens ein Block eine Video-Adresse trägt. Das Skript baut das Video (YouTube, Vimeo oder Datei) beim Anzeigen der Seite ein. Bei eingeschaltetem VN Cookie-Consent laden YouTube und Vimeo ab Version 1.3.100 erst nach Zustimmung zu „Marketing“ (bis dahin bleibt das Ersatzbild stehen; siehe Wiedergabe auf der Seite). Im Editor sieht man nur das Ersatzbild.

vn-strict-if#

Ein Marker an der Wurzel (oder einem beliebigen Element), der vn-if im ganzen Block streng macht. Siehe vn-strict-if.

id und class#

Eigene class-Werte bleiben, die Instanzklasse kommt hinzu. Eine eigene id bleibt erhalten; ohne id setzt das Programm blk-<Block-Kennung> bzw. die Anker-ID des Nutzers. Verwenden Sie in Verweisen innerhalb des Blocks {{vn-id}} (Platzhalter), nicht feste IDs: derselbe Block kann mehrfach auf einer Seite stehen.

Nicht ausgewertete Attribute#

Diese Attribute kommen in älteren Paketen am Wurzelelement vor. Das Programm lässt sie unbeachtet; sie bleiben im Markup stehen und schaden nicht: group, always-top, not-draggable, position-absolute, data-app-selector, data-app-placeholder, data-toolbar.

Platzhalter#

Ein Platzhalter {{ausdruck}} wird beim Zeichnen durch sein Ergebnis ersetzt. Das gilt überall im Template: in Text, in Attributen, in <script> und <style>. Der Ausdruck ist JavaScript (Ausdrücke) und kennt alle Werte des Blocks unter ihrem Namen.

{{name}}#

Setzt den Wert eines Felds ein.

Syntax

html
<h2>{{titel}}</h2>
<div style="min-height:{{hoehe}}vh"></div>
<img src="{{foto}}" alt="">

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

html
<section class="vn-hero" vn-class="{'vs-fullscreen': fullScreen}" style="min-height:{{hoehe}}vh">

Was aus dem Ergebnis wird (geprüft)

Ergebnis des Ausdruckseingesetzt als
Text, Zahlder Text
true, falsetrue, false
undefined, null (auch bei einem Fehler im Ausdruck)leerer Text, ohne Meldung
Liste [1,2]1,2
Objekt[object Object]

Ausdrücke#

Zwischen den Klammern darf jeder JavaScript-Ausdruck stehen, nicht nur ein Name.

html
<p>{{ n > 3 ? 'viel' : 'wenig' }}</p>
<div style="height:{{logoSize * 1.8}}rem"></div>
<a data-n="{{ Number(anzahl) + 1 }}">…</a>
  • Leerraum um den Ausdruck wird entfernt.
  • In Attributen wandelt das Programm &amp;&amp; (&&), &lt;, &gt;, &quot;, &#39; und &amp; vor der Auswertung zurück: data-bg-video="{{bg.type == 'video' &amp;&amp; bg.value.url}}" funktioniert.
  • range-Werte sind Text: {{n + 1}} ergibt bei n = "4" den Text 41; {{n * 2}} ergibt 8 (geprüft).
  • Die Standardobjekte von JavaScript (Math, String …) sind verfügbar.
  • Ein Fehler ergibt leeren Text; es gibt keine Fehlermeldung. Prüfen Sie ungewöhnliche Ausdrücke im Editor.

Objektfelder#

Das Hintergrund-Widget liefert ein Objekt. Im Template stehen diese Felder (Name des Widgets hier bg):

AusdruckBildFarbeVideo
{{bg.type}}imagecolorvideo
{{bg.value}}die Bildadresse#rrggbb[object Object]
{{bg.value.url}}die Bildadresse–die Videoadresse
{{bg.parallax}}true/falsefalsefalse

Bei Bild verhält sich bg.value im Template wie die Adresse als Text und hat .url (geprüft): beide Schreibweisen url({{bg.value}}) und url({{bg.value.url}}) funktionieren.

html
<div class="deckel" style="background-image: url({{bg.value}});"></div>

Siehe Hintergrund-Widget.

{{vn-id}}#

Ergibt die Kennung der Instanz: blk-<Block-Kennung> oder die Anker-ID des Nutzers. Damit bilden Sie IDs, die auch bei mehreren gleichen Blöcken auf einer Seite eindeutig bleiben. Die Ersetzung gilt im ganzen Template, auch im Text von <script>.

Syntax

html
<button class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#{{vn-id}}-nav"></button>
<div class="collapse navbar-collapse" id="{{vn-id}}-nav"> … </div>

vnEnc(text)#

Maskiert einen Text für ein data-…-Attribut: Ergebnis ist encodeURIComponent(String(wert)); undefined und null ergeben leeren Text. Im Skript lesen Sie mit decodeURIComponent zurück.

Syntax

html
<h1 data-swapwords="{{vnEnc(swapWords)}}">…</h1>
js
var worte = decodeURIComponent(h.getAttribute("data-swapwords") || "").split("|");

Beispiel (aus gallery-content/vn-kinetic-theme, Baustein „Hero 1“): Die Wörter kommen aus einem Textfeld des Panels, das beliebige Zeichen enthalten darf. Mehr: Text-Daten in Attributen.

vnEmbed(adresse)#

Wandelt eine YouTube- oder Vimeo-Adresse in die einbettbare Adresse um; andere Adressen bleiben unverändert.

html
<iframe src="{{vnEmbed(videoUrl)}}" allowfullscreen></iframe>
EingabeErgebnis
https://youtu.be/dQw4w9WgXcQhttps://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?rel=0&modestbranding=1&playsinline=1
https://vimeo.com/76979871https://player.vimeo.com/video/76979871
andere Adresseunverändert

Platzhalter in Knöpfen#

In einem Knopf (<a class="btn …">) werden Platzhalter in Text und href nicht ausgewertet. Das Programm baut jeden Knopf aus seinem Vorgabewert und den Änderungen des Nutzers im Knopf-Dialog neu auf; der Vorgabewert ist der rohe Text aus dem Template, also steht {{name}} wörtlich auf der Seite (geprüft im Editor und im Export).

html
<a class="btn btn-primary" href="{{ziel}}">{{beschriftung}}</a>   

Was funktioniert: ein Platzhalter in einem gewöhnlichen Link (<a href="{{ziel}}">Text {{x}}</a> ohne die Klasse btn), in einem <button> und in Attributen wie title oder alt. Den Knopftext und das Ziel pflegt der Nutzer am Knopf selbst.

Platzhalter in Skripten und Attributen#

Die Ersetzung geschieht auf dem Text des Templates, vor dem Lesen als HTML. Daraus folgt:

  • Ein Platzhalter funktioniert auch im Inhalt von <script> (var s = "{{n}}"; ergibt var s = "2";).
  • Ein Wert mit " bricht ein Attribut; ein Wert mit < oder > kann das Markup ändern. Verwenden Sie bei Texten aus dem Panel vnEnc oder setzen Sie sie nur in Textinhalt ein.
  • Jedes {{ … }} im Template wird als Ausdruck ausgewertet, auch in JavaScript-Code. Eine Folge {{ oder }} im Skript (zum Beispiel function(){{…}} oder ein verschachtelter Objekt-Ausdruck) liefert Unsinn oder leeren Text. Schreiben Sie Klammern im Skript mit Leerzeichen ({ {, } }) oder auf getrennten Zeilen.

Wie Bilder und Links im Editor austauschbar werden, beschreibt Direkt bearbeitbare Inhalte. Für das Template gilt:

  • Bildfeld: <img src="{{feld}}">, wobei feld ein Feld type="image" ist. Genau ein Platzhalter als src (ohne weiteren Text) markiert das Bild; ein Klick darauf öffnet im Editor die Bildauswahl für dieses Feld.
  • Hintergrundbild: style="background-image: url({{bg.value}});" (im style oder in vn-style) markiert dieses Element für das Widget bg. Zusätzlich trägt bei einem Hintergrund-Widget immer die Wurzel diese Markierung.
  • Festes Bild: <img src="https://…"> oder ein style mit background-image: url(…) ohne Platzhalter ist ein freies Bild und lässt sich per Klick ersetzen.
  • Links: Platzhalter in href gehen bei gewöhnlichen Links (<a href="{{ziel}}">), nicht bei Knöpfen (siehe oben).
  • Dateiadressen: Im Projekt stehen Bilder als file:///…/assets/…. Der Export schreibt jede solche Adresse in HTML und CSS zu assets/… um und kopiert die Dateien mit; nur referenzierte Dateien kommen mit.

Bootstrap und Klassen#

Das Programm liefert Bootstrap 5.0.1 (Raster, Hilfsklassen, Komponenten) und die Bootstrap Icons. Beides steht im Editor und in jeder exportierten Seite zur Verfügung (vendor/bootstrap.min.css, vendor/bootstrap.bundle.min.js, vendor/bootstrap-icons/); Bausteine müssen nichts einbinden.

  • Verwenden Sie die Klassen von Bootstrap 5 (container, row, col-md-6, d-flex, gap-3, btn, btn-primary …) und bi bi-<name> für Symbole.
  • jQuery steht nicht zur Verfügung (nur im Bootstrap-Theme-Modus für Bootstrap-4-Themes).
  • Bootstrap-JS-Komponenten funktionieren über data-bs-…-Attribute (data-bs-toggle="collapse"). Attribute der Version 4 (data-toggle, data-target …) ergänzt der Import um das data-bs-…-Gegenstück (Bootstrap-Attribute).
  • Vergeben Sie eigene Klassennamen mit Kürzel des Blocks (mb-karte, vnkn-hero). Das Block-CSS ist zwar auf die Instanz begrenzt, Klassen aus Theme-CSS und Bootstrap sind es nicht.

Seitenweite Blöcke#

Menü und Fußzeile gehören auf jede Seite. Ein Block mit global am Wurzelelement liegt nicht in einer Seite, sondern in der Liste der globalen Blöcke; im Export steht er auf jeder Seite, Menü-Gruppen oben, alle anderen unten, und sein CSS nur einmal in style.css. Alles Weitere: Seitenweite Blöcke: global und once.

Editor und Export#

Dasselbe Template wird zweimal gezeichnet: für die Arbeitsfläche und für den Export. Beide benutzen dieselbe Zeichenfunktion (render); danach unterscheiden sie sich.

EditorExport
<vn-parameters>entferntentfernt
{{…}}, Direktivenausgewertetausgewertet (gleiches Ergebnis)
Texte, Bilder, Knöpfe, Symbolecontenteditable, Kennungen data-vn-…, Klassen wie vn-editable-text; ein Klick öffnet DialogeÄnderungen eingebacken, alle Editor-Kennungen entfernt
data-vn-editor-onlysichtbarentfernt (Skripte)
<script> im Blockläuft über Stellvertreter für window, document, Zeitgeber; jedes Neuzeichnen beendet die alten Zeitgebersteht unverändert in der Seite (Skripte)
Videos mit Autostartstarten nichtstarten (stumm)
Hintergrundvideo (data-bg-video)ErsatzbildVideo über vn-bgvideo.js
Bildadressenfile:///…assets/…
CSS@layer vn-blocks, Bootstrap und Theme in @scope (#canvas)eine style.css, keine Layer (Rangfolge)
PHP (<script type="text/x-vn-php">)läuft nichtwird durch den rohen PHP-Code ersetzt; die Seite braucht die Endung .php (das Programm bietet die Umbenennung an)
Popup, CMSRahmen und KennzeichnungPopup-Behälter, CMS-Markierungen und PHP-Aufrufe