Backgrounds, media and tool blocks
Background widget (image, color, video, parallax, overlay), video background and video container, self-hosted video, lightbox, gallery, PDF viewer, search, blog, animations and translator – each with the markers the block author sets and what the program makes of them.
Overview#
Media and tool blocks follow two patterns:
- Marker in the template: The block author sets an attribute, a class or a widget (
fieldset type="background",data-bg-video,class="vn-zoom",[vn-video]…). The program recognizes it when rendering or exporting. - Runtime library: Only if the exported page contains a trace of it does the export copy the matching file from
vendor/and include it (see Bundled libraries).
Background widget#
fieldset type="background"#
The background widget in the properties panel consists of a fieldset with up to three inputs: image, color, video. The user picks one of the kinds.
Syntax
<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>(from gallery-content/vn-bloecke/src/artikel/inhalt/template.html, only image and color there)
| Part | Values | Default | Meaning |
|---|---|---|---|
fieldset (type="background") | — | — | The widget: every fieldset in the vn-parameters block that contains an input of type image, color or video. type="background" is the writing convention |
name | field name | bg | Name of the field; key in block.values and name in the expression |
title | text | Hintergrund | Label in the panel |
input[type=image] | address in value | empty | Image kind; the parallax attribute switches the parallax effect on as the default |
input[type=color] | #rrggbb in value | #000000 | Color kind |
input[type=video] | address in value | empty | Video kind (YouTube, Vimeo or file) |
selected | switch on an input | — | The preselected kind |
Which kind applies first: video if it is selected or the widget has nothing else; otherwise image if it is selected or there is no color; otherwise color.
What is stored in block.values[<name>]:
{ "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 }Access in the template and in LESS#
| Place | Expression | Value |
|---|---|---|
Template ({{…}}, vn-if, vn-class) | bg.type | image, color or video |
| Template | bg.value | For image/video: an object that also returns the address as text (toString); color: the hex value |
| Template | bg.value.url | Address (image and video) |
| Template | bg.parallax | Boolean |
| LESS | @bg-type | 'image', 'color', 'video' (string in single quotes) |
| LESS | @bg-value | For image and video: the address as a string, for color: the color |
| LESS | @bg-parallax | true or false |
Where image addresses appear as a LESS variable, write url(@bg-value) and not url({{…}}): @bg-value is already a string without url(…). Comparisons such as (@bg-type = "image") with double quotes are rewritten to single quotes by the program for you.
Checked (block with widget, three states rendered):
/* 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#
If the widget has the kind “Image” and “Parallax effect” is switched on (bg.parallax), the program appends background-attachment: fixed to the CSS of the block. This happens in addition to @bg-parallax, because the LESS of older blocks does not know the variable. There is no parallax for color and video.
& when (@bg-type = 'image') { background-image: url(@bg-value); background-size: cover; background-position: center; }Overlay: darkening the background#
There are two ways to darken an image.
1. Your own fields and LESS (recommended, full control): color and strength as panel fields, a layer via CSS.
<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. The overlay element vn-overlay: An element with the class vn-overlay becomes a covering layer.
<div class="vn-overlay" opacity="0.4" bg-color="#000000"></div>| Attribute | Value | Meaning |
|---|---|---|
Class vn-overlay | — | The element gets position:absolute; inset:0; pointer-events:none |
opacity | 0–1 | Opacity (becomes style="opacity", the attribute is removed) |
bg-color | color | Background color (becomes style="background-color") |
Checked: <div class="vn-overlay" opacity="0.4" bg-color="#000000"> becomes style="position: absolute; inset: 0px; pointer-events: none; opacity: 0.4; background-color: rgb(0, 0, 0);". The parent element must have position: relative.
Video background#
data-bg-video#
A block whose root element carries data-bg-video="<address>" gets a background video in the export. The address is usually an expression from the widget.
Syntax
<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>Value of data-bg-video | Effect |
|---|---|
| Address (YouTube, Vimeo, file) | Video is inserted |
empty, false, undefined, null, 0 | no video (blocks that are not in video mode render data-bg-video="false") |
The export includes vendor/vn-bgvideo/vn-bgvideo.js as soon as any block has a data-bg-video with a value (or the class vn-bgvid).
Checked: With bg.type = 'video', the example renders data-bg-video="https://youtu.be/abc12345678"; with image and color data-bg-video="false".
Fallback image layer#
When rendering, the program inserts as the first child a layer that shows the background image until the video is playing (and for “reduced motion”). It carries the class mbr-fallback-image; if the block already has an element of this class, it is used. In addition, renderer.js sets with :where() (low specificity, themes take precedence):
: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; }The content of a block sits in .container or .container-fluid above the video (z-index: 2).
Playback on the page#
For every [data-bg-video], vn-bgvideo.js creates a container div.vn-bgv (aria-hidden, pointer-events:none) and inserts it after the fallback image.
| Source | Structure |
|---|---|
| YouTube | <iframe> pointing to 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, filled at 16:9 (fit with 2 % overhang), faded in after loading (1.2 s delay) |
| Vimeo | <iframe> pointing to https://player.vimeo.com/video/<ID>?background=1&autoplay=1&loop=1&muted=1&byline=0&title=0&portrait=0 (+ &h=<hash>) |
| File | <video muted loop autoplay playsinline preload="auto"> with object-fit: cover; pauses off screen (IntersectionObserver, threshold 5 %); on error the container is removed |
| Reduced motion | prefers-reduced-motion: reduce: nothing is played, the fallback image stays |
The recognized address forms are youtube.com/watch?v=, youtube.com/embed/, youtube.com/shorts/, youtube.com/live/, youtu.be/, youtube-nocookie.com/embed/, vimeo.com/<number> (also with hash); everything else counts as a file.
Cookie consent (from version 1.3.100): The iframes for YouTube and Vimeo are only created at runtime in vn-bgvideo.js, so the export cannot block them in advance. The script therefore checks for itself: if VN Cookie Consent is switched on for the page (window.vnCookieConsent exists), it builds the video only once the visitor has agreed to "Marketing". Until then the fallback image stays in place. The script listens for the event vn-cc-consent (Event vn-cc-consent), which is fired on the document after every "Save", "Accept all" and "Necessary only"; if consent is already stored, the video loads immediately. If cookie consent is not switched on for the page, YouTube and Vimeo load immediately, as before.
The “Video background” block (vn-bgvid)#
The finished block (tab “Custom code”) is a hero with a video in the background and freely editable text and buttons on top.
Syntax (skeleton from src/vn-bgvideo-block.js, inputs shortened)
<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 && !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>| Part | Meaning |
|---|---|
section.vn-bgvid | Detection (the export includes vn-bgvideo.js) |
video.vn-bgvid-el | File video directly in the template: therefore it also plays in the editor (editorPlay) |
data-bg-video="{{videoUrl}}" | YouTube/Vimeo address. The title of the panel field says “only if no file is chosen”; the template, however, always sets the attribute from videoUrl. So do not fill in both |
.vn-bgvid-poster | Preview image (also carries the fallback image class) |
.vn-bgvid-overlay | Darkening (style flat, bottom, top, none; color, strength) |
.vn-bgvid-toggle | Pause/play button; sets the class vn-bgvid-paused on the section |
.vn-bgvid-scroll | Arrow: scrolls to the next block (smooth, without animation for “reduced motion”) |
vn-bgvid-mobile-poster | Class: below 768 px only the preview image, the video is hidden |
Particularities of the script for this element: it remembers the initialization as a JS property (sec.__vnBgvid), pauses the video off screen (unless the visitor paused it themselves) and sets muted.
File fields: videoFile, videoFile2, subtitleFile#
Panel fields of type text with these names automatically get a file selection (“Choose file …”) next to the input field (VIDEO_FILE_FIELDS).
| Field name | File kind | Allowed | Location |
|---|---|---|---|
videoFile | Video | mp4, webm, ogv, m4v; at most 4 GB | assets/videos/ |
videoFile2 | Video | as above (second version, e.g. WebM) | assets/videos/ |
subtitleFile | Subtitles | vtt; at most 2 MB | assets/subtitles/ |
<input type="text" title="Video-Datei (MP4/WebM) — Adresse oder Datei wählen" name="videoFile" value="">The file is copied from disk to disk (even several GB, without loading it into memory), the original name is kept (same file = no second copy). The project address goes into the field; the export rewrites it as relative. Typing an address (https://…) is also possible. In the “Free surface”, the same applies to fields e<no.>_file.
Video container vn-video#
The element [vn-video]#
An element with the attribute vn-video that contains an <iframe> (or <video>) is a video container. For this, the program offers a “Video address” field per video in the panel and converts the address into an embeddable one (editor and export).
Syntax
<div vn-video class="ratio ratio-16x9">
<iframe src="https://www.youtube.com/watch?v=aqz-KE-bpKQ" title="Video"></iframe>
</div>| Part | Meaning |
|---|---|
vn-video | Marker on the container (only if it contains iframe, video or data-vn-video-empty) |
data-vn-video-empty | A container without a video is kept as a placeholder |
Panel values per container (index i in document order starting at 0), in block.values:
| Value | Type | Default | Meaning |
|---|---|---|---|
_videoUrl<i> | address | src of the iframe in the template | YouTube, Vimeo or file |
_videoAuto<i> | switch | autoplay=1 of the template | Start automatically (always muted; never in the editor) |
_videoLoop<i> | switch | loop=1 of the template | Repeat |
Recognizing and converting addresses#
parseVideoUrl classifies every address; embedSrc returns the embeddable address.
Kind (kind) | Recognized | Embedding |
|---|---|---|
youtube | youtube.com/watch?v=, /embed/, /shorts/, /live/, /v/, youtu.be/, youtube-nocookie.com | https://www.youtube-nocookie.com/embed/<ID>?rel=0&modestbranding=1&playsinline=1 (+ start=<s>, with autoplay autoplay=1&mute=1, with repeat loop=1&playlist=<ID>) |
vimeo | vimeo.com/<no.>, /video/<no.>, with hash | https://player.vimeo.com/video/<no.> (+ h=<hash>, autoplay=1&muted=1, loop=1) |
file | ends in .mp4 .webm .ogv .m4v, starts with file: or contains assets/videos/ | <video controls playsinline preload="metadata"> (with autoplay autoplay muted; with repeat loop) |
other | everything else | Address unchanged as an iframe |
empty | empty | Hint line “Enter the video address in the properties panel” (data-vn-editor-only) |
Start time from the address: start=/t= with seconds (65) or 1m5s. The generated iframe gets allow="autoplay; fullscreen; picture-in-picture; encrypted-media", allowfullscreen, loading="lazy", referrerpolicy="strict-origin-when-cross-origin", title="Video".
Checked:
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=1With cookie consent switched on, the export blocks the YouTube iframe (youtube-nocookie.com) and, from version 1.3.100, also the Vimeo iframe (player.vimeo.com/video/…); both belong to the category "marketing" (see Automatic blocking).
Video in a popup window: iframe[data-src]#
For an <iframe data-src="{{modalVideo}}"> (the video is only loaded when a window is opened), only the address is converted: if it is of the kind YouTube or Vimeo, data-src becomes the embeddable address (with autoplay/loop from the address). The loading itself is handled by the block's window (for example a Bootstrap modal or the Popup: there vn-popup.js empties iframes on closing and restores them from data-vn-src).
Self-hosted video: the “Video” block#
The “Video (self-hosted)” block is in the tab “Custom code”. No request goes to third-party services; the file lies in assets/videos/.
Syntax (core from src/vn-video.js)
<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 && !clickToLoad" src="{{videoFile}}">
<source vn-if="!!videoFile && clickToLoad" data-src="{{videoFile}}">
<track vn-if="!!subtitleFile && !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>The switches are written as data-… values and become real attributes: {{…}} directly in an attribute such as controls would be destroyed during processing. applyVideoAttributes (editor and export) turns them into:
Attribute on video.vn-video-el | Values | Effect |
|---|---|---|
data-controls | 1/0 | controls (not with data-lazy) |
data-autoplay | 1/0 | autoplay + muted (never in the editor) |
data-loop | 1/0 | loop |
data-muted | 1/0 | muted (also with autoplay or data-viewplay="play") |
data-nodownload | 1 | controlslist="nodownload"; also blocks the right-click menu |
data-nopip | 1 | disablepictureinpicture |
data-nomenu | 1 | Block the right-click menu |
track[data-default="1"] | — | default on the subtitle track; the data-default is removed |
Additional runtime functions (vendor/vn-video/vn-video.js, root .vn-video; only if the page contains video.vn-video-el; without the script the video plays normally):
| Attribute | Values | Meaning |
|---|---|---|
data-start, data-end | seconds | Start/end time (with repeat it jumps back to the start) |
data-rate | number (0.5–2) | Playback speed |
data-volume | 0–100 | Volume (only without muted) |
data-viewplay | none, pause, play | When scrolling: pause = pause when less than 50 % visible; play = start muted and pause |
data-exclusive | 1 | Only one video at a time (others pause) |
data-lazy | 1 | Load only on click (preview image + .vn-video-play): source[data-src] and track[data-src] only then become src |
data-player | vn or native | vn: own control bar, identical in all browsers (color via --vn-vp-accent); native: the browser's control bar |
data-vn-ready, data-vn-loaded | 1 | Set by the script (initialized / sources loaded) |
Class vn-video-error | — | Set on .vn-video when the video does not load (CSS shows “The video is not available.”) |
Class vn-video-started | — | After the first start in lazy mode |
The VN Player supports keyboard (c = subtitles, Home, End …), a playback bar, volume and full screen.
Lightbox#
The VN Lightbox makes images on the whole website zoomable and movable. It is switched on in the page settings (not in the block). The block author only marks what is to be zoomed, or excludes images.
Markers#
| Marker | Where | Effect |
|---|---|---|
class="vn-zoom" | img | This image opens the lightbox (magnifier icon on hover) |
class="vn-zoom" | Container (not img) | All images inside are captured and form a gallery |
data-vn-skip | img in a .vn-zoom container | Exclude this image |
class="vn-nozoom" or data-vn-nozoom | Image or ancestor | Never zoom |
data-vn-caption | Image or element | Caption in the lightbox (otherwise alt, title, figcaption, link title) |
data-vn-full (also data-large) | img | Address of the large version (otherwise src; placeholder data: addresses and lazily loaded data-src, data-lazy-src, data-original, data-echo are taken into account) |
data-vn-group="<name>" | img | Images with the same name form one gallery (browsing between them) |
data-vn-badge="off" | img | No magnifier icon |
Syntax
<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>Galleries without markers: In the mode “Galleries + vn-zoom” (default), the lightbox automatically captures images with a modal trigger (img[data-bs-toggle="modal"], data-toggle="modal", data-bs-slide-to, data-slide-to), grouped by data-bs-target/data-target. In the mode “Every content image” (all), unmarked images are added if they are wide enough; excluded are logos and icons (class names with logo, icon, avatar, badge, bullet, arrow, sprite; .svg images), images in nav, .navbar, button, .modal and images in links with a real address.
Page settings#
siteSettings.vnLightbox (invalid values fall back to the default):
| Key | Values | Default | Meaning |
|---|---|---|---|
enabled | switch | off | Include the lightbox (script + CSS) |
mode | gallery, all, class | gallery | Only galleries + vn-zoom; every content image; only vn-zoom |
minWidth | 50–2000 | 250 | Minimum width in px (mode all) |
gallery | switch | on | Automatically adopt imported galleries |
badge | switch | on | Magnifier icon |
opacity | 30–100 | 94 | Opacity of the background in % |
maxScale | 2–15 | 6 | Maximum zoom |
closeOnBackdrop | switch | on | A click outside closes |
caption | switch | on | Show caption |
captionColor, captionSize, counterSize, buttonSize, buttonColor | color, px | default | Appearance (0 = automatic) |
exclude | one line per exception | empty | Exceptions: page pattern (impressum.html, blog/*, *preis*), block identifier (#galerie1 or galerie1) or CSS expression (.keine-lightbox, [data-schutz]); lines starting with / are comments |
The configuration is available as window.VN_LIGHTBOX_CONFIG before the script. The lightbox switches itself off when body carries the class is-builder (the program does not set it). Images inserted later (CMS, filter, Ajax) are captured by a MutationObserver.
Gallery: VN Gallery#
The “VN Gallery” block is created via the VN Gallery tool (multiple selection, order, captions). Block authors do not write it by hand; this entry shows which markers the runtime evaluates.
| Class / marker | Meaning |
|---|---|
vn-galerie-host | Identifying mark of the gallery (GALLERY_HOST_CLASS) |
.vn-gal-wrap | Container; settings as CSS variables (--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-karussell | View (grid, masonry, carousel, …); selection ansicht, lightbox, uebergangArt in the panel |
.vn-gal-lb-radio | Hidden radio buttons: the lightbox works purely with CSS (radio + label for); disabled in the editor (disabled) so that a click does not put the large view over the work area |
figure.vn-gal-item, img.vn-gal-thumb, figcaption.vn-gal-caption | Single image with caption (the caption can be changed by clicking) |
.vn-gal-bar, .vn-gal-prev, .vn-gal-next, .vn-gal-dots | Arrows and dots of the carousel (script; without the script a scroll bar remains) |
The carousel script is part of the block itself (GALLERY_CAROUSEL_SCRIPT) and remembers the initialization as a JS property (grid.vnGalInit); “reduced motion” switches off the smooth scrolling.
PDF viewer and tables#
PDF: iframe[data-vn-pdf-src]#
The “VN PDF Viewer” block embeds the bundled Mozilla PDF.js 3.11.174. The PDF lies byte for byte under assets/vn-pdf-viewer/dateien/ (only [A-Za-z0-9._-]+.pdf, at most 300 MB).
Syntax
<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()) }}&vnedit={{bearbeitungErlauben}}#search={{encodeURIComponent(anfangssuche)}}&phrase={{exaktePhrase}}"
title="PDF-Betrachter"></iframe>| Part | Meaning |
|---|---|
data-vn-pdf-src | Address of the viewer; not src in the template: in the editor the program sets it to the bundled viewer (without src nothing loads into the void), in the export it becomes src (resolvePdfIframesForExport) |
?file= | PDF relative to the viewer (../../dateien/<name>.pdf) or a full address |
&vnedit= | true enables the viewer's PDF editing |
#search=…&phrase= | Search on opening; phrase=true = exact phrase |
The export copies the viewer (about 6 MB) only if a page contains the viewer address, plus exactly the PDFs that a block refers to (viewer.html?file=../../dateien/<name>.pdf).
Panel fields of the block: pdfDatei, titel, breite (30–100 %), hoehe (400–1600 px), blockFarbe, anfangssuche, exaktePhrase, bearbeitungErlauben, paddingTop, paddingBottom. The block does not go through the text/button marking (noTagging).
CSV and XLSX as a table: VN Table#
From a CSV or Excel file, the “VN Table” block creates a fixed, searchable, sortable table; the source file is not published. Everything runs in the browser.
Syntax (skeleton)
<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>‹</button><span data-vntabelle-info></span><button type="button" data-vntabelle-next>›</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>| Marker | Meaning |
|---|---|
data-vntabelle-root | Root; data-vntabelle-name = title (for the CSV export) |
th[data-vnsort="<column>"] | A click sorts by this column (index starting at 0) |
td[data-label] | Column name per cell (for the phone view) |
data-vntabelle-search, -export, -print, -size, -prev, -next, -info | Controls; data-vntabelle-start = rows at start |
data-vntabelle-ready | Set by the script |
Panel fields: titel, zeigeSuche, zeigeSeiten, startZeilen (10/25/50/100), zeigeExport, zeigeDruck, colors (blockFarbe, kopfFarbe, kopfTextFarbe, tabellenFarbe, textFarbe, wechselFarbe, linienFarbe), sizes (schriftGroesse, kopfGroesse, zellenAbstand, rundung) and spacing. The script is part of the block itself.
Search: VN Search#
The search field (pages and PDFs) calls assets/vn-search/search.php at runtime via fetch. The backend (SQLite full text, PDF text excerpt, administration with password) is copied by the export to assets/vn-search/ if the block carries the class vn-search.
Syntax (skeleton)
<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-… on .vns-data | Values | Meaning |
|---|---|---|
data-lang | de, en | Language of the texts |
data-scope | all, page, pdf | What is searched |
data-maxresults | 3–400 | Maximum number of hits |
data-snippetwords | 6–64 | Words around the match |
data-placeholder | text | Placeholder (empty = depends on the language) |
data-sticky | switch | Keep the search field fixed at the top (--vns-sticky-top = distance) |
data-nfmode | off, enter, auto | Redirect on “no hits” |
data-nfurl, data-nftext, data-nfdelay, data-nfpassquery | address, text, seconds, switch | Target, hint, waiting time, append ?q= |
The script finds its block with document.currentScript (fallback: document.querySelector('section.vn-search')). It evaluates html.is-builder (always false in the editor, see Editor detection). After publishing, you reach the administration of the search database at …/assets/vn-search/admin/; the VN Search tool stores the credentials (user, password) in the program profile and writes them to admin-config.php on export.
Blog: VN Blog#
Three blocks (“Blog: List + Article”, “Blog: Archive”, “Latest posts”) include a dedicated PHP blog that lies per website in vn-blog/ (SQLite, administration with TinyMCE, image upload).
How the block includes the PHP#
The PHP sits in a protected script, the settings are passed as JSON (Base64) to the include:
<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>| Part | Meaning |
|---|---|
type="text/x-vn-php" | Protected PHP code: the editor does not execute it, the export inserts it raw; the page must be named .php |
| Base64 JSON | Characters A–Z a–z 0–9 + / =: cannot break a PHP string |
/*VNBLOGLANG*/ | The export replaces it with $vnblog_lang = 'de' or 'en' (according to lang of the page) |
data-vn-editor-only | The dummy with sample posts is visible in the editor and removed in the export (div.vnblog-preview) |
noTagging | The blocks do not go through the text/button marking, otherwise the dummy would be editable |
| Block | Include | Panel fields (selection) |
|---|---|---|
| Blog: List + Article | include/blog.php | view (cards, list), perPage (1–24), excerptWords, showSearch, showViewToggle, showMeta, buttonText, colors, radius |
| Blog: Archive | include/archive.php | heading, blogPage (page with the blog block), colors |
| Latest posts | include/latest.php | heading, limit (1–20), showDate, blogPage, colors |
Setting up and managing#
After the first upload, call …/vn-blog/install/ once (create admin user and password); after that you write posts at …/vn-blog/admin/. The folders vn-blog/data/ and vn-blog/uploads/ only come into existence on the server and never belong to the export; a renewed export does not overwrite posts, images and credentials. If the page is not in the root directory of the domain, set BASE_PATH in inc/config.php before uploading.
Animations: VN Animation#
The VN Animation tool applies CSS animations to texts and images. It is stored per block in block.animOverrides = { [targetId]: { name, dur, delay, ease, loop, trigger } }; without animOverrides (old projects) nothing happens.
Targets and settings#
| Part | Values | Meaning |
|---|---|---|
| Target ID | tN (text), fiN (free image), k:<field> (field image) | the stable identifiers from Directly editable content |
name | see list below | Animation (invalid name = entry is ignored) |
dur | 0.1–10 | Duration in s (default 0.8) |
delay | 0–10 | Delay in s (default 0) |
ease | ease, ease-out, ease-in, ease-in-out, linear, spring | Easing; spring = cubic-bezier(.34,1.56,.64,1) |
loop | switch | endless; default on for pulse, heartbeat, float, glow, spin |
trigger | scroll, load, hover | When becoming visible (default); on load; on hover |
26 animations: Fade-in: fadeIn, fadeUp, fadeDown, fadeLeft, fadeRight, zoomIn, zoomOut, rotateIn, flipX, flipY, blurIn, revealUp, revealLeft, bounceIn, dropIn. Attention: pulse, heartbeat, float, shake, wobble, swing, tada, rubber, flash, glow, spin.
What the export contains#
The element gets data-vn-anim, data-vn-anim-t and inline variables; the @keyframes and short rules appear once in the <head> (only the animations used); for “when becoming visible”, a small script at the end of the page starts the animation (class vn-in).
Checked (heading with fadeUp on scroll, image with zoomIn on hover):
<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">@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}}| Variable | Meaning |
|---|---|
--vn-a | Name of the keyframes (vn-a-<name>) |
--vn-d, --vn-dl | Duration, delay |
--vn-e | Easing function |
--vn-n | 1 or infinite |
In addition, a <noscript><style>[data-vn-anim]{animation:none!important}</style></noscript> is placed in the <head>. Without JavaScript or with “reduced motion”, everything stays still.
Animation on single words#
On a word in the text, the animation is written as <span data-vn-anim="fadeUp" data-vn-anim-t="scroll" style="--vn-a:…;display:inline-block">. The text sanitizer lets data-vn-anim (only [A-Za-z0-9]{1,30}), data-vn-anim-t (scroll, load, hover; otherwise scroll) and the --vn-* variables through (see Allowed styles).
In the editor#
In the editor, the animation runs only in the preview of the tool (class vn-anim-play, never permanently). The elements carry data-vn-anim-edit="<name>"; while the tool is open, animated elements are outlined with a dashed line.
Translator: VN Translator#
The visitor gets a language button; the text of the page is translated live via DeepL, Microsoft Translator or Google Cloud Translation (your own access key). The block author only marks exceptions.
What is translated#
vendor/vn-translate/vn-translate.js goes through the page text and translates:
| Content | Rule |
|---|---|
Text nodes in the <body> | all visible text, regardless of the tag; the content of script, style, noscript, template and textarea is skipped |
placeholder | on input and textarea |
value | on input[type=submit] and input[type=button] |
Not translated: texts under two characters, pure numbers/symbols (^[\d.,€$%\-–—/]+$), all attributes except those above (so not alt, title, aria-label).
Marking exceptions#
| Marker | Effect |
|---|---|
class="notranslate" | The element and everything inside it stays untranslated |
<span class="notranslate">Marke</span> | the same for a single word (text bar: format “No translation”, see Format selection) |
.vn-menue, [id$='-fenster'], .vn-uebersetzer-schalter | always excluded (the language button itself and its windows) |
| Pages | In the settings, pages can be excluded (excludePages, for example the legal notice): no script is included for them |
Flow and configuration#
| Part | Description |
|---|---|
| Configuration | window.VN_TRANSLATE_CONFIG = { endpunkt, original, sprachen, namen, position, darstellung } before the script; the keys are never in the page code |
| Server | vn-translate/translate.php (root level of the website) with vn-translate-config.php (keys, blocked via .htaccess) |
| Safeguards | only the configured languages; at most 500 texts per request; target language only as a language code; cache per text and language in vn-translate-cache/ |
| Visitor's choice | in localStorage under vn-uebersetzer-sprache |
| Source language | from lang of the page (en-GB becomes en; default de) |
| Position | br, bl, tr, tl |
| Appearance | classic, compact (collapsible on phones), compactall (also on desktop) |
| Active when | switched on and key and at least one target language; otherwise nothing is exported |
The language list is comma-separated (for example en,fr,es), at most 30 codes, format ^[a-z]{2,3}([-_][a-z0-9]{2,8})?$. The names in the menu are in the language of the page.