VN-Designer Entwickler-Dokumentation
09

Hintergründe, Medien und Werkzeug-Bausteine

Hintergrund-Widget (Bild, Farbe, Video, Parallax, Overlay), Video-Hintergrund und Video-Behälter, selbst gehostetes Video, Lightbox, Galerie, PDF-Betrachter, Suche, Blog, Animationen und Übersetzer – jeweils mit den Markierungen, die der Block-Autor setzt, und dem, was das Programm daraus macht.

Überblick#

Medien und Werkzeug-Bausteine folgen zwei Mustern:

  1. Markierung im Template: Der Block-Autor setzt ein Attribut, eine Klasse oder ein Widget (fieldset type="background", data-bg-video, class="vn-zoom", [vn-video] …). Das Programm erkennt es beim Rendern oder beim Export.
  2. Laufzeit-Bibliothek: Nur wenn die exportierte Seite eine Spur davon enthält, kopiert der Export die passende Datei aus vendor/ und bindet sie ein (siehe Mitgelieferte Bibliotheken).

Hintergrund-Widget#

fieldset type="background"#

Das Hintergrund-Widget im Eigenschaften-Panel besteht aus einem fieldset mit bis zu drei Eingaben: Bild, Farbe, Video. Der Nutzer wählt eine der Arten.

Syntax

html
<vn-parameters>
  <header>Hintergrund</header>
  <fieldset type="background" name="bg" title="Hintergrund">
    <input type="image" title="Bild" value="">
    <input type="color" title="Farbe" value="#f8fafc" selected>
    <input type="video" title="Video" value="">
  </fieldset>
</vn-parameters>

(aus gallery-content/vn-bloecke/src/artikel/inhalt/template.html, dort nur Bild und Farbe)

TeilWerteStandardBedeutung
fieldset (type="background")——Das Widget: jedes fieldset im vn-parameters-Block, das ein input vom Typ image, color oder video enthält. type="background" ist die Schreibkonvention
nameFeldnamebgName des Felds; Schlüssel in block.values und Name im Ausdruck
titleTextHintergrundBeschriftung im Panel
input[type=image]Adresse im valueleerBildart; das Attribut parallax schaltet den Parallax-Effekt als Vorgabe ein
input[type=color]#rrggbb im value#000000Farbart
input[type=video]Adresse im valueleerVideoart (YouTube, Vimeo oder Datei)
selectedSchalter an einer Eingabe—Die vorgewählte Art

Welche Art zuerst gilt: Video, wenn es selected ist oder das Widget nichts anderes hat; sonst Bild, wenn es selected ist oder keine Farbe da ist; sonst Farbe.

Gespeichert wird in block.values[<name>]:

json
{ "type": "image",  "value": { "url": "assets/images/hero.jpg" }, "parallax": true }
{ "type": "color",  "value": "#112233", "parallax": false }
{ "type": "video",  "value": { "url": "https://youtu.be/abc12345678" }, "parallax": false }

Zugriff im Template und in LESS#

OrtAusdruckWert
Template ({{…}}, vn-if, vn-class)bg.typeimage, color oder video
Templatebg.valueBei Bild/Video: Objekt, das auch als Text die Adresse liefert (toString); Farbe: der Hex-Wert
Templatebg.value.urlAdresse (Bild und Video)
Templatebg.parallaxWahrheitswert
LESS@bg-type'image', 'color', 'video' (Zeichenkette in einfachen Anführungszeichen)
LESS@bg-valueBei Bild und Video: die Adresse als Zeichenkette, bei Farbe: die Farbe
LESS@bg-parallaxtrue oder false

Wo Bildadressen als LESS-Variable stehen, schreiben Sie url(@bg-value) und nicht url({{…}}): @bg-value ist schon eine Zeichenkette ohne url(…). Vergleiche wie (@bg-type = "image") mit doppelten Anführungszeichen schreibt das Programm für Sie auf einfache um.

Geprüft (Block mit Widget, drei Zustände gerendert):

css
/* bg = Bild + Parallax */
.vn-imp-test-b1 { min-height: 300px; background-image: url("assets/images/a.jpg"); }
.vn-imp-test-b1 { background-attachment: fixed; }
/* bg = Farbe: kein Bild, kein Parallax */
.vn-imp-test-b1 { min-height: 300px; }

Parallax#

Hat das Widget die Art „Bild“ und ist „Parallax-Effekt“ eingeschaltet (bg.parallax), hängt das Programm an das CSS des Blocks background-attachment: fixed an. Das geschieht zusätzlich zu @bg-parallax, weil die LESS älterer Bausteine die Variable nicht kennt. Bei Farbe und Video gibt es keinen Parallax.

less
& when (@bg-type = 'image') { background-image: url(@bg-value); background-size: cover; background-position: center; }

Overlay: Abdunkeln des Hintergrunds#

Es gibt zwei Wege, ein Bild abzudunkeln.

1. Eigene Felder und LESS (empfohlen, volle Kontrolle): Farbe und Stärke als Panel-Felder, eine Ebene per CSS.

html
<input type="color" title="Bild abdunkeln: Farbe" name="overlayColor" value="#000000" condition="bg.type == 'image'">
<input type="range" inline title="Bild abdunkeln (%)" name="overlay" min="0" max="85" step="5" value="40" condition="bg.type == 'image'">

2. Das Overlay-Element vn-overlay: Ein Element mit der Klasse vn-overlay wird zur deckenden Ebene.

html
<div class="vn-overlay" opacity="0.4" bg-color="#000000"></div>
AttributWertBedeutung
Klasse vn-overlay—Das Element bekommt position:absolute; inset:0; pointer-events:none
opacity0–1Deckkraft (wird zu style="opacity", das Attribut entfällt)
bg-colorFarbeHintergrundfarbe (wird zu style="background-color")

