VN-Designer Entwickler-Dokumentation
07

Skripte in Blöcken und Themes

Wie ein Block JavaScript mitbringt, wie er den Editor erkennt, was der Editor mit Skripten tut, wie Cookie-Consent und Datenschutz angebunden werden, welche Bibliotheken unter vendor/ mitgeliefert werden und welche Fallen es gibt.

Überblick#

Ein Block bringt JavaScript als Inline-<script> im Template mit. Es gibt keine eigene JS-Datei je Block oder Theme. Das Skript steht meist am Ende des Wurzelelements und wird mit dem Template ausgeliefert: im Editor, in der Vorschau und im Export.

OrtLäuft das Skript?Wie
Export (publish/), Vorschau im Browser und Live-Vorschauja, normalDie Seite wird über einen lokalen Server ausgeliefert (preview-server.cjs), das Skript läuft wie auf der echten Seite
Editor (Arbeitsfläche)ja, abgeschirmtsrc/editor-scripts.js führt Inline-Skripte nach jedem Render mit Stellvertretern aus (siehe Verhalten im Editor); abschaltbar
Code-EditorneinDort wird nur das Template-HTML gezeigt

Reihenfolge einer exportierten Seite (aus buildExportHtml):

  1. <head>: Bootstrap-CSS, Bootstrap-Icons-CSS, die CSS-Dateien der benutzten Laufzeit-Bibliotheken, style.css.
  2. <body>: der HTML-Code aller Blöcke der Seite in Reihenfolge, jeweils mit ihren Inline-Skripten.
  3. Danach vendor/bootstrap.bundle.min.js, dann die Skripte der Laufzeit-Bibliotheken (Lightbox, Cookie-Consent, Popup, CMS, Video …), dann Skripte des Nutzers.

Skripte in Blöcken#

Inline-Skript im Template#

Syntax

html
<section class="va va-inhalt" group="Content">
  <vn-parameters> … </vn-parameters>
  <div class="va-in" data-anim="{{anim}}"> … </div>
  <script>(function(){
    [].forEach.call(document.querySelectorAll(".va-in"), function(R){
      if (R.__vaInit) return; R.__vaInit = 1;       /* einmalig je Element */
      if (R.closest("#canvas")) return;              /* im Editor nichts tun */
      /* … Effekt … */
    });
  })();</script>
</section>

(Muster aus gallery-content/vn-bloecke/src/artikel/inhalt/template.html; dort steht der Merker als data-va-init-Attribut, empfohlen ist die JS-Eigenschaft)

