VN-Designer Developer Documentation
09

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:

  1. 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.
  2. 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

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>

(from gallery-content/vn-bloecke/src/artikel/inhalt/template.html, only image and color there)

PartValuesDefaultMeaning
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
namefield namebgName of the field; key in block.values and name in the expression
titletextHintergrundLabel in the panel
input[type=image]address in valueemptyImage kind; the parallax attribute switches the parallax effect on as the default
input[type=color]#rrggbb in value#000000Color kind
input[type=video]address in valueemptyVideo kind (YouTube, Vimeo or file)
selectedswitch 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>]:

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 }

Access in the template and in LESS#

PlaceExpressionValue
Template ({{…}}, vn-if, vn-class)bg.typeimage, color or video
Templatebg.valueFor image/video: an object that also returns the address as text (toString); color: the hex value
Templatebg.value.urlAddress (image and video)
Templatebg.parallaxBoolean
LESS@bg-type'image', 'color', 'video' (string in single quotes)
LESS@bg-valueFor image and video: the address as a string, for color: the color
LESS@bg-parallaxtrue 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):

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#

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.

less
& 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.

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. The overlay element vn-overlay: An element with the class vn-overlay becomes a covering layer.

html
<div class="vn-overlay" opacity="0.4" bg-color="#000000"></div>
AttributeValueMeaning
Class vn-overlay—The element gets position:absolute; inset:0; pointer-events:none
opacity0–1Opacity (becomes style="opacity", the attribute is removed)
bg-colorcolorBackground 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

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>
Value of data-bg-videoEffect
Address (YouTube, Vimeo, file)Video is inserted
empty, false, undefined, null, 0no 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):

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; }

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.

SourceStructure
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 motionprefers-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)

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>
PartMeaning
section.vn-bgvidDetection (the export includes vn-bgvideo.js)
video.vn-bgvid-elFile 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-posterPreview image (also carries the fallback image class)
.vn-bgvid-overlayDarkening (style flat, bottom, top, none; color, strength)
.vn-bgvid-togglePause/play button; sets the class vn-bgvid-paused on the section
.vn-bgvid-scrollArrow: scrolls to the next block (smooth, without animation for “reduced motion”)
vn-bgvid-mobile-posterClass: 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 nameFile kindAllowedLocation
videoFileVideomp4, webm, ogv, m4v; at most 4 GBassets/videos/
videoFile2Videoas above (second version, e.g. WebM)assets/videos/
subtitleFileSubtitlesvtt; at most 2 MBassets/subtitles/
html
<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

html
<div vn-video class="ratio ratio-16x9">
  <iframe src="https://www.youtube.com/watch?v=aqz-KE-bpKQ" title="Video"></iframe>
</div>
PartMeaning
vn-videoMarker on the container (only if it contains iframe, video or data-vn-video-empty)
data-vn-video-emptyA container without a video is kept as a placeholder

Panel values per container (index i in document order starting at 0), in block.values:

ValueTypeDefaultMeaning
_videoUrl<i>addresssrc of the iframe in the templateYouTube, Vimeo or file
_videoAuto<i>switchautoplay=1 of the templateStart automatically (always muted; never in the editor)
_videoLoop<i>switchloop=1 of the templateRepeat

Recognizing and converting addresses#

parseVideoUrl classifies every address; embedSrc returns the embeddable address.

Kind (kind)RecognizedEmbedding
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>, with autoplay autoplay=1&mute=1, with repeat loop=1&playlist=<ID>)
vimeovimeo.com/<no.>, /video/<no.>, with hashhttps://player.vimeo.com/video/<no.> (+ h=<hash>, autoplay=1&muted=1, loop=1)
fileends in .mp4 .webm .ogv .m4v, starts with file: or contains assets/videos/<video controls playsinline preload="metadata"> (with autoplay autoplay muted; with repeat loop)
othereverything elseAddress unchanged as an iframe
emptyemptyHint 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:

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

With 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)

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>

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-elValuesEffect
data-controls1/0controls (not with data-lazy)
data-autoplay1/0autoplay + muted (never in the editor)
data-loop1/0loop
data-muted1/0muted (also with autoplay or data-viewplay="play")
data-nodownload1controlslist="nodownload"; also blocks the right-click menu
data-nopip1disablepictureinpicture
data-nomenu1Block 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):

AttributeValuesMeaning
data-start, data-endsecondsStart/end time (with repeat it jumps back to the start)
data-ratenumber (0.5–2)Playback speed
data-volume0–100Volume (only without muted)
data-viewplaynone, pause, playWhen scrolling: pause = pause when less than 50 % visible; play = start muted and pause
data-exclusive1Only one video at a time (others pause)
data-lazy1Load only on click (preview image + .vn-video-play): source[data-src] and track[data-src] only then become src
data-playervn or nativevn: own control bar, identical in all browsers (color via --vn-vp-accent); native: the browser's control bar
data-vn-ready, data-vn-loaded1Set 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.

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.