Geprüft: <div class="vn-overlay" opacity="0.4" bg-color="#000000"> wird zu style="position: absolute; inset: 0px; pointer-events: none; opacity: 0.4; background-color: rgb(0, 0, 0);". Das Elternelement muss position: relative haben.

Video-Hintergrund#

data-bg-video#

Ein Block, dessen Wurzelelement data-bg-video="<Adresse>" trägt, bekommt im Export ein Hintergrundvideo. Die Adresse steht meist als Ausdruck aus dem Widget.

Syntax

html
<section data-bg-video="{{bg.type == 'video' && bg.value.url}}">
  <vn-parameters>
    <fieldset type="background" name="bg">
      <input type="image" title="Bild" value="">
      <input type="video" title="Video" value="">
    </fieldset>
  </vn-parameters>
  <div class="container"> … Inhalt … </div>
</section>
Wert von data-bg-videoWirkung
Adresse (YouTube, Vimeo, Datei)Video wird eingesetzt
leer, false, undefined, null, 0kein Video (Bausteine, die nicht im Video-Modus sind, rendern data-bg-video="false")

Der Export bindet vendor/vn-bgvideo/vn-bgvideo.js ein, sobald irgendein Block ein data-bg-video mit Wert (oder die Klasse vn-bgvid) hat.

Geprüft: Mit bg.type = 'video' rendert das Beispiel data-bg-video="https://youtu.be/abc12345678"; bei Bild und Farbe data-bg-video="false".

Ersatzbild-Ebene#

Beim Rendern fügt das Programm als erstes Kind eine Ebene ein, die das Bild des Hintergrunds zeigt, bis das Video läuft (und bei „weniger Bewegung“). Sie trägt die Klasse mbr-fallback-image; hat der Block schon ein Element dieser Klasse, wird es benutzt. Dazu setzt renderer.js mit :where() (niedrige Spezifität, Themes haben Vorrang):

css
:where(.vn-imp-x-b1) { position: relative; overflow: hidden; }
:where(.vn-imp-x-b1) > .mbr-fallback-image { position: absolute; left: 0; top: 0; width: 100%; height: 100%; background-size: cover; background-position: center; z-index: 0; }
:where(.vn-imp-x-b1) > .container, :where(.vn-imp-x-b1) > .container-fluid { position: relative; z-index: 2; }

Der Inhalt eines Blocks liegt in .container oder .container-fluid über dem Video (z-index: 2).

Wiedergabe auf der Seite#

vn-bgvideo.js legt für jedes [data-bg-video] einen Behälter div.vn-bgv (aria-hidden, pointer-events:none) an und setzt ihn nach dem Ersatzbild ein.

QuelleAufbau
YouTube<iframe> auf https://www.youtube-nocookie.com/embed/<ID>?autoplay=1&mute=1&loop=1&playlist=<ID>&controls=0&disablekb=1&fs=0&modestbranding=1&playsinline=1&rel=0&iv_load_policy=3, 16:9 gefüllt (fit mit Überstand 2 %), Einblendung nach dem Laden (1,2 s Verzögerung)
Vimeo<iframe> auf https://player.vimeo.com/video/<ID>?background=1&autoplay=1&loop=1&muted=1&byline=0&title=0&portrait=0 (+ &h=<Hash>)
Datei<video muted loop autoplay playsinline preload="auto"> mit object-fit: cover; pausiert außerhalb des Bildschirms (IntersectionObserver, Schwelle 5 %); bei Fehler wird der Behälter entfernt
Weniger Bewegungprefers-reduced-motion: reduce: nichts wird abgespielt, das Ersatzbild bleibt

Erkannt werden die Adressformen youtube.com/watch?v=, youtube.com/embed/, youtube.com/shorts/, youtube.com/live/, youtu.be/, youtube-nocookie.com/embed/, vimeo.com/<Nummer> (auch mit Hash); alles andere gilt als Datei.

Cookie-Consent (ab Version 1.3.100): Die Iframes für YouTube und Vimeo entstehen erst zur Laufzeit in vn-bgvideo.js, der Export kann sie daher nicht vorab sperren. Das Skript prüft deshalb selbst: Ist VN Cookie-Consent auf der Seite eingeschaltet (window.vnCookieConsent vorhanden), baut es das Video erst, wenn der Besucher „Marketing“ zugestimmt hat. Bis dahin bleibt das Ersatzbild stehen. Das Skript hört dafür auf das Ereignis vn-cc-consent (Ereignis vn-cc-consent), das nach jedem „Speichern“, „Alle akzeptieren“ und „Nur notwendige“ am document ausgelöst wird; ist die Zustimmung schon gespeichert, lädt das Video sofort. Ist Cookie-Consent auf der Seite nicht eingeschaltet, laden YouTube und Vimeo wie bisher sofort.

Der Baustein „Video-Hintergrund“ (vn-bgvid)#

Der fertige Baustein (Reiter „Eigener Code“) ist ein Hero mit Video im Hintergrund und frei änderbarem Text und Knöpfen darüber.

Syntax (Gerüst aus src/vn-bgvideo-block.js, Eingaben gekürzt)

