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.
<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
idblk-<Block-Kennung>, oder die vom Nutzer gesetzte Anker-ID. Trägt die Wurzel selbst eineid, 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>ohnesrc) 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
<nav global once="menu" class="navbar vn-menu"> … </nav>
<footer global once="footers" class="vn-footer"> … </footer>Attribute
| Name | Wert | Standard | Bedeutung |
|---|---|---|---|
global | Schalter | – | 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.
| Wert | Bedeutung |
|---|---|
menu | Gruppe „Menü“: der Block steht im Export über dem Seiteninhalt |
footers | Gruppe „Fußzeile“: der Block steht darunter |
| anderer Text | Gruppe 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
<section class="mein-header" data-bg-video="{{bg.type == 'video' && 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 HTMLdata-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: Wurzelposition: relative; overflow: hidden, Ebene absolut und füllend,.container/.container-fluidaufz-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
<h2>{{titel}}</h2>
<div style="min-height:{{hoehe}}vh"></div>
<img src="{{foto}}" alt="">Beispiel (aus themes/vn-studio-src/components/header1)
<section class="vn-hero" vn-class="{'vs-fullscreen': fullScreen}" style="min-height:{{hoehe}}vh">Was aus dem Ergebnis wird (geprüft)
| Ergebnis des Ausdrucks | eingesetzt als |
|---|---|
| Text, Zahl | der Text |
true, false | true, 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.
<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
&&(&&),<,>,",'und&vor der Auswertung zurück:data-bg-video="{{bg.type == 'video' && bg.value.url}}"funktioniert. range-Werte sind Text:{{n + 1}}ergibt bein = "4"den Text41;{{n * 2}}ergibt8(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):
| Ausdruck | Bild | Farbe | Video |
|---|---|---|---|
{{bg.type}} | image | color | video |
{{bg.value}} | die Bildadresse | #rrggbb | [object Object] |
{{bg.value.url}} | die Bildadresse | – | die Videoadresse |
{{bg.parallax}} | true/false | false | false |
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.
<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
<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
<h1 data-swapwords="{{vnEnc(swapWords)}}">…</h1>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.
<iframe src="{{vnEmbed(videoUrl)}}" allowfullscreen></iframe>| Eingabe | Ergebnis |
|---|---|
https://youtu.be/dQw4w9WgXcQ | https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?rel=0&modestbranding=1&playsinline=1 |
https://vimeo.com/76979871 | https://player.vimeo.com/video/76979871 |
| andere Adresse | unverä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).
<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}}";ergibtvar s = "2";). - Ein Wert mit
"bricht ein Attribut; ein Wert mit<oder>kann das Markup ändern. Verwenden Sie bei Texten aus dem PanelvnEncoder setzen Sie sie nur in Textinhalt ein. - Jedes
{{ … }}im Template wird als Ausdruck ausgewertet, auch in JavaScript-Code. Eine Folge{{oder}}im Skript (zum Beispielfunction(){{…}}oder ein verschachtelter Objekt-Ausdruck) liefert Unsinn oder leeren Text. Schreiben Sie Klammern im Skript mit Leerzeichen ({ {,} }) oder auf getrennten Zeilen.
Bilder und Links#
Wie Bilder und Links im Editor austauschbar werden, beschreibt Direkt bearbeitbare Inhalte. Für das Template gilt:
- Bildfeld:
<img src="{{feld}}">, wobeifeldein Feldtype="image"ist. Genau ein Platzhalter alssrc(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}});"(imstyleoder invn-style) markiert dieses Element für das Widgetbg. Zusätzlich trägt bei einem Hintergrund-Widget immer die Wurzel diese Markierung. - Festes Bild:
<img src="https://…">oder einstylemitbackground-image: url(…)ohne Platzhalter ist ein freies Bild und lässt sich per Klick ersetzen. - Links: Platzhalter in
hrefgehen 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 zuassets/…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…) undbi 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 dasdata-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.
| Editor | Export | |
|---|---|---|
<vn-parameters> | entfernt | entfernt |
{{…}}, Direktiven | ausgewertet | ausgewertet (gleiches Ergebnis) |
| Texte, Bilder, Knöpfe, Symbole | contenteditable, Kennungen data-vn-…, Klassen wie vn-editable-text; ein Klick öffnet Dialoge | Änderungen eingebacken, alle Editor-Kennungen entfernt |
data-vn-editor-only | sichtbar | entfernt (Skripte) |
<script> im Block | läuft über Stellvertreter für window, document, Zeitgeber; jedes Neuzeichnen beendet die alten Zeitgeber | steht unverändert in der Seite (Skripte) |
| Videos mit Autostart | starten nicht | starten (stumm) |
Hintergrundvideo (data-bg-video) | Ersatzbild | Video über vn-bgvideo.js |
| Bildadressen | file:///… | 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 nicht | wird durch den rohen PHP-Code ersetzt; die Seite braucht die Endung .php (das Programm bietet die Umbenennung an) |
| Popup, CMS | Rahmen und Kennzeichnung | Popup-Behälter, CMS-Markierungen und PHP-Aufrufe |