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.
| Ort | Läuft das Skript? | Wie |
|---|---|---|
Export (publish/), Vorschau im Browser und Live-Vorschau | ja, normal | Die Seite wird über einen lokalen Server ausgeliefert (preview-server.cjs), das Skript läuft wie auf der echten Seite |
| Editor (Arbeitsfläche) | ja, abgeschirmt | src/editor-scripts.js führt Inline-Skripte nach jedem Render mit Stellvertretern aus (siehe Verhalten im Editor); abschaltbar |
| Code-Editor | nein | Dort wird nur das Template-HTML gezeigt |
Reihenfolge einer exportierten Seite (aus buildExportHtml):
<head>: Bootstrap-CSS, Bootstrap-Icons-CSS, die CSS-Dateien der benutzten Laufzeit-Bibliotheken,style.css.<body>: der HTML-Code aller Blöcke der Seite in Reihenfolge, jeweils mit ihren Inline-Skripten.- 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
<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)
| Regel | Beschreibung |
|---|---|
| Ort | Innerhalb des Wurzelelements, meist als letztes Kind |
| Art | Nur <script> ohne src und ohne fremden type wird im Editor ausgeführt (type leer, text/javascript, application/javascript, module) |
| Fremde Typen | type="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 |
| Bedingungen | vn-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
(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 …
});
})();| Merker | Eignung | Grund |
|---|---|---|
JS-Eigenschaft (box.vnInit = 1) | empfohlen | Gehört dem Element, nie im HTML, nie im gespeicherten Template, nie im Export |
data-…-Attribut | vermeiden | Das 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 Hilfsfunktionen | Im 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“):
(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.
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
<div class="vn-bgvid-empty" data-vn-editor-only vn-if="!videoFile && !videoUrl">
Noch kein Video gewählt — im Eigenschaften-Panel unter „Video“ eine Datei wählen.
</div>| Attribut | Wert | Bedeutung |
|---|---|---|
data-vn-editor-only | Schalter | Das 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
var inEditor = !!el.closest("#canvas");
if (inEditor) return; // oder nur den Effekt auslassen, Inhalt aber setzenWert von el.closest("#canvas") | Bedeutung |
|---|---|
| Element | Editor (Arbeitsfläche) |
null | Export, Vorschau oder Live-Vorschau |
Editor, Vorschau und Export im Vergleich#
| Merkmal | Editor (Arbeitsfläche) | Vorschau und Live-Vorschau | Export |
|---|---|---|---|
| Block-Skripte | abgeschirmt, nach jedem Render | normal | normal |
el.closest("#canvas") | Element | null | null |
window.bootstrap | da | da (nach den Block-Skripten) | da (nach den Block-Skripten) |
| jQuery | nein | nein (nur im Bootstrap-Theme-Modus) | nein (nur im Bootstrap-Theme-Modus) |
| Laufzeit-Bibliotheken (Lightbox, Consent, Popup …) | nein (Ausnahme: VN Untermenü) | ja, wie im Export | ja, wenn benutzt |
data-vn-editor-only-Elemente | sichtbar | entfernt | entfernt |
| PHP | läuft nicht (Attrappen) | läuft über den lokalen Server | lä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:
| Mittel | Ergebnis im Editor | Folge |
|---|---|---|
document.documentElement.classList.contains("is-builder") | false | Das 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") | false | wie oben (nur die Lightbox beachtet sie) |
document.currentScript | null | Der 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.top | false | Es 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 Skript | Verhalten im Editor |
|---|---|
setTimeout, setInterval, requestAnimationFrame | Rü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 window | Rückruf läuft sofort (zeitversetzt, setTimeout 0) |
window.onload = fn | wird als Rückruf sofort ausgeführt |
document.readyState | immer complete |
document.write, document.writeln | tut nichts |
location.assign, .replace, .reload; location.href = … | tut nichts; Lesen geht |
alert, confirm, prompt | tun nichts (confirm liefert false, prompt null) |
andere document-/window-Aufrufe | normal (an das echte Objekt gebunden) |
this, self, globalThis, window.window | der 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#
| Regel | Begründung |
|---|---|
Alles, was DOM verschiebt, versteckt oder austauscht, im Editor nicht tun (No-op): Karussell-Umbau, Reveal mit opacity:0, Einklappen, Klonen | Sonst 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 beenden | Wer 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 beenden | Zeitgeber 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.
| Regel | Beschreibung |
|---|---|
| Quelle | Der echte Text steht im Template (oder in einem data--Attribut wie data-words) |
| Effekt | Das Skript zerlegt oder ersetzt den Inhalt erst beim Laden der Seite |
| Editor | Kein Effekt, nur der Ausgangszustand (siehe Regeln) |
| Ohne JavaScript | Der 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
var RM = !!(window.matchMedia && matchMedia("(prefers-reduced-motion: reduce)").matches);
if (!RM && "IntersectionObserver" in window) { /* Einblend-Effekt starten */ }@media (prefers-reduced-motion: reduce) {
.mein-block .effekt { animation: none !important; transition: none !important; }
}| Baustein | Verhalten 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 Popup | schließt ohne Animation |
| VN Galerie (Karussell) | scrollt ohne weiches Scrollen |
Weiches Scrollen zu Ankern (vn-bgvid-scroll) | springt statt zu gleiten |
Cookie-Consent und Datenschutz#
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.
Automatisches Sperren#
gateThirdPartyEmbeds (Export, auf jedem Block) und gateRawScriptText (globale HTML-Einfügungen) erkennen:
| Inhalt | Erkennung | Kategorie |
|---|---|---|
Google Maps (<iframe src>) | google.<tld>/maps, maps.google., goo.gl/maps | functional |
| YouTube-Einbettung | youtube.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, GoogleAnalyticsObject | statistics |
| Facebook-Pixel | connect.facebook.net, facebook.com/tr; Inline fbq( | marketing |
Für alles andere markieren Sie das Element selbst:
<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>| Attribut | Werte | Bedeutung |
|---|---|---|
data-vn-consent-category | functional, statistics, marketing | Das Element wird gesperrt, bis die Kategorie zugestimmt ist; wirkt unabhängig von der Domain |
Was der Export daraus macht
<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>| Marker | Bedeutung |
|---|---|
data-vn-cc-src | Die ursprüngliche src; wird nach Zustimmung wieder zu src |
type="text/plain" + data-vn-cc-category | Gesperrtes Skript; nach Zustimmung wird eine echte <script> eingefügt, type und data-vn-cc* entfallen, andere Attribute bleiben |
.vn-cc-gate | Hülle mit Überlagerung („Inhalt laden“, „Einstellungen“); „Inhalt laden“ schaltet nur diese eine Einbettung frei |
Eigene Sperre im Block (Gate-Markup)#
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):
| Aufruf | Rückgabe | Bedeutung |
|---|---|---|
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):
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();
});
}Ereignis vn-cc-consent#
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:
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:
- Zwei-Klick-Lösung im Block: Zuerst nur ein Vorschaubild mit Abspielknopf (
buttonmitimg), erst der Klick erzeugt den<iframe>. Beispielgallery-content/vn-bloecke/src/effekte/videoprivacy/template.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>- 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
<div class="mein-block" data-titel="{{vnEnc(titel)}}"></div>var titel = decodeURIComponent(box.getAttribute("data-titel") || "");| Hilfsfunktion | Gilt in | Bedeutung |
|---|---|---|
vnEnc(wert) | {{…}} und Bedingungen im Template | encodeURIComponent(String(wert)); undefined/null ergibt '' |
vnEmbed(adresse) | {{…}} im Template | YouTube-/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.
| Bibliothek | Zweck | Export (Bedingung) |
|---|---|---|
| Bootstrap 5.0.1 (CSS + Bundle-JS) | Grid, Hilfsklassen, Dropdown, Collapse, Tooltip, Modal | immer (Bundle: window.bootstrap), außer im Bootstrap-Theme-Modus |
| Bootstrap Icons | Symbolschrift bi bi-… | immer (vendor/bootstrap-icons/) |
| Flaggen | Länderflaggen (SVG, 4:3 und 1:1) | als Projektdateien unter assets/, nur die benutzten |
| jQuery 3.5.1 | Nur für ältere Bootstrap-4-Themes und deren Plugins | nur im Theme-Modus (vendor/jquery.min.js) |
| VN Lightbox | Zoomen/Schieben von Bildern | Seiteneinstellung eingeschaltet |
| VN Cookie-Consent | Banner, Sperren, vnCookieConsent | Seiteneinstellung eingeschaltet |
| VN Popup | Popup-Blöcke | Seite enthält ein Popup |
| VN CMS | Bearbeiten auf der fertigen Seite | Seite enthält einen CMS-Block |
| VN Untermenü | Seitlich aufklappende Menüebene | li.vn-submenu im HTML |
| VN Tooltip | Tooltips auf Wörtern | span.vn-tip im HTML |
| VN Video | Zusatzfunktionen für selbst gehostete Videos | video.vn-video-el im HTML |
| VN Hintergrundvideo | Hintergrundvideo (Datei, YouTube, Vimeo) | data-bg-video mit Wert oder .vn-bgvid |
| VN Übersetzer | Live-Übersetzung | Seiteneinstellung eingeschaltet |
| VN WhatsApp | Schwebender Kontaktknopf | Seiteneinstellung (mit Nummer) |
VN Formular (vn-sform), Form Renderer | Formulare, Versand | form.vn-sform-form oder Form-Renderer-Block |
| VN PDF-Betrachter (PDF.js 3.11.174) | PDF und Tabellen | Block mit Betrachter-Adresse |
| VN Suche, VN Blog | PHP-Systeme | jeweilige Blöcke |
| jszip, less, CodeMirror | Nur im Editor | nie 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.
document.addEventListener("DOMContentLoaded", function () {
var el = document.querySelector("#mein-id-modal");
if (el && window.bootstrap) new bootstrap.Modal(el).show();
});| Hinweis | Beschreibung |
|---|---|
| Attribute | Bootstrap-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-…) |
| Editor | Das 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:
<section class="menu" plugins="DropDown, TouchSwipe"> … </section>| Attribut | Wert | Bedeutung |
|---|---|---|
plugins | Liste 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.
<img class="vn-zoom" src="assets/images/foto.jpg" alt="Foto" data-vn-caption="Bildunterschrift">VN Cookie-Consent#
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.
| Bibliothek | Zweck | So nutzt ein Block sie |
|---|---|---|
VN Video (vendor/vn-video) | Start-/Endzeit, Tempo, Lazy-Laden, VN Player | video.vn-video-el mit data-…-Werten (Selbst gehostetes Video) |
VN Hintergrundvideo (vendor/vn-bgvideo) | Video hinter dem Inhalt | data-bg-video="<Adresse>" oder Klasse vn-bgvid (Video-Hintergrund) |
VN Formular (vendor/vn-sform) | Prüfen und Senden statischer Formulare | form.vn-sform-form (Formulare) |
Form Renderer (vendor/vn-formrender) | Formular aus JSON, Regeln, PHP-Versand | section.vn-formrender mit .vnfr-data (Form Renderer) |
VN PDF-Betrachter (vendor/vn-pdf-viewer) | PDF.js mit Suche | iframe[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:
| Falle | Wirkung | Abhilfe |
|---|---|---|
Skript schreibt den Inhalt eines data-vn-text-id-Elements um | Beim 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 Anfangswerts | Panel-Änderungen sind im Editor unsichtbar | Anfangszustand setzen, dann beenden |
Skript versteckt Inhalt (opacity:0, display:none, .reveal) und blendet ihn erst per Beobachter ein | Im Editor erscheint nur der Hintergrund | Verstecken nur nach der Editor-Prüfung |
data-…-Init-Merker | Neue Blöcke werden von alten Skripten „als schon erledigt“ übergangen | JS-Eigenschaft am Element |
| Feste IDs / ein globaler Zustand | Zweite Instanz kaputt | Klassen, {{vn-id}}, Namensraum |
document.currentScript ohne Rückfall | im Editor null | document.querySelector(…) als Rückfall |
Prüfung auf is-builder | Editor wird nie erkannt | closest('#canvas') |
Zugriff auf bootstrap/vnCookieConsent beim Parsen | undefined | Auf DOMContentLoaded warten |
| jQuery vorausgesetzt | im Editor und normalen Export nicht da | Reines JavaScript |
window-Schutzschalter (window.fertig) | im Editor pro Render zurückgesetzt, auf der echten Seite dauerhaft | Merker am Element |
<script type="module"> mit statischem import | im 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 unbrauchbar | Mitliefern oder weglassen |
Zugriff auf location zum Umleiten im Editor | wirkungslos (absichtlich) | nur auf der echten Seite sinnvoll |