html
<section class="vn-bgvid" group="Video-Hintergrund" data-bg-video="{{videoUrl}}"
         vn-class="{'vn-bgvid-left': align === 'left', 'vn-bgvid-mobile-poster': mobilePoster}">
  <vn-parameters>
    <input type="text" title="Video-Datei (MP4/WebM) — Adresse oder Datei wählen" name="videoFile" value="">
    <input type="text" title="Zweite Fassung (optional, z. B. WebM)" name="videoFile2" value="">
    <input type="text" title="Oder: YouTube-/Vimeo-Adresse" name="videoUrl" value="">
    <input type="image" title="Vorschaubild" name="poster" value="">
    <input type="checkbox" title="Video auch im Editor abspielen" name="editorPlay" checked>
    <input type="checkbox" title="Auf Handys nur das Vorschaubild zeigen" name="mobilePoster">
    <input type="checkbox" title="Pause-Knopf für Besucher anzeigen" name="showToggle" checked>
  </vn-parameters>
  <img class="mbr-fallback-image vn-bgvid-poster" vn-if="!!poster" src="{{poster}}" alt="">
  <video class="vn-bgvid-el" vn-if="!!videoFile" autoplay muted loop playsinline preload="auto" poster="{{poster}}" aria-hidden="true">
    <source src="{{videoFile}}">
    <source vn-if="!!videoFile2" src="{{videoFile2}}">
  </video>
  <div class="vn-bgvid-overlay"></div>
  <div class="vn-bgvid-empty" data-vn-editor-only vn-if="!videoFile &amp;&amp; !videoUrl">Noch kein Video gewählt …</div>
  <div class="vn-bgvid-content"> … Kicker, Überschrift, Text, Knöpfe … </div>
  <button type="button" class="vn-bgvid-toggle" vn-if="showToggle" aria-label="Video pausieren oder abspielen"> … </button>
  <a class="vn-bgvid-scroll" href="#" vn-if="showScroll" aria-label="Weiter nach unten"> … </a>
</section>
TeilBedeutung
section.vn-bgvidErkennung (Export bindet vn-bgvideo.js ein)
video.vn-bgvid-elDatei-Video direkt im Template: läuft deshalb auch im Editor (editorPlay)
data-bg-video="{{videoUrl}}"YouTube/Vimeo-Adresse. Der Titel des Panel-Felds sagt „nur wenn keine Datei gewählt ist“; das Template setzt das Attribut aber immer aus videoUrl. Tragen Sie deshalb nicht beide ein
.vn-bgvid-posterVorschaubild (trägt zugleich die Ersatzbild-Klasse)
.vn-bgvid-overlayAbdunklung (Stil flat, bottom, top, none; Farbe, Stärke)
.vn-bgvid-togglePause-/Abspielen-Knopf; setzt Klasse vn-bgvid-paused an der Section
.vn-bgvid-scrollPfeil: scrollt zum nächsten Baustein (weich, ohne Animation bei „weniger Bewegung“)
vn-bgvid-mobile-posterKlasse: unter 768 px nur das Vorschaubild, das Video wird ausgeblendet

Besonderheiten des Skripts für dieses Element: Es merkt sich die Initialisierung als JS-Eigenschaft (sec.__vnBgvid), pausiert das Video außerhalb des Bildschirms (außer der Besucher hat selbst pausiert) und setzt muted.

Dateifelder: videoFile, videoFile2, subtitleFile#

Panel-Felder vom Typ text mit diesen Namen bekommen automatisch eine Dateiauswahl („Datei wählen …“) neben dem Eingabefeld (VIDEO_FILE_FIELDS).

FeldnameDateiartErlaubtAblage
videoFileVideomp4, webm, ogv, m4v; höchstens 4 GBassets/videos/
videoFile2Videowie oben (zweite Fassung, z. B. WebM)assets/videos/
subtitleFileUntertitelvtt; höchstens 2 MBassets/subtitles/
html
<input type="text" title="Video-Datei (MP4/WebM) — Adresse oder Datei wählen" name="videoFile" value="">