MarkerWhereEffect
class="vn-zoom"imgThis 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-skipimg in a .vn-zoom containerExclude this image
class="vn-nozoom" or data-vn-nozoomImage or ancestorNever zoom
data-vn-captionImage or elementCaption in the lightbox (otherwise alt, title, figcaption, link title)
data-vn-full (also data-large)imgAddress 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>"imgImages with the same name form one gallery (browsing between them)
data-vn-badge="off"imgNo magnifier icon

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>

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.

siteSettings.vnLightbox (invalid values fall back to the default):

KeyValuesDefaultMeaning
enabledswitchoffInclude the lightbox (script + CSS)
modegallery, all, classgalleryOnly galleries + vn-zoom; every content image; only vn-zoom
minWidth50–2000250Minimum width in px (mode all)
galleryswitchonAutomatically adopt imported galleries
badgeswitchonMagnifier icon
opacity30–10094Opacity of the background in %
maxScale2–156Maximum zoom
closeOnBackdropswitchonA click outside closes
captionswitchonShow caption
captionColor, captionSize, counterSize, buttonSize, buttonColorcolor, pxdefaultAppearance (0 = automatic)
excludeone line per exceptionemptyExceptions: 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 / markerMeaning
vn-galerie-hostIdentifying mark of the gallery (GALLERY_HOST_CLASS)
.vn-gal-wrapContainer; 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-karussellView (grid, masonry, carousel, …); selection ansicht, lightbox, uebergangArt in the panel
.vn-gal-lb-radioHidden 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-captionSingle image with caption (the caption can be changed by clicking)
.vn-gal-bar, .vn-gal-prev, .vn-gal-next, .vn-gal-dotsArrows 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

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>
PartMeaning
data-vn-pdf-srcAddress 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)

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>
MarkerMeaning
data-vntabelle-rootRoot; 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, -infoControls; data-vntabelle-start = rows at start
data-vntabelle-readySet 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.

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)

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-… on .vns-dataValuesMeaning
data-langde, enLanguage of the texts
data-scopeall, page, pdfWhat is searched
data-maxresults3–400Maximum number of hits
data-snippetwords6–64Words around the match
data-placeholdertextPlaceholder (empty = depends on the language)
data-stickyswitchKeep the search field fixed at the top (--vns-sticky-top = distance)
data-nfmodeoff, enter, autoRedirect on “no hits”
data-nfurl, data-nftext, data-nfdelay, data-nfpassqueryaddress, text, seconds, switchTarget, 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:

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>
PartMeaning
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 JSONCharacters 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-onlyThe dummy with sample posts is visible in the editor and removed in the export (div.vnblog-preview)
noTaggingThe blocks do not go through the text/button marking, otherwise the dummy would be editable
BlockIncludePanel fields (selection)
Blog: List + Articleinclude/blog.phpview (cards, list), perPage (1–24), excerptWords, showSearch, showViewToggle, showMeta, buttonText, colors, radius
Blog: Archiveinclude/archive.phpheading, blogPage (page with the blog block), colors
Latest postsinclude/latest.phpheading, 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#

PartValuesMeaning
Target IDtN (text), fiN (free image), k:<field> (field image)the stable identifiers from Directly editable content
namesee list belowAnimation (invalid name = entry is ignored)
dur0.1–10Duration in s (default 0.8)
delay0–10Delay in s (default 0)
easeease, ease-out, ease-in, ease-in-out, linear, springEasing; spring = cubic-bezier(.34,1.56,.64,1)
loopswitchendless; default on for pulse, heartbeat, float, glow, spin
triggerscroll, load, hoverWhen 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):

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}}
VariableMeaning
--vn-aName of the keyframes (vn-a-<name>)
--vn-d, --vn-dlDuration, delay
--vn-eEasing function
--vn-n1 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:

ContentRule
Text nodes in the <body>all visible text, regardless of the tag; the content of script, style, noscript, template and textarea is skipped
placeholderon input and textarea
valueon 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#

MarkerEffect
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-schalteralways excluded (the language button itself and its windows)
PagesIn the settings, pages can be excluded (excludePages, for example the legal notice): no script is included for them

Flow and configuration#

PartDescription
Configurationwindow.VN_TRANSLATE_CONFIG = { endpunkt, original, sprachen, namen, position, darstellung } before the script; the keys are never in the page code
Servervn-translate/translate.php (root level of the website) with vn-translate-config.php (keys, blocked via .htaccess)
Safeguardsonly 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 choicein localStorage under vn-uebersetzer-sprache
Source languagefrom lang of the page (en-GB becomes en; default de)
Positionbr, bl, tr, tl
Appearanceclassic, compact (collapsible on phones), compactall (also on desktop)
Active whenswitched 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.