RegelBeschreibung
OrtInnerhalb des Wurzelelements, meist als letztes Kind
ArtNur <script> ohne src und ohne fremden type wird im Editor ausgeführt (type leer, text/javascript, application/javascript, module)
Fremde Typentype="text/x-vn-php" (geschützter PHP-Code) und JSON-Datenblöcke werden vom Editor nicht ausgeführt und vom Cookie-Consent nicht angefasst
Platzhalter{{…}} wird im gesamten Template ersetzt, auch im Skript-Text. Eine doppelte öffnende Klammer im Skript (zum Beispiel ein Objektliteral in einem Objektliteral, {{a:1}}) wird als Ausdruck ausgewertet: schreiben Sie { { oder vermeiden Sie die Folge
Bedingungenvn-if am <script> ist möglich; fällt es weg, fehlt das Skript
Externe Dateien<script src="…"> läuft im Export, im Editor nicht. Fremde Server (CDN) sind aus Datenschutzgründen zu vermeiden

Einmal-Initialisierung#

Das Skript soll alle Elemente seines Blocks im Dokument finden und jedes nur einmal initialisieren. Den Merker setzen Sie als JavaScript-Eigenschaft am Element, nicht als data--Attribut.

Syntax

js
(function () {
  var roots = document.querySelectorAll(".mein-block");
  Array.prototype.forEach.call(roots, function (box) {
    if (box.vnInit) return;     // schon erledigt (Eigenschaft, kein Attribut)
    box.vnInit = 1;
    if (box.closest("#canvas")) return;
    // … Initialisierung …
  });
})();
MerkerEignungGrund
JS-Eigenschaft (box.vnInit = 1)empfohlenGehört dem Element, nie im HTML, nie im gespeicherten Template, nie im Export
data-…-AttributvermeidenDas Skript läuft über alle Elemente der Seite; ein älteres Block-Skript setzte das Attribut auf Elemente neuer Blöcke, und diese wurden dann nie initialisiert. Außerdem landet ein Attribut im DOM, das später gebacken werden kann
Globale Variable (window.fertig = true)nur für gemeinsame HilfsfunktionenIm Editor gilt window.… nur für einen Render-Durchgang (siehe unten); auf der echten Seite bleibt es für alle Blöcke stehen

Gemeinsamer Namensraum für mehrere Instanzen (aus dem Baustein „Video-Einbettung“):

js
(function () {
  var V = window.vfvd = window.vfvd || {};   // einmalig anlegen, später wiederverwenden
  if (!V.parse) {
    V.ed = function (e) { return !!(e && e.closest && e.closest("#canvas")); };
    V.parse = function (raw) { /* … */ };
  }
  // … je Instanz …
})();

Reihenfolge und Wartezeit#

Zur Laufzeit des Block-Skripts (Parsen von <body>) sind noch nicht vorhanden: window.bootstrap, window.vnCookieConsent, window.VNPopup, Elemente weiter unten auf der Seite. Warten Sie auf DOMContentLoaded oder load.

js
function late(fn) {
  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", fn);
  else fn();
}
late(function () {
  var cc = window.vnCookieConsent;          // jetzt da (wenn Cookie-Consent eingeschaltet ist)
  var BS = window.bootstrap;                // Bootstrap 5.0.1
});

Im Editor sind DOMContentLoaded und load bereits vorbei; der Editor ruft solche Rückrufe sofort (zeitversetzt) auf und meldet document.readyState === "complete". Dieselbe Schreibweise funktioniert deshalb an beiden Orten.

Marker data-vn-editor-only#

Elemente mit data-vn-editor-only sind Attrappen für den Editor. Der Export entfernt sie (publish.js: container.querySelectorAll('[data-vn-editor-only]').forEach(remove)). Typisch: Hinweiszeilen („Noch kein Video gewählt“), Beispielinhalte für PHP-Ausgaben, die im Editor nicht laufen.

Syntax

html
<div class="vn-bgvid-empty" data-vn-editor-only vn-if="!videoFile &amp;&amp; !videoUrl">
  Noch kein Video gewählt — im Eigenschaften-Panel unter „Video“ eine Datei wählen.
</div>
AttributWertBedeutung
data-vn-editor-onlySchalterDas Element erscheint im Editor und in der Block-Vorschau, nicht im Export

Editor-Erkennung#

Erkennung mit el.closest('#canvas')#

Die einzige verlässliche Erkennung ist die Lage im Canvas: Die Arbeitsfläche ist ein Element mit der ID canvas im selben Dokument wie das Programm (kein iframe). Ein Block-Element im Editor hat #canvas als Vorfahren, im Export und in der Vorschau nicht.

Syntax

js
var inEditor = !!el.closest("#canvas");
if (inEditor) return;        // oder nur den Effekt auslassen, Inhalt aber setzen
Wert von el.closest("#canvas")Bedeutung
ElementEditor (Arbeitsfläche)
nullExport, Vorschau oder Live-Vorschau

Editor, Vorschau und Export im Vergleich#

MerkmalEditor (Arbeitsfläche)Vorschau und Live-VorschauExport
Block-Skripteabgeschirmt, nach jedem Rendernormalnormal
el.closest("#canvas")Elementnullnull
window.bootstrapdada (nach den Block-Skripten)da (nach den Block-Skripten)
jQueryneinnein (nur im Bootstrap-Theme-Modus)nein (nur im Bootstrap-Theme-Modus)
Laufzeit-Bibliotheken (Lightbox, Consent, Popup …)nein (Ausnahme: VN Untermenü)ja, wie im Exportja, wenn benutzt
data-vn-editor-only-Elementesichtbarentferntentfernt
PHPläuft nicht (Attrappen)läuft über den lokalen Serverläuft auf Ihrem Server
Mail-Versand—an einen lokalen Mail-Fänger (.eml-Dateien)über Ihren SMTP-Server

Was nicht zur Erkennung taugt#

Geprüft in einer laufenden Instanz:

MittelErgebnis im EditorFolge
document.documentElement.classList.contains("is-builder")falseDas Programm setzt die Klasse nie; das Programm schaltet sie bewusst nicht global, um nicht bei jedem importierten Block .is-builder-Regeln zu aktivieren
document.body.classList.contains("is-builder")falsewie oben (nur die Lightbox beachtet sie)
document.currentScriptnullDer Editor führt Skripte über new Function aus; ein Skript, das sich per currentScript seinen Block sucht, braucht einen Rückfall (document.querySelector(…))
window.self !== window.topfalseEs gibt keinen iframe

Verhalten im Editor#

Stellvertreter statt freier Lauf#

Die Arbeitsfläche ist Teil des Programmfensters. Ein Block-Skript läuft deshalb nicht frei, sondern in einer Funktion, die die globalen Namen durch Stellvertreter überdeckt (new Function('document','window','location','setTimeout',…)). Dadurch kann ein Skript weder das Programm umleiten noch nach dem nächsten Render weiterlaufen.

Zugriff im SkriptVerhalten im Editor
setTimeout, setInterval, requestAnimationFrameRückrufe laufen nur, solange der Render-Durchgang gilt, in dem das Skript startete; jeder neue Render beendet alle Ketten des alten
document.addEventListener('DOMContentLoaded'/'load'/'readystatechange', fn) und dasselbe an windowRückruf läuft sofort (zeitversetzt, setTimeout 0)
window.onload = fnwird als Rückruf sofort ausgeführt
document.readyStateimmer complete
document.write, document.writelntut nichts
location.assign, .replace, .reload; location.href = …tut nichts; Lesen geht
alert, confirm, prompttun nichts (confirm liefert false, prompt null)
andere document-/window-Aufrufenormal (an das echte Objekt gebunden)
this, self, globalThis, window.windowder Stellvertreter

Fehler im Skript werden nur in die Konsole geschrieben (Block-Skript im Editor nicht ausgeführt: …) und stören die Arbeitsfläche nicht.

Neu-Rendern und Zeitgeber#

Bei jedem Render der Arbeitsfläche (renderCanvasNow) ruft das Programm zuerst stopBlockScripts() (Zeitgeber/Ketten des vorigen Durchgangs enden), baut alle Blöcke neu auf und führt danach, wenn alles im Dokument steht und das CSS gesetzt ist, die Inline-Skripte jedes Blocks aus. Fast jede Änderung im Panel löst einen Render aus: Das Skript läuft also oft neu, auf frischen Elementen.

window-Eigenschaften gelten nur einen Durchgang#

Was ein Block-Skript an window hängt (window.initialisiert = true, window.vfvd = {…}), landet in einem Speicher, der mit dem nächsten Render verworfen wird. Der Schutzschalter if (!window.fertig) { window.fertig = true; … } bliebe sonst stehen, und das Skript liefe nach dem ersten Neu-Rendern nie wieder an. Auf der echten Seite gibt es diese Beschränkung nicht.

Geprüft: Ein Skript, das window.__leak = 5 setzt, hinterlässt auf dem echten window nichts; nach stopBlockScripts() ist typeof window.initFlag wieder undefined.

Abschalten#

In den Seiten-Einstellungen gibt es den Schalter für Block-Skripte im Editor (siteSettings.editorScripts, Standard an). Aus: Block-Skripte laufen im Editor nie; Blöcke, die ihren sichtbaren Inhalt erst per JavaScript erzeugen, zeigen dann nur den Ausgangszustand.

Regeln für Skripte im Editor#

RegelBegründung
Alles, was DOM verschiebt, versteckt oder austauscht, im Editor nicht tun (No-op): Karussell-Umbau, Reveal mit opacity:0, Einklappen, KlonenSonst verschwindet der Inhalt oder lässt sich nicht mehr anklicken
Einen parameterabhängigen Anfangszustand trotzdem setzen (erstes Wort, Zähler-Endwert, Termin) und erst dann beendenWer if (closest('#canvas')) return; an den Anfang stellt, zeigt im Editor Änderungen im Panel nicht an (Fehlerbild „Schreibmaschine zeigt das neue Wort nicht“)
Den Inhalt eines Textfelds nie umschreiben (keine Buchstaben-<span>s, kein innerHTML auf data-vn-text-id-Elementen)Beim nächsten Tippen speichert das Programm den aktuellen innerHTML des Felds als Text (Eingabe-Ereignis); ein Zwischenzustand des Effekts würde zum gespeicherten Text
Keine Dauerläufer ohne Ende, die sich selbst nicht beendenZeitgeber werden zwar abgebrochen, aber Ereignis-Hörer an document/window bleiben bis zum Neuladen

Text-Animationen zur Laufzeit#

Effekte, die Text zerlegen oder umschreiben (Buchstaben einzeln einblenden, Zähler hochzählen, Schreibmaschine, Wörter wechseln), geschehen zur Laufzeit im Browser. Im gespeicherten HTML steht immer der vollständige, ruhige Text. So finden ihn Suchmaschinen, der Übersetzer, das CMS und die Textbearbeitung.

RegelBeschreibung
QuelleDer echte Text steht im Template (oder in einem data--Attribut wie data-words)
EffektDas Skript zerlegt oder ersetzt den Inhalt erst beim Laden der Seite
EditorKein Effekt, nur der Ausgangszustand (siehe Regeln)
Ohne JavaScriptDer Text bleibt vollständig lesbar
Mit „weniger Bewegung“Der Effekt entfällt (nächster Abschnitt)

Für einfache Animationen ohne eigenes Skript gibt es das Werkzeug VN Animation (Animationen): Es setzt data-vn-anim-Attribute und liefert Keyframes und ein kleines Beobachter-Skript.

Weniger Bewegung#

Alles, was sich bewegt, muss die Systemeinstellung „Bewegung reduzieren“ respektieren: per CSS und per Skript.

Syntax

js
var RM = !!(window.matchMedia && matchMedia("(prefers-reduced-motion: reduce)").matches);
if (!RM && "IntersectionObserver" in window) { /* Einblend-Effekt starten */ }
css
@media (prefers-reduced-motion: reduce) {
  .mein-block .effekt { animation: none !important; transition: none !important; }
}
BausteinVerhalten bei „weniger Bewegung“
VN Animation (Export-Regeln)[data-vn-anim] { animation: none !important }
VN Hintergrundvideo (vendor/vn-bgvideo)Video wird nicht gestartet; Vorschaubild bleibt
VN Popupschließt ohne Animation
VN Galerie (Karussell)scrollt ohne weiches Scrollen
Weiches Scrollen zu Ankern (vn-bgvid-scroll)springt statt zu gleiten

Ist VN Cookie-Consent in den Projekteinstellungen eingeschaltet, sperrt der Export bekannte Drittanbieter-Inhalte, bis die passende Kategorie zugestimmt hat. Fremde Inhalte (Karten, Videos, Tracking) laden dann erst nach Zustimmung oder Klick.

gateThirdPartyEmbeds (Export, auf jedem Block) und gateRawScriptText (globale HTML-Einfügungen) erkennen:

InhaltErkennungKategorie
Google Maps (<iframe src>)google.<tld>/maps, maps.google., goo.gl/mapsfunctional
YouTube-Einbettungyoutube.com/embed/…, youtube.com/v/…, auch youtube-nocookie.com (die IP-Adresse geht schon beim Laden des Players an den Anbieter)marketing
Vimeo-Einbettung (ab Version 1.3.100)player.vimeo.com/video/… (die Seitenadresse vimeo.com/<Nr> ist keine Einbettung und wird nicht erkannt)marketing
Google Analytics / Tag Manager<script src> mit googletagmanager.com, google-analytics.com; Inline-Code mit gtag(, googletagmanager, GoogleAnalyticsObjectstatistics
Facebook-Pixelconnect.facebook.net, facebook.com/tr; Inline fbq(marketing

Für alles andere markieren Sie das Element selbst:

html
<iframe src="https://example.com/widget" data-vn-consent-category="functional"></iframe>
<script src="https://example.com/stats.js" data-vn-consent-category="statistics"></script>
AttributWerteBedeutung
data-vn-consent-categoryfunctional, statistics, marketingDas Element wird gesperrt, bis die Kategorie zugestimmt ist; wirkt unabhängig von der Domain

Was der Export daraus macht

html

<div class="vn-cc-gate" data-vn-cc-category="marketing" style="width:560px;height:315px">
  <iframe data-vn-cc-src="https://www.youtube-nocookie.com/embed/ID" …></iframe>
  <div class="vn-cc-gate-overlay">
    <p class="vn-cc-gate-text" data-vn-cc-category="marketing"></p>
    <div class="vn-cc-gate-buttons"><button type="button" class="vn-cc-gate-accept"></button><button type="button" class="vn-cc-gate-settings"></button></div>
  </div>
</div>

<script type="text/plain" data-vn-cc-category="statistics" data-vn-cc-src="https://example.com/stats.js"></script>
MarkerBedeutung
data-vn-cc-srcDie ursprüngliche src; wird nach Zustimmung wieder zu src
type="text/plain" + data-vn-cc-categoryGesperrtes Skript; nach Zustimmung wird eine echte <script> eingefügt, type und data-vn-cc* entfallen, andere Attribute bleiben
.vn-cc-gateHülle mit Überlagerung („Inhalt laden“, „Einstellungen“); „Inhalt laden“ schaltet nur diese eine Einbettung frei

Blöcke, die ihr Fremdmaterial per JavaScript nachladen (Klick auf ein Vorschaubild, Karte), bauen die Sperre selbst und nutzen dieselbe Schnittstelle. So bleibt der Block unabhängig davon, ob Consent eingeschaltet ist.

Schnittstelle window.vnCookieConsent (erst nach DOMContentLoaded vorhanden; nur wenn Cookie-Consent eingeschaltet ist):

AufrufRückgabeBedeutung
getConsent(){ necessary: true, functional, statistics, marketing } (Wahrheitswerte)Stand der Zustimmung; ohne Entscheidung alles false
openSettings()—Öffnet das Einstellungsfenster
labelGates()—Beschriftet alle .vn-cc-gate-text, .vn-cc-gate-accept und .vn-cc-gate-settings neu (nach dem eigenen Einfügen aufrufen)

Ereignis vn-cc-activated wird an der Hülle ausgelöst, sobald sie freigegeben wurde (Klick auf „Inhalt laden“ oder Zustimmung zur Kategorie). Darauf reagieren Sie, um zu laden.

Muster (verkürzt aus gallery-content/vn-bloecke/src/video/embed/template.html):

js
var c = window.vnCookieConsent && window.vnCookieConsent.getConsent ? window.vnCookieConsent : null;
function ask(host, go) {
  if (!c || c.getConsent().marketing) { go(); return; }          // ohne Consent oder schon erlaubt
  host.classList.add("vn-cc-gate");
  host.setAttribute("data-vn-cc-category", "marketing");
  var o = document.createElement("div");
  o.className = "vn-cc-gate-overlay";
  o.innerHTML = '<p class="vn-cc-gate-text" data-vn-cc-category="marketing"></p>'
    + '<div class="vn-cc-gate-buttons"><button type="button" class="vn-cc-gate-accept"></button>'
    + '<button type="button" class="vn-cc-gate-settings"></button></div>';
  host.appendChild(o);
  if (c.labelGates) c.labelGates();
  host.addEventListener("vn-cc-activated", function f() {
    host.removeEventListener("vn-cc-activated", f);
    o.remove(); host.classList.remove("vn-cc-gate", "vn-cc-activated");
    go();
  });
}

Ab Version 1.3.100 löst VN Cookie-Consent bei jeder neuen Auswahl des Besuchers („Speichern“, „Alle akzeptieren“, „Nur notwendige“) am document das Ereignis vn-cc-consent aus; event.detail ist die neue Einwilligung (dasselbe Objekt wie getConsent()). Es kommt nicht beim Laden der Seite mit bereits gespeicherter Auswahl und nicht beim Klick auf „Inhalt laden“ einer einzelnen Hülle (dafür gibt es vn-cc-activated). Ein Skript, das erst nach Zustimmung etwas laden soll, prüft deshalb beim Start getConsent() und hört zusätzlich auf das Ereignis:

js
function ok() {
  var c = window.vnCookieConsent;
  return !c || !c.getConsent || !!c.getConsent().marketing;   // ohne Cookie-Consent auf der Seite: sofort
}
function start() { /* Fremdinhalt laden */ }
if (ok()) start();
else document.addEventListener("vn-cc-consent", function f() {
  if (!ok()) return;
  document.removeEventListener("vn-cc-consent", f);
  start();
});

So arbeitet das Hintergrundvideo (vendor/vn-bgvideo/vn-bgvideo.js): YouTube- und Vimeo-Hintergründe laden bei eingeschaltetem Cookie-Consent erst nach Zustimmung zu „Marketing“, das Ersatzbild bleibt bis dahin stehen (Video-Hintergrund).

YouTube und Vimeo erst nach Klick#

Der Datenschutz-Grundsatz: Es gibt keine Verbindung zu YouTube oder Vimeo, bevor der Besucher aktiv wird. Zwei Wege:

  1. Zwei-Klick-Lösung im Block: Zuerst nur ein Vorschaubild mit Abspielknopf (button mit img), erst der Klick erzeugt den <iframe>. Beispiel gallery-content/vn-bloecke/src/effekte/videoprivacy/template.html:
html
<div class="vf-vd" data-v="{{video}}">
  <div class="vf-vd-frame">
    <button class="vf-vd-poster" type="button" aria-label="Video abspielen">
      <img src="{{imgPoster}}" alt="Vorschaubild">
      <span class="vf-vd-label">Video abspielen</span>
    </button>
  </div>
</div>
<script>(function(){document.querySelectorAll(".vf-vd").forEach(function(b){if(b.dataset.vfInit)return;b.dataset.vfInit=1;
var fr=b.querySelector(".vf-vd-frame"),po=b.querySelector(".vf-vd-poster");if(!po)return;
po.addEventListener("click",function(){if(b.closest("#canvas"))return;
var raw=(b.dataset.v||"").trim(),id=raw,m=raw.match(/(?:v=|youtu\.be\/|embed\/|shorts\/|live\/)([A-Za-z0-9_-]{11})/);if(m)id=m[1];
if(!/^[A-Za-z0-9_-]{6,20}$/.test(id))return;
var f=document.createElement("iframe");f.src="https://www.youtube-nocookie.com/embed/"+id+"?autoplay=1&rel=0";f.title="Video";
f.allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen";f.setAttribute("allowfullscreen","");f.setAttribute("referrerpolicy","strict-origin-when-cross-origin");
fr.appendChild(f);b.classList.add("is-playing");po.hidden=true})})})();</script>
  1. Einbettung mit Sperre: Ein normaler <iframe> mit Adresse; bei eingeschaltetem Consent sperrt der Export ihn automatisch (Automatisches Sperren).

Text-Daten in Attributen: vnEnc#

Im Template darf ein Text aus dem Panel nie roh in data-…="{{x}}" stehen: Ein Anführungszeichen oder {{ im Text bricht das Markup. Verwenden Sie vnEnc(text) und dekodieren Sie im Skript.

Syntax

html
<div class="mein-block" data-titel="{{vnEnc(titel)}}"></div>
js
var titel = decodeURIComponent(box.getAttribute("data-titel") || "");
HilfsfunktionGilt inBedeutung
vnEnc(wert){{…}} und Bedingungen im TemplateencodeURIComponent(String(wert)); undefined/null ergibt ''
vnEmbed(adresse){{…}} im TemplateYouTube-/Vimeo-Adresse → einbettbare Adresse (youtube-nocookie.com/embed/… bzw. player.vimeo.com/video/…); andere Adressen bleiben unverändert
{{vn-id}}Template (Text, Attribute, auch im Skript-Text)Block-ID oder Anker-ID der Instanz; eindeutige IDs: id="{{vn-id}}-nav"

Diese drei sind Hilfen des Template-Ausdrucks, keine globalen JavaScript-Funktionen: Im Skript selbst (window.vnEnc) gibt es sie nicht (geprüft: typeof window.vnEnc === "undefined"). Die Ausdrücke laufen außerdem mit Zugriff auf die globalen Standardobjekte (String, Number, Math, encodeURIComponent …).

Mitgelieferte Bibliotheken#

Alles Fremde, was ein Block braucht, muss mitgeliefert werden (keine CDN-Aufrufe, keine Webfonts). Das Programm kopiert beim Export nur, was die Seiten wirklich verwenden. Folgende Bibliotheken liegen unter vendor/; die Auswahl hängt von Spuren im fertigen HTML ab.

BibliothekZweckExport (Bedingung)
Bootstrap 5.0.1 (CSS + Bundle-JS)Grid, Hilfsklassen, Dropdown, Collapse, Tooltip, Modalimmer (Bundle: window.bootstrap), außer im Bootstrap-Theme-Modus
Bootstrap IconsSymbolschrift bi bi-…immer (vendor/bootstrap-icons/)
FlaggenLänderflaggen (SVG, 4:3 und 1:1)als Projektdateien unter assets/, nur die benutzten
jQuery 3.5.1Nur für ältere Bootstrap-4-Themes und deren Pluginsnur im Theme-Modus (vendor/jquery.min.js)
VN LightboxZoomen/Schieben von BildernSeiteneinstellung eingeschaltet
VN Cookie-ConsentBanner, Sperren, vnCookieConsentSeiteneinstellung eingeschaltet
VN PopupPopup-BlöckeSeite enthält ein Popup
VN CMSBearbeiten auf der fertigen SeiteSeite enthält einen CMS-Block
VN UntermenüSeitlich aufklappende Menüebeneli.vn-submenu im HTML
VN TooltipTooltips auf Wörternspan.vn-tip im HTML
VN VideoZusatzfunktionen für selbst gehostete Videosvideo.vn-video-el im HTML
VN HintergrundvideoHintergrundvideo (Datei, YouTube, Vimeo)data-bg-video mit Wert oder .vn-bgvid
VN ÜbersetzerLive-ÜbersetzungSeiteneinstellung eingeschaltet
VN WhatsAppSchwebender KontaktknopfSeiteneinstellung (mit Nummer)
VN Formular (vn-sform), Form RendererFormulare, Versandform.vn-sform-form oder Form-Renderer-Block
VN PDF-Betrachter (PDF.js 3.11.174)PDF und TabellenBlock mit Betrachter-Adresse
VN Suche, VN BlogPHP-Systemejeweilige Blöcke
jszip, less, CodeMirrorNur im Editornie im Export

Die folgenden Einträge beschreiben die Bibliotheken, die ein Block-Autor aus einem Block heraus nutzt oder ansteuert. Die Einbindung ist immer: nichts tun (Markierung setzen), der Export fügt <link>/<script> selbst ein.

Bootstrap 5.0.1 und Bootstrap Icons#

Das Bundle stellt window.bootstrap bereit (Collapse, Dropdown, Tooltip, Modal, Carousel …). Es läuft nach den Block-Skripten.

js
document.addEventListener("DOMContentLoaded", function () {
  var el = document.querySelector("#mein-id-modal");
  if (el && window.bootstrap) new bootstrap.Modal(el).show();
});
HinweisBeschreibung
AttributeBootstrap-5-Namen (data-bs-toggle, data-bs-target); die Bootstrap-4-Namen (data-toggle, data-target, data-dismiss, data-ride, data-slide, data-slide-to, data-parent) ergänzt der Import beim Einlesen um die 5er-Namen (data-bs-…)
EditorDas Bundle ist im Editor geladen (Menüs, Dropdowns funktionieren); jQuery ist es nicht
Symbole<i class="bi bi-NAME">; die Symbolliste (2078 Symbole) wird im Symbol-Dialog durchsucht

jQuery und Theme-Plugins (Bootstrap-Theme-Modus)#

Ein Projekt kann auf dem Bootstrap eines Themes laufen (zum Beispiel Bootstrap 4.5; siteSettings.bootstrapMode = 'theme'). Der Export lädt dann statt Bootstrap 5 diese Reihenfolge: jQuery (vendor/jquery.min.js, 3.5.1), Popper, Bootstrap-JS des Themes, Smooth-Scroll, die Plugins der benutzten Bausteine (mit Abhängigkeiten), zuletzt das Theme-Skript.

Welche Plugins ein Baustein will, steht am Wurzelelement:

html
<section class="menu" plugins="DropDown, TouchSwipe"> … </section>
AttributWertBedeutung
pluginsListe von Plugin-Namen (Komma, Groß-/Kleinschreibung egal)Nur im Theme-Modus: lädt diese Plugin-Ordner des Themes (plugins/<name>/, nur .js; bei Paaren die .min-Fassung)

Abhängigkeiten sind eingebaut (masonry braucht imagesloaded; gallery braucht imagesloaded und masonry). Ein Parallax-Hintergrund-Marker im Markup löst das Plugin parallax aus. Die Skript-Dateien liegen im Projekt unter assets/theme-js/, damit der Export ohne das Paket funktioniert.

VN Lightbox#

Seitenweit zoom- und verschiebbare Bilder. Der Block markiert nur, was gezoomt werden soll; Details und Attribute: Lightbox.

html
<img class="vn-zoom" src="assets/images/foto.jpg" alt="Foto" data-vn-caption="Bildunterschrift">

Einstellungsfenster, Sperren, Konfiguration window.VN_COOKIE_CONFIG, die Schnittstelle vnCookieConsent und das Ereignis vn-cc-consent. Link zum erneuten Öffnen: <a href="#" data-vn-cookie-settings> (Cookie-Link). Kategorien: functional, statistics, marketing; Zustimmung in localStorage.

VN Popup#

Fenster über der Seite; Auslösung über Link, Zeit, Scrollen, Verlassen der Seite; Schnittstelle VNPopup (Popup).

VN CMS#

Bearbeiten auf der fertigen Seite (vendor/vn-cms, PHP). Markierungen und Server-Ordner: CMS.

VN Untermenü#

Reines JS, fügt seine CSS-Regeln selbst ein (<style data-vn-submenu>), setzt window.__vnSubmenu. Markup: Untermenü. Es ist auch im Editor geladen (vendor/vn-submenu/vn-submenu.js in index.html).

VN Tooltip#

Aktiviert span.vn-tip[data-bs-toggle="tooltip"] über Bootstrap-Tooltip; ohne Bootstrap 5 bleibt der title-Hinweis. Markup: Tooltips.

VN Übersetzer#

Sprachknopf für Besucher; markiert werden nur Ausnahmen: Übersetzer.

VN WhatsApp#

Schwebender Kontaktknopf, rein über die Seiteneinstellung (window.VN_WHATSAPP_CONFIG: phone, message, side, bottomOffset, sideOffset, bubbleEnabled, bubbleTitle, bubbleText, bubbleDelay). Ein Block hat damit nichts zu tun; für einen Link zu WhatsApp siehe Telefon und WhatsApp.

VN Video, Hintergrundvideo, Formulare, PDF, Suche, Blog#

Diese Bibliotheken gehören zu fertigen Blöcken. Ihre Markierungen und Einstellungen stehen in den Kapiteln Formulare und Medien.

BibliothekZweckSo nutzt ein Block sie
VN Video (vendor/vn-video)Start-/Endzeit, Tempo, Lazy-Laden, VN Playervideo.vn-video-el mit data-…-Werten (Selbst gehostetes Video)
VN Hintergrundvideo (vendor/vn-bgvideo)Video hinter dem Inhaltdata-bg-video="<Adresse>" oder Klasse vn-bgvid (Video-Hintergrund)
VN Formular (vendor/vn-sform)Prüfen und Senden statischer Formulareform.vn-sform-form (Formulare)
Form Renderer (vendor/vn-formrender)Formular aus JSON, Regeln, PHP-Versandsection.vn-formrender mit .vnfr-data (Form Renderer)
VN PDF-Betrachter (vendor/vn-pdf-viewer)PDF.js mit Sucheiframe[data-vn-pdf-src] (PDF)
VN Suche (vendor/vn-search)Volltextsuche (PHP)section.vn-search (Suche)
VN Blog (vendor/vn-blog)Blog (PHP, SQLite)Include im geschützten PHP-Skript (Blog)

Fallen: Skript läuft im Editor und zerstört Inhalt#

Alle bisherigen Meldungen zu Skripten lassen sich auf diese Klassen zurückführen:

FalleWirkungAbhilfe
Skript schreibt den Inhalt eines data-vn-text-id-Elements umBeim Tippen wird der Zwischenzustand gespeichert; Text „zerstört“Effekte nur außerhalb des Canvas; Text im Template ruhig halten
if (closest('#canvas')) return; vor dem Setzen des AnfangswertsPanel-Änderungen sind im Editor unsichtbarAnfangszustand setzen, dann beenden
Skript versteckt Inhalt (opacity:0, display:none, .reveal) und blendet ihn erst per Beobachter einIm Editor erscheint nur der HintergrundVerstecken nur nach der Editor-Prüfung
data-…-Init-MerkerNeue Blöcke werden von alten Skripten „als schon erledigt“ übergangenJS-Eigenschaft am Element
Feste IDs / ein globaler ZustandZweite Instanz kaputtKlassen, {{vn-id}}, Namensraum
document.currentScript ohne Rückfallim Editor nulldocument.querySelector(…) als Rückfall
Prüfung auf is-builderEditor wird nie erkanntclosest('#canvas')
Zugriff auf bootstrap/vnCookieConsent beim ParsenundefinedAuf DOMContentLoaded warten
jQuery vorausgesetztim Editor und normalen Export nicht daReines JavaScript
window-Schutzschalter (window.fertig)im Editor pro Render zurückgesetzt, auf der echten Seite dauerhaftMerker am Element
<script type="module"> mit statischem importim Editor nicht ausführbar (läuft in new Function)Klassisches Skript
Rohtext in data-x="{{x}}"Markup bricht bei Anführungszeichen oder {{vnEnc(x) + decodeURIComponent
Eigene Fremd-Adressen (CDN, Fonts)Datenschutz, offline unbrauchbarMitliefern oder weglassen
Zugriff auf location zum Umleiten im Editorwirkungslos (absichtlich)nur auf der echten Seite sinnvoll