Die Datei wird von Platte zu Platte kopiert (auch mehrere GB, ohne sie in den Speicher zu laden), der Originalname bleibt erhalten (gleiche Datei = keine zweite Kopie). In das Feld kommt die Projektadresse; der Export schreibt sie relativ um. Eintippen einer Adresse (https://…) ist ebenfalls möglich. In der Freien Fläche gilt dasselbe für Felder e<Nr>_file.

Video-Behälter vn-video#

Das Element [vn-video]#

Ein Element mit dem Attribut vn-video, das einen <iframe> (oder <video>) enthält, ist ein Video-Behälter. Das Programm bietet dazu im Panel pro Video ein Feld „Video-Adresse“ und baut die Adresse zur einbettbaren um (Editor und Export).

Syntax

html
<div vn-video class="ratio ratio-16x9">
  <iframe src="https://www.youtube.com/watch?v=aqz-KE-bpKQ" title="Video"></iframe>
</div>
TeilBedeutung
vn-videoMarker am Behälter (nur wenn er iframe, video oder data-vn-video-empty enthält)
data-vn-video-emptyEin Behälter ohne Video bleibt als Platzhalter erhalten

Panel-Werte je Behälter (Index i in Dokumentreihenfolge ab 0), in block.values:

WertTypStandardBedeutung
_videoUrl<i>Adressesrc des Iframes in der VorlageYouTube, Vimeo oder Datei
_videoAuto<i>Schalterautoplay=1 der VorlageAutomatisch starten (immer stumm; im Editor nie)
_videoLoop<i>Schalterloop=1 der VorlageWiederholen

Adressen erkennen und umbauen#

parseVideoUrl ordnet jede Adresse ein; embedSrc liefert die einbettbare Adresse.

Art (kind)ErkanntEinbettung
youtubeyoutube.com/watch?v=, /embed/, /shorts/, /live/, /v/, youtu.be/, youtube-nocookie.comhttps://www.youtube-nocookie.com/embed/<ID>?rel=0&modestbranding=1&playsinline=1 (+ start=<s>, bei Autoplay autoplay=1&mute=1, bei Wiederholen loop=1&playlist=<ID>)
vimeovimeo.com/<Nr>, /video/<Nr>, mit Hashhttps://player.vimeo.com/video/<Nr> (+ h=<Hash>, autoplay=1&muted=1, loop=1)
fileendet auf .mp4 .webm .ogv .m4v, beginnt mit file: oder enthält assets/videos/<video controls playsinline preload="metadata"> (bei Autoplay autoplay muted; bei Wiederholen loop)
otheralles ÜbrigeAdresse unverändert als Iframe
emptyleerHinweiszeile „Video-Adresse im Eigenschaften-Panel eintragen“ (data-vn-editor-only)

Startzeit aus der Adresse: start=/t= mit Sekunden (65) oder 1m5s. Das erzeugte Iframe bekommt allow="autoplay; fullscreen; picture-in-picture; encrypted-media", allowfullscreen, loading="lazy", referrerpolicy="strict-origin-when-cross-origin", title="Video".

Geprüft:

text
https://youtu.be/abc12345678?start=5  + Autoplay + Wiederholen
 → https://www.youtube-nocookie.com/embed/abc12345678?rel=0&modestbranding=1&playsinline=1&start=5&autoplay=1&mute=1&loop=1&playlist=abc12345678
https://vimeo.com/123456789/abcdef1234 + Autoplay
 → https://player.vimeo.com/video/123456789?h=abcdef1234&autoplay=1&muted=1

Bei eingeschaltetem Cookie-Consent sperrt der Export den YouTube-Iframe (youtube-nocookie.com) und, ab Version 1.3.100, auch den Vimeo-Iframe (player.vimeo.com/video/…); beide gehören zur Kategorie „marketing“ (siehe Automatisches Sperren).

Video im Popup-Fenster: iframe[data-src]#

Ein <iframe data-src="{{modalVideo}}"> (Video wird erst beim Öffnen eines Fensters geladen) bekommt nur die Adresse umgebaut: Hat sie die Art YouTube oder Vimeo, wird data-src zur einbettbaren Adresse (mit autoplay/loop aus der Adresse). Das Laden selbst übernimmt das Fenster des Blocks (zum Beispiel ein Bootstrap-Modal oder das Popup: Dort leert vn-popup.js Iframes beim Schließen und stellt sie aus data-vn-src wieder her).

Selbst gehostetes Video: der Baustein „Video“#

Der Baustein „Video (selbst gehostet)“ liegt im Reiter „Eigener Code“. Es geht keine Anfrage an fremde Dienste; die Datei liegt in assets/videos/.

Syntax (Kern aus src/vn-video.js)

html
<section class="vn-video" group="Video" vn-class="{'vn-video-full': width === 'full', 'vn-video-lazy': clickToLoad}">
  <vn-parameters> … </vn-parameters>
  <div class="vn-video-inner">
    <div class="vn-video-frame">
      <video class="vn-video-el" playsinline preload="{{clickToLoad ? 'none' : preload}}" poster="{{poster}}"
             aria-label="{{ariaLabel}}" data-controls="{{controls ? 1 : 0}}" data-autoplay="{{autoplay ? 1 : 0}}"
             data-loop="{{loop ? 1 : 0}}" data-muted="{{muted ? 1 : 0}}" data-start="{{startTime}}" data-end="{{endTime}}"
             data-rate="{{rate}}" data-volume="{{volume}}" data-viewplay="{{viewPlay}}"
             data-exclusive="{{exclusive ? 1 : 0}}" data-lazy="{{clickToLoad ? 1 : 0}}" data-player="{{player}}">
        <source vn-if="!!videoFile &amp;&amp; !clickToLoad" src="{{videoFile}}">
        <source vn-if="!!videoFile &amp;&amp; clickToLoad" data-src="{{videoFile}}">
        <track vn-if="!!subtitleFile &amp;&amp; !clickToLoad" kind="subtitles" src="{{subtitleFile}}" srclang="{{subLang}}" label="{{subLabel}}" data-default="{{subDefault ? 1 : 0}}">
      </video>
      <button type="button" class="vn-video-play" vn-if="clickToLoad" aria-label="Video abspielen"> … </button>
    </div>
  </div>
</section>

Die Schalter stehen als data-…-Werte und werden zu echten Attributen: {{…}} direkt in einem Attribut wie controls würde bei der Verarbeitung zerstört. applyVideoAttributes (Editor und Export) macht daraus:

Attribut am video.vn-video-elWerteWirkung
data-controls1/0controls (nicht bei data-lazy)
data-autoplay1/0autoplay + muted (im Editor nie)
data-loop1/0loop
data-muted1/0muted (auch bei Autoplay oder data-viewplay="play")
data-nodownload1controlslist="nodownload"; sperrt auch das Rechtsklick-Menü
data-nopip1disablepictureinpicture
data-nomenu1Rechtsklick-Menü sperren
track[data-default="1"]—default am Untertitel; das data-default wird entfernt

Zusatzfunktionen der Laufzeit (vendor/vn-video/vn-video.js, Wurzel .vn-video; nur wenn die Seite video.vn-video-el enthält; ohne das Skript spielt das Video normal):

AttributWerteBedeutung
data-start, data-endSekundenStart-/Endzeit (bei Wiederholen springt es zum Start)
data-rateZahl (0,5–2)Wiedergabegeschwindigkeit
data-volume0–100Lautstärke (nur ohne muted)
data-viewplaynone, pause, playBeim Scrollen: pause = pausieren, wenn unter 50 % sichtbar; play = stumm starten und pausieren
data-exclusive1Nur ein Video gleichzeitig (andere pausieren)
data-lazy1Erst beim Klick laden (Vorschaubild + .vn-video-play): source[data-src] und track[data-src] werden erst dann zu src
data-playervn oder nativevn: eigene Steuerleiste in allen Browsern gleich (Farbe über --vn-vp-accent); native: Steuerleiste des Browsers
data-vn-ready, data-vn-loaded1Vom Skript gesetzt (initialisiert / Quellen geladen)
Klasse vn-video-error—Wird an .vn-video gesetzt, wenn das Video nicht lädt (CSS zeigt „Das Video ist nicht verfügbar.“)
Klasse vn-video-started—Nach dem ersten Start im Lazy-Modus

Der VN Player unterstützt Tastatur (c = Untertitel, Home, End …), Wiedergabeleiste, Lautstärke und Vollbild.

Die VN Lightbox macht Bilder der ganzen Website zoom- und verschiebbar. Sie wird in den Seiteneinstellungen eingeschaltet (nicht im Block). Der Block-Autor markiert nur, was gezoomt werden soll, oder schließt Bilder aus.

MarkierungOrtWirkung
class="vn-zoom"imgDieses Bild öffnet die Lightbox (Lupensymbol beim Darüberfahren)
class="vn-zoom"Behälter (kein img)Alle Bilder darin werden erfasst und bilden eine Galerie
data-vn-skipimg in einem .vn-zoom-BehälterDieses Bild ausnehmen
class="vn-nozoom" oder data-vn-nozoomBild oder VorfahrNie zoomen
data-vn-captionBild oder ElementBeschriftung in der Lightbox (sonst alt, title, figcaption, Link-title)
data-vn-full (auch data-large)imgAdresse der großen Fassung (sonst src; Platzhalter-data:-Adressen und verzögert geladene data-src, data-lazy-src, data-original, data-echo werden berücksichtigt)
data-vn-group="<Name>"imgBilder mit demselben Namen bilden eine Galerie (Blättern zwischen ihnen)
data-vn-badge="off"imgKein Lupensymbol

Syntax

html
<img class="vn-zoom" src="assets/images/foto.jpg" alt="Foto" data-vn-caption="Unser Team 2026" data-vn-group="team">
<div class="vn-zoom">
  <img src="assets/images/a.jpg" alt="A"><img src="assets/images/b.jpg" alt="B"><img src="assets/images/logo.svg" alt="" data-vn-skip>
</div>

Galerien ohne Markierung: Im Modus „Galerien + vn-zoom“ (Standard) erfasst die Lightbox automatisch Bilder mit Modal-Auslöser (img[data-bs-toggle="modal"], data-toggle="modal", data-bs-slide-to, data-slide-to), gruppiert nach data-bs-target/data-target. Im Modus „Jedes Inhaltsbild“ (all) kommen nicht markierte Bilder dazu, wenn sie breit genug sind; ausgenommen sind Logos und Symbole (Klassennamen mit logo, icon, avatar, badge, bullet, arrow, sprite; .svg-Bilder), Bilder in nav, .navbar, button, .modal und Bilder in Links mit echter Adresse.

siteSettings.vnLightbox (Ungültiges fällt auf den Standard zurück):

SchlüsselWerteStandardBedeutung
enabledSchalterausLightbox einbinden (Skript + CSS)
modegallery, all, classgalleryNur Galerien + vn-zoom; jedes Inhaltsbild; nur vn-zoom
minWidth50–2000250Mindestbreite in px (Modus all)
gallerySchalteranImportierte Galerien automatisch übernehmen
badgeSchalteranLupensymbol
opacity30–10094Deckkraft des Hintergrunds in %
maxScale2–156Höchstes Zoomen
closeOnBackdropSchalteranKlick daneben schließt
captionSchalteranBeschriftung zeigen
captionColor, captionSize, counterSize, buttonSize, buttonColorFarbe, pxStandardAussehen (0 = automatisch)
excludeeine Zeile je AusnahmeleerAusnahmen: Seitenmuster (impressum.html, blog/*, *preis*), Block-Kennung (#galerie1 oder galerie1) oder CSS-Ausdruck (.keine-lightbox, [data-schutz]); Zeilen mit / am Anfang sind Kommentare

Die Konfiguration steht als window.VN_LIGHTBOX_CONFIG vor dem Skript. Die Lightbox schaltet sich ab, wenn body die Klasse is-builder trägt (das Programm setzt sie nicht). Nachträglich eingefügte Bilder (CMS, Filter, Ajax) erfasst ein MutationObserver.

Galerie: VN Galerie#

Der Baustein „VN Galerie“ entsteht über das Werkzeug VN Galerie (Mehrfachauswahl, Reihenfolge, Bildunterschriften). Block-Autoren schreiben ihn nicht von Hand; dieser Eintrag zeigt, welche Markierungen die Laufzeit auswertet.

Klasse / MarkerBedeutung
vn-galerie-hostErkennungsmerkmal der Galerie (GALLERY_HOST_CLASS)
.vn-gal-wrapBehälter; Einstellungen als CSS-Variablen (--vn-gal-spalten, --vn-gal-spalten-handy, --vn-gal-groesse, --vn-gal-hoehe, --vn-gal-abstand, --vn-gal-rundung, --vn-gal-rahmenfarbe, --vn-gal-lightboxfarbe …)
.vn-gal-grid + vn-gal-karussellAnsicht (Raster, Masonry, Karussell, …); Auswahl ansicht, lightbox, uebergangArt im Panel
.vn-gal-lb-radioVersteckte Radio-Knöpfe: die Lightbox arbeitet rein mit CSS (Radio + label for); im Editor stillgelegt (disabled), damit ein Klick nicht die Großansicht über die Arbeitsfläche legt
figure.vn-gal-item, img.vn-gal-thumb, figcaption.vn-gal-captionEinzelbild mit Beschriftung (die Beschriftung ist per Klick änderbar)
.vn-gal-bar, .vn-gal-prev, .vn-gal-next, .vn-gal-dotsPfeile und Punkte des Karussells (Skript; ohne Skript bleibt eine Bildlaufleiste)

Das Karussell-Skript steht im Baustein selbst (GALLERY_CAROUSEL_SCRIPT) und merkt sich die Initialisierung als JS-Eigenschaft (grid.vnGalInit); „weniger Bewegung“ schaltet das weiche Scrollen ab.

PDF-Betrachter und Tabellen#

PDF: iframe[data-vn-pdf-src]#

Der Baustein „VN PDF-Betrachter“ bettet den mitgelieferten Mozilla PDF.js 3.11.174 ein. Die PDF liegt bytegenau unter assets/vn-pdf-viewer/dateien/ (nur [A-Za-z0-9._-]+.pdf, höchstens 300 MB).

Syntax

html
<iframe class="vn-pdf-frame" style="height:{{hoehe}}px"
        data-vn-pdf-src="assets/vn-pdf-viewer/pdfjs-3.11.174/web/viewer.html?file={{ /[\/:]/.test(pdfDatei) ? encodeURI(String(pdfDatei).trim()) : '../../dateien/' + encodeURIComponent(String(pdfDatei).trim()) }}&amp;vnedit={{bearbeitungErlauben}}#search={{encodeURIComponent(anfangssuche)}}&amp;phrase={{exaktePhrase}}"
        title="PDF-Betrachter"></iframe>
TeilBedeutung
data-vn-pdf-srcAdresse des Betrachters; im Template nicht src: Im Editor setzt das Programm sie auf den mitgelieferten Viewer (ohne src lädt nichts ins Leere), im Export wird daraus src (resolvePdfIframesForExport)
?file=PDF relativ zum Viewer (../../dateien/<name>.pdf) oder eine volle Adresse
&vnedit=true schaltet die PDF-Bearbeitung des Betrachters frei
#search=…&phrase=Suche beim Öffnen; phrase=true = exakte Wortfolge

Der Export kopiert den Viewer (etwa 6 MB) nur, wenn eine Seite die Betrachter-Adresse enthält, und dazu genau die PDFs, auf die ein Block verweist (viewer.html?file=../../dateien/<name>.pdf).

Panel-Felder des Bausteins: pdfDatei, titel, breite (30–100 %), hoehe (400–1600 px), blockFarbe, anfangssuche, exaktePhrase, bearbeitungErlauben, paddingTop, paddingBottom. Der Block läuft nicht durch die Text-/Button-Markierung (noTagging).

CSV und XLSX als Tabelle: VN Tabelle#

Aus einer CSV- oder Excel-Datei erzeugt der Baustein „VN Tabelle“ eine feste, durchsuchbare, sortierbare Tabelle; die Quelldatei wird nicht veröffentlicht. Alles läuft im Browser.

Syntax (Gerüst)

html
<div data-vntabelle-root data-vntabelle-name="Preisliste">
  <div class="vntabelle-werkzeuge">
    <input type="search" data-vntabelle-search placeholder="Suchen …">
    <div class="vntabelle-aktionen">
      <button type="button" data-vntabelle-export>CSV exportieren</button>
      <button type="button" data-vntabelle-print>Drucken</button>
    </div>
    <div class="vntabelle-blaettern">
      <select data-vntabelle-size data-vntabelle-start="25"><option>10</option><option>25</option><option>50</option><option>100</option></select>
      <button type="button" data-vntabelle-prev>&lsaquo;</button><span data-vntabelle-info></span><button type="button" data-vntabelle-next>&rsaquo;</button>
    </div>
  </div>
  <div class="vntabelle-rahmen"><div class="vntabelle-wrap">
    <table><thead><tr><th data-vnsort="0">Artikel</th></tr></thead><tbody><tr><td data-label="Artikel">Schraube</td></tr></tbody></table>
  </div></div>
</div>
MarkerBedeutung
data-vntabelle-rootWurzel; data-vntabelle-name = Titel (für den CSV-Export)
th[data-vnsort="<Spalte>"]Klick sortiert nach dieser Spalte (Index ab 0)
td[data-label]Spaltenname je Zelle (für die Handy-Ansicht)
data-vntabelle-search, -export, -print, -size, -prev, -next, -infoBedienelemente; data-vntabelle-start = Zeilen beim Start
data-vntabelle-readyVom Skript gesetzt

Panel-Felder: titel, zeigeSuche, zeigeSeiten, startZeilen (10/25/50/100), zeigeExport, zeigeDruck, Farben (blockFarbe, kopfFarbe, kopfTextFarbe, tabellenFarbe, textFarbe, wechselFarbe, linienFarbe), Größen (schriftGroesse, kopfGroesse, zellenAbstand, rundung) und Abstände. Das Skript steht im Baustein selbst.

Das Suchfeld (Seiten und PDFs) ruft zur Laufzeit assets/vn-search/search.php per fetch auf. Das Backend (SQLite-Volltext, PDF-Text-Auszug, Verwaltung mit Passwort) kopiert der Export nach assets/vn-search/, wenn der Block die Klasse vn-search trägt.

Syntax (Gerüst)

html
<section class="vn-search" group="Form" id="{{vn-id}}" style="--vns-accent:{{accentColor}};--vns-radius:{{inputRadius}}px">
  <vn-parameters> … </vn-parameters>
  <div class="vns-data" data-lang="{{vnsLang}}" data-scope="{{searchScope}}" data-maxresults="{{maxResults}}"
       data-snippetwords="{{snippetWords}}" data-placeholder="{{placeholderText}}" data-sticky="{{stickySearch}}"
       data-nfmode="{{vnsNfMode}}" data-nfurl="{{vnsNfUrl}}" data-nftext="{{vnsNfText}}"
       data-nfdelay="{{vnsNfDelay}}" data-nfpassquery="{{vnsNfPassQuery}}" style="display:none;"></div>
  <div class="container">
    <div class="vns-builder-dummy"> … Attrappe für den Editor … </div>
    <div class="vns-out"></div>
  </div>
  <script> … </script>
</section>
data-… am .vns-dataWerteBedeutung
data-langde, enSprache der Texte
data-scopeall, page, pdfWas durchsucht wird
data-maxresults3–400Höchstzahl Treffer
data-snippetwords6–64Wörter um die Fundstelle
data-placeholderTextPlatzhalter (leer = je nach Sprache)
data-stickySchalterSuchfeld oben festhalten (--vns-sticky-top = Abstand)
data-nfmodeoff, enter, autoWeiterleitung bei „keine Treffer“
data-nfurl, data-nftext, data-nfdelay, data-nfpassqueryAdresse, Text, Sekunden, SchalterZiel, Hinweis, Wartezeit, ?q= anhängen

Das Skript sucht seinen Block mit document.currentScript (Rückfall: document.querySelector('section.vn-search')). Es wertet html.is-builder aus (im Editor immer falsch, siehe Editor-Erkennung). Die Verwaltung der Suchdatenbank erreichen Sie nach dem Veröffentlichen unter …/assets/vn-search/admin/; Zugang (Benutzer, Passwort) legt das Werkzeug VN Suche im Programm-Profil ab und schreibt ihn beim Export in admin-config.php.

Blog: VN Blog#

Drei Bausteine („Blog: Liste + Artikel“, „Blog: Archiv“, „Neueste Beiträge“) binden ein eigenes PHP-Blog ein, das pro Website in vn-blog/ liegt (SQLite, Verwaltung mit TinyMCE, Bild-Upload).

Wie der Block das PHP einbindet#

Das PHP steckt in einem geschützten Skript, die Einstellungen gehen als JSON (Base64) an das Include:

html
<script type="text/x-vn-php"><?php
$vnblog_opts = json_decode(base64_decode('{{ btoa(unescape(encodeURIComponent(JSON.stringify({ view: view, perPage: Number(perPage) })))) }}'), true); /*VNBLOGLANG*/
include __DIR__ . '/vn-blog/include/blog.php';
?></script>
TeilBedeutung
type="text/x-vn-php"Geschützter PHP-Code: Der Editor führt ihn nicht aus, der Export setzt ihn roh ein; die Seite muss .php heißen
Base64-JSONZeichen A–Z a–z 0–9 + / =: kann keinen PHP-String sprengen
/*VNBLOGLANG*/Der Export ersetzt es durch $vnblog_lang = 'de' oder 'en' (nach lang der Seite)
data-vn-editor-onlyDie Attrappe mit Beispielbeiträgen ist im Editor sichtbar und wird im Export entfernt (div.vnblog-preview)
noTaggingDie Bausteine laufen nicht durch die Text-/Button-Markierung, sonst wäre die Attrappe bearbeitbar
BausteinIncludePanel-Felder (Auswahl)
Blog: Liste + Artikelinclude/blog.phpview (cards, list), perPage (1–24), excerptWords, showSearch, showViewToggle, showMeta, buttonText, Farben, radius
Blog: Archivinclude/archive.phpheading, blogPage (Seite mit dem Blog-Baustein), Farben
Neueste Beiträgeinclude/latest.phpheading, limit (1–20), showDate, blogPage, Farben

Einrichten und Verwalten#

Nach dem ersten Hochladen einmal …/vn-blog/install/ aufrufen (Admin-Benutzer und Passwort anlegen), danach schreiben Sie Beiträge unter …/vn-blog/admin/. Die Ordner vn-blog/data/ und vn-blog/uploads/ entstehen erst auf dem Server und gehören nie zum Export; ein erneuter Export überschreibt Beiträge, Bilder und Zugang nicht. Liegt die Seite nicht im Wurzelverzeichnis der Domain, stellen Sie BASE_PATH in inc/config.php vor dem Hochladen ein.

Animationen: VN Animation#

Das Werkzeug VN Animation legt CSS-Animationen auf Texte und Bilder. Gespeichert wird je Block in block.animOverrides = { [zielId]: { name, dur, delay, ease, loop, trigger } }; ohne animOverrides (alte Projekte) geschieht nichts.

Ziele und Einstellungen#

TeilWerteBedeutung
Ziel-IDtN (Text), fiN (freies Bild), k:<feld> (Feldbild)die stabilen Kennungen aus Direkt bearbeitbare Inhalte
namesiehe Liste untenAnimation (ungültiger Name = Eintrag wird ignoriert)
dur0,1–10Dauer in s (Standard 0,8)
delay0–10Verzögerung in s (Standard 0)
easeease, ease-out, ease-in, ease-in-out, linear, springVerlauf; spring = cubic-bezier(.34,1.56,.64,1)
loopSchalterendlos; Vorgabe an für pulse, heartbeat, float, glow, spin
triggerscroll, load, hoverBeim Sichtbarwerden (Standard); beim Laden; beim Darüberfahren

26 Animationen: Einblenden: fadeIn, fadeUp, fadeDown, fadeLeft, fadeRight, zoomIn, zoomOut, rotateIn, flipX, flipY, blurIn, revealUp, revealLeft, bounceIn, dropIn. Aufmerksamkeit: pulse, heartbeat, float, shake, wobble, swing, tada, rubber, flash, glow, spin.

Was im Export steht#

Das Element bekommt data-vn-anim, data-vn-anim-t und Inline-Variablen; die @keyframes und kurzen Regeln stehen einmal im <head> (nur die benutzten Animationen), bei „Sichtbarwerden“ startet ein kleines Skript am Ende der Seite die Animation (Klasse vn-in).

Geprüft (Überschrift mit fadeUp beim Scrollen, Bild mit zoomIn beim Darüberfahren):

html
<h2 style="--vn-a:vn-a-fadeUp;--vn-d:1s;--vn-dl:0.2s;--vn-e:ease-out;--vn-n:1" data-vn-anim="fadeUp" data-vn-anim-t="scroll">Titel</h2>
<img src="a.jpg" style="--vn-a:vn-a-zoomIn;--vn-d:0.8s;--vn-dl:0s;--vn-e:ease;--vn-n:1" data-vn-anim="zoomIn" data-vn-anim-t="hover">
css
@keyframes vn-a-fadeUp{from{opacity:0;transform:translateY(40px)}to{opacity:1;transform:none}}
[data-vn-anim-t="load"]{animation:var(--vn-a) var(--vn-d) var(--vn-e) var(--vn-dl) var(--vn-n) backwards}
[data-vn-anim-t="scroll"]{animation:var(--vn-a) var(--vn-d) var(--vn-e) var(--vn-dl) var(--vn-n) backwards;animation-play-state:paused}
[data-vn-anim-t="scroll"].vn-in{animation-play-state:running}
[data-vn-anim-t="hover"]:hover{animation:var(--vn-a) var(--vn-d) var(--vn-e) var(--vn-dl) var(--vn-n) backwards}
@media (prefers-reduced-motion:reduce){[data-vn-anim]{animation:none!important}}
VariableBedeutung
--vn-aName der Keyframes (vn-a-<name>)
--vn-d, --vn-dlDauer, Verzögerung
--vn-eVerlaufsfunktion
--vn-n1 oder infinite

Zusätzlich steht ein <noscript><style>[data-vn-anim]{animation:none!important}</style></noscript> im <head>. Ohne JavaScript oder bei „weniger Bewegung“ bleibt alles stehen.

Animation auf einzelnen Wörtern#

Auf einem Wort im Text steht die Animation als <span data-vn-anim="fadeUp" data-vn-anim-t="scroll" style="--vn-a:…;display:inline-block">. Der Text-Sanitizer lässt data-vn-anim (nur [A-Za-z0-9]{1,30}), data-vn-anim-t (scroll, load, hover; sonst scroll) und die --vn-*-Variablen durch (siehe Erlaubte Stile).

Im Editor#

Im Editor läuft die Animation nur in der Vorschau des Werkzeugs (Klasse vn-anim-play, nie dauerhaft). Die Elemente tragen data-vn-anim-edit="<name>"; bei geöffnetem Werkzeug werden animierte Elemente gestrichelt umrandet.

Übersetzer: VN Übersetzer#

Der Besucher bekommt einen Sprachknopf; der Text der Seite wird live über DeepL, Microsoft Translator oder Google Cloud Translation übersetzt (eigener Zugangsschlüssel). Der Block-Autor markiert nur Ausnahmen.

Was übersetzt wird#

vendor/vn-translate/vn-translate.js geht durch den Seitentext und übersetzt:

InhaltRegel
Textknoten im <body>jeder sichtbare Text, unabhängig vom Tag; Skript-, Style-, Noscript-, Template- und Textarea-Inhalt wird übersprungen
placeholderan input und textarea
valuean input[type=submit] und input[type=button]

Nicht übersetzt werden: Texte unter zwei Zeichen, reine Zahlen/Symbole (^[\d.,€$%\-–—/]+$), alle Attribute außer den oben (also nicht alt, title, aria-label).

Ausnahmen markieren#

MarkierungWirkung
class="notranslate"Das Element und alles darin bleibt unübersetzt
<span class="notranslate">Marke</span>dasselbe für ein Wort (Textleiste: Format „Keine Übersetzung“, siehe Format-Auswahl)
.vn-menue, [id$='-fenster'], .vn-uebersetzer-schalterimmer ausgeschlossen (der Sprachknopf selbst und seine Fenster)
SeitenIn den Einstellungen lassen sich Seiten ausnehmen (excludePages, zum Beispiel Impressum): für sie wird kein Skript eingebunden

Ablauf und Konfiguration#

TeilBeschreibung
Konfigurationwindow.VN_TRANSLATE_CONFIG = { endpunkt, original, sprachen, namen, position, darstellung } vor dem Skript; die Schlüssel stehen nie im Seitencode
Servervn-translate/translate.php (Wurzelebene der Website) mit vn-translate-config.php (Schlüssel, per .htaccess gesperrt)
Absicherungnur die eingestellten Sprachen; höchstens 500 Texte je Anfrage; Zielsprache nur als Sprachcode; Zwischenspeicher je Text und Sprache in vn-translate-cache/
Wahl des Besuchersin localStorage unter vn-uebersetzer-sprache
Ausgangsspracheaus lang der Seite (en-GB wird en; Standard de)
Positionbr, bl, tr, tl
Darstellungclassic, compact (aufklappbar am Handy), compactall (auch am Desktop)
Aktiv, wenneingeschaltet und Schlüssel und mindestens eine Zielsprache; sonst wird nichts exportiert

Die Sprachliste ist kommagetrennt (zum Beispiel en,fr,es), höchstens 30 Codes, Format ^[a-z]{2,3}([-_][a-z0-9]{2,8})?$. Die Namen im Menü stehen in der Sprache der Seite.