Directly Editable Content
What can be edited with a click in the canvas (text, images, icons, buttons, menus, links), how the block author marks, triggers or prevents this in the template, and how CMS and popup features attach to the block.
Overview#
In the canvas, almost everything is clicked and changed directly: texts, images, icons, buttons, menu items, links. A block author writes no editor code for this. They write normal HTML in template.html; on import, the program detects what is editable and assigns stable identifiers.
The sequence is always the same:
- Import: Helper functions (
tagEditableText,tagButtons,tagIcons,tagFreeImages,tagImageFields) set identifiers in the template (data-vn-text-id,data-vn-button-id,data-vn-icon-id,data-vn-free-image-id,data-vn-image-key). The same functions run again every time a project is loaded (idempotent: existing identifiers stay, only new elements get fresh ones). - Editing: The user's changes do not end up in the template but in overrides on the block. The template stays unchanged.
- Rendering (editor): After every render, the program lays the overrides over the freshly rendered HTML again and makes the elements clickable.
- Export: The same overrides are baked in permanently; all editor traces (identifiers,
contenteditable, helper classes) are removed.
| Override on the block | Key | Content |
|---|---|---|
textOverrides | t0, t1 … | changed content (innerHTML) of a text field |
textTagOverrides | t0 … | chosen tag (H1, H2, H3, P …) |
textLinkOverrides | t0 … | { href, newTab, colorClass, rel, download } for text fields that are themselves an <a> |
textAlignOverrides | t0 … | left, center, right, justify |
buttonOverrides | btn0 … | text, link, color, shape, icon of a button |
iconOverrides | icon0 … | icon, size, color, link |
navIconOverrides | t0 … (menu item) | icon before/after a menu item |
imageOverrides | fi1 … | address of a free image |
imageLinkOverrides | fi1 or k:<field> | { href, target, rel, download } around an image |
imageAltOverrides | fi1, k:<field>; t:<id>; s:<id> | alt text; title (t:); size (s:) |
animOverrides | t0, fi1, k:<field> | animation (see Animations) |
Text#
Which elements become text fields#
Every element that carries running text automatically becomes a text field (contenteditable) with an identifier data-vn-text-id="tN". The author does not have to mark anything. The following are captured, in this order of identifier assignment:
- Standard text tags:
h1–h6,p,li,blockquote,figcaption(only the outermost one in each case, no double marking), plus menu links and loose links (see below). - List fields
ul/olwithdata-multilineorvn-article(see List fields). - Leaf elements: every other element that contains only text and inline tags, for example
<div>Text</div>,<span>,<td>,<label>,<small>,<em>,<dt>.
Syntax
<h2>Überschrift</h2>
<p>Absatz mit <b>fett</b> und <a href="#kontakt">Link</a>.</p>
<div class="hinweis">Ein Blatt-Element mit Text</div>Result after the import (verified)
<h2 data-vn-text-id="t0">Überschrift</h2>
<p data-vn-text-id="t1">Absatz mit <b>fett</b> und <a href="#kontakt" data-vn-text-id="t2">Link</a>.</p>
<div class="hinweis" data-vn-text-id="t3">Ein Blatt-Element mit Text</div>The identifiers are assigned in this order: first headings, paragraphs and list items, then menu links and loose links, and finally the leaf elements. A link inside a paragraph gets its own, nested identifier (t2 in the example): the link is a separate field for address and color, its text remains part of the paragraph.
| Element | Text field? | Remark |
|---|---|---|
h1–h6, p, li, blockquote, figcaption | yes | Outside navigation, form, button, link |
div, span, td, th, label, small, em, dt … | yes, if leaf | Only text and inline tags inside |
Container with paragraph/heading children (div.wrap > p) | no | Only the children become fields |
a.nav-link, a.navbar-brand, a.dropdown-item | yes | Separate branch, also inside nav |
a (loose links, not .btn) with text | yes | The <a> itself is the field, link via the text toolbar |
Text consisting only of {{placeholder}} | no | Belongs to the properties panel |
script, style, textarea, option, select, button, iframe, svg, noscript, template, pre, code, input, header (panel header), fieldset | never | NEVER_TEXT_TAGS |
Everything inside nav, button, select, form, a, vn-parameters | no | SKIP_ANCESTOR_TAGS; a narrower list applies to menu links and loose links (nav is allowed there) |
data-vn-text-id#
Identifier of a text field, assigned by the program. It is the link between the template and textOverrides. Authors do not set it themselves. It matters for anything that should address a field later: Animations, CMS keys and extensions (ctx.blocks.texts).
Syntax
<h2 data-vn-text-id="t0">Titel</h2>| Property | Value | Meaning |
|---|---|---|
| Format | t + number (t0, t1 …) | Consecutive, starting from the highest existing index |
| Lifetime | Editor and template | Removed on export (bakeTextOverridesForExport) |
List fields: data-multiline and vn-article#
A list in which Enter should create a new entry is a single text field. You mark this on the ul/ol itself. The entries inside are then not separate fields.
Syntax
<ul data-multiline>
<li>Erster Punkt</li>
<li>Zweiter Punkt</li>
</ul>
<ol vn-article>
<li>Schritt eins</li>
</ol>| Attribute | Value | Default | Meaning |
|---|---|---|---|
data-multiline | Switch (no value) | off | On ul, ol (expandable list) or on div: the field may contain lists, paragraphs, quotes and headings |
vn-article | Switch | off | Like data-multiline, on ul/ol |
Nested lists: only the outermost one is the field. A div field or a field with data-multiline keeps ul, ol, li, p, blockquote, h1–h6 when saving (see Allowed tags).
Placeholders in text#
If the entire text of an element consists of a {{placeholder}}, the element is not a text field; the value is maintained in the properties panel. If a placeholder appears only in the middle of the text (x {{a}} y), the element is a text field.
<h2>{{title}}</h2>
<p>Preis ab {{preis}} €</p> Allowed tags when saving (sanitizer)#
Every change is cleaned by sanitizeRichTextHtml on render and on export. An allowlist determines what stays in the text:
| Group | Tags |
|---|---|
| Inline allowed | strong, b, em, i, u, a, span, br, code, mark, sub, sup, small, abbr, kbd, samp, var, q, cite, dfn, s, strike, del, ins, time, data, wbr, bdi, bdo, ruby, rt, rp |
Blocks, only in multi-line fields (div or data-multiline) | ul, ol, li, p, blockquote, h1–h6 |
Unwrapped (content stays, wrapper is dropped, former block boundary becomes <br>) | div, section, article, table parts, figure, header, footer, main, aside, nav, hr, pre, form and everything unknown |
| Removed | Comments |
| Unchanged | <script type="text/x-vn-php"> (protected PHP code) |
Verified example (input as a saved override, result after baking in):
Hallo <b class="foo" onclick="x()">B</b> <div>blk</div>
<span style="color:red;position:fixed;text-shadow:0 0 4px #f00" class="akzent vn-editable-x n6owBd">s</span>
<img src=x onerror=1><i class="bi bi-star vn-ic" style="font-size:2em">i</i>
Hallo <b class="foo">B</b><br>blk<br>
<span style="color:red;text-shadow:rgb(255, 0, 0) 0px 0px 4px" class="akzent">s</span>
<i class="bi bi-star vn-ic">i</i>Allowed attributes and classes#
On allowed inline tags, only these attributes remain:
| Tag | Allowed attributes |
|---|---|
a | href, target, rel, download, title, aria-label, data-vn-cookie-settings |
q | cite |
time | datetime |
data | value |
abbr, dfn | title |
del, ins | datetime, cite |
bdo | dir |
span | style (filtered, see below), data-vn-text-color, data-vn-anim, data-vn-anim-t, data-vn-svg, data-vn-svg-mode, tooltip attributes |
| all | class (filtered) |
Classes are kept if the name is a simple token (no quotation marks, <, >, &, =, backtick). The following are dropped: classes starting with vn-editable, vn-anim-…, vn-tip/vn-tip-plain (set by the tooltip branch itself) and known foreign classes of web page frameworks. A <span class="akzent"> in the text therefore survives saving, export and reloading.
Allowed styles on the span#
A <span> may keep these inline styles:
| Source | Properties |
|---|---|
| Text toolbar | color, font-family, font-size, font-weight, font-style |
| VN Text Effects | text-shadow, background-color, background-image, background-clip (with -webkit-background-clip), background-repeat, background-size, padding-left, padding-right, the four border-*-radius, box-decoration-break (with prefix), -webkit-text-stroke-width, -webkit-text-stroke-color, -webkit-text-fill-color, paint-order, text-decoration-line, text-decoration-style, text-decoration-color, text-decoration-thickness, text-underline-offset, letter-spacing, text-transform, font-variant-caps |
| VN Animation | the variables --vn-a, --vn-d, --vn-dl, --vn-e, --vn-n and display:inline-block |
| Custom SVG icon | Style is rebuilt from data-vn-svg and data-vn-svg-mode |
Values with url(…), expression, javascript, @import, < or > are discarded. All other properties (for example position) are dropped.
Foreign markup from web pages#
If a user pastes text from an AI chat page or a search engine, foreign markup comes along (attributes jscontroller, jsaction, data-sfc-…, data-section-id together with data-start/data-end, and known framework classes). There are two levels of protection against this:
- Pasting and dragging into a text field always happens as plain text. Line breaks become
<br>. stripForeignFrameworkMarkupcleans a whole template of these fingerprints on loading and when applying in the code editor: the element is unwrapped, its content stays. If an empty text field precedes it, the content slides into it.
Heading level and alignment#
For a field, the text toolbar offers: paragraph or heading 1–3, and the alignment left, center, right, justify.
| Override | Effect on the template element |
|---|---|
textTagOverrides[tN] = 'H2' | The element is replaced by a new one with this tag (all attributes and children stay) |
textAlignOverrides[tN] | text-align with !important; for block tags (p, h1–h6, div, blockquote, ul, ol, figcaption) additionally margin-left/margin-right (0 or auto), except for justify |
Format selector and “No translation”#
The format selector of the text toolbar wraps a selection in an inline tag:
| UI entry | Result |
|---|---|
| Code | <code> |
| Highlighted | <mark> |
| Small | <small> |
| Superscript | <sup> |
| Subscript | <sub> |
| Keyboard shortcut | <kbd> |
| Quote | <q> |
| Abbreviation | <abbr> |
| Strikethrough | <s> |
| No translation | <span class="notranslate"> (not a tag; see Translator) |
<p>Wir nutzen <span class="notranslate">VN-Designer</span> seit 2024.</p>Link colors#
A link in the text gets a color class directly on the <a> via the text toolbar. The list is also the allowlist.
| Entry | Class |
|---|---|
| Link color: default | (none) |
| Primary, Secondary, Success, Info, Warning, Danger, Light, Dark | text-primary, text-secondary, text-success, text-info, text-warning, text-danger, text-light, text-dark |
The classes are Bootstrap utility classes with !important and therefore win against theme link colors.
Icons in text#
The icon button of the text toolbar inserts an icon at the cursor that inherits the size and color of the text.
Syntax
<span class="bi bi-star vn-ic" style="font-size:1.5em;color:#c00" aria-hidden="true"></span>
<span class="vn-ic vn-ic-svg" data-vn-svg="assets/icons/herz.svg" data-vn-svg-mode="mask" aria-hidden="true"></span>| Part | Values | Meaning |
|---|---|---|
bi bi-NAME | Name from Bootstrap Icons ([a-z0-9-]{1,60}) | Icon font, drawn via ::before |
vn-ic | Class | Marker: clickable and changeable in the editor |
style="font-size:…em" | ^\d+(\.\d+)?em$ | Size relative to the text |
style="color:#rrggbb" | Hex | Color (empty = text color) |
vn-ic-svg + data-vn-svg | assets/icons/….svg or file:///….svg | Custom SVG from the project; other addresses are discarded (SVG_ICON_SRC_RE) |
data-vn-svg-mode | mask or image | mask: single color in the text color; image: with its own colors |
A <i class="bi bi-…"> or <span class="bi bi-…"> that is fixed in the template inside a text field automatically becomes a changeable icon in the editor (class vn-ic), but not in the menu item (there the ★ menu icon applies).
Tooltips on words#
The text toolbar puts a tooltip on a word. On export, vendor/vn-tooltip activates the Bootstrap tooltip (only if the page contains at least one).
Syntax
<span class="vn-tip" data-bs-toggle="tooltip" data-bs-placement="top" title="Erklärung"
data-vn-tip-bg="#000000" data-vn-tip-fg="#ffffff" data-vn-tip-trigger="hover focus">Wort</span>| Attribute | Values | Default | Meaning |
|---|---|---|---|
class | vn-tip (+ vn-tip-plain) | — | Marker; vn-tip-plain: without underline |
title | Text | — | Tooltip text (plain-text version) |
data-vn-tip-html | sanitized HTML | — | Tooltip with line break/formatting; title then carries the plain-text version |
data-bs-placement | top, bottom, left, right | top | Placement |
data-vn-tip-bg, data-vn-tip-fg | #rrggbb | Theme | Colors of surface and text |
data-vn-tip-trigger | hover focus or click | hover focus | Trigger; a click outside closes it |
The script sets tabindex="0" (keyboard), remembers the initialization in data-vn-tip-ready and falls back to the browser's title hint without Bootstrap 5.
Text effects and animation on a word#
The tools VN Text Effects and VN Animation write their effect as filtered styles and attributes onto a <span> (see Allowed styles). An author does not write them by hand; they only need to know that these properties survive saving and all others do not.
Size, width and position per block#
In the properties panel, every block has three sliders for all its text fields and buttons (elements with data-vn-text-id or data-vn-button-id). Menu items and brands (nav-link, dropdown-item, navbar-brand) are excluded; they have their own sliders.
Value in block.values | Range | Effect (same in editor and export) |
|---|---|---|
_textScalePct | 50–200 % | zoom on the element: proportional to its own theme size, hierarchy stays |
_textWidthPct | 20–100 % (100 = off) | max-width in %, with margin-left/right: auto |
_textOffsetYPx | −150–150 px (0 = off) | transform: translateY(…): shifts purely visually, the text flow stays |
For the free surface (block with freeSurface), width and position do not apply; there the elements decide for themselves.
Image and menu icon in a text element#
A direct child img, picture, svg or a menu icon (data-vn-nav-icon) in a text field is not part of the edited text. It is never taken into the override and is re-inserted on the same side (front or back) when the content is replaced. This is how, for example, the logo in the brand link of a menu survives text editing.
<a class="navbar-brand" href="#"><img src="{{logo}}" alt="Logo"><span>Marke</span></a>Protected PHP code in text#
A <script type="text/x-vn-php"> in the middle of the text stays unchanged during cleaning (attributes other than type are removed). In the browser it is inert; it cannot be typed. The export inserts the PHP code raw.
<p>Stand: <script type="text/x-vn-php"><?php echo date('d.m.Y'); ?></script></p>Images#
Image field: data-vn-image-key#
An <img> whose src is exactly one placeholder of an image field can be swapped with one click. The import sets data-vn-image-key="<fieldname>".
Syntax
<vn-parameters>
<input type="image" title="Bild" name="bild" value="../_images/land-d.jpg">
</vn-parameters>
<img src="{{bild}}" alt="Landschaft">Result (verified on import)
<img src="{{bild}}" alt="Landschaft" data-vn-image-key="bild">| Rule | Description |
|---|---|
| Detection | img[src] with src="{{field}}" (spaces allowed), where field is an image field |
| Background in style | style="background-image:url({{field}})" (also in vn-style) gets the same marker on the element |
| Background widget | If there is a fieldset type="background", the root element of the block is marked as the target; a click only counts if the free surface itself is hit (e.target is the root element) |
| Effect | A click opens the image selection and writes to block.values[field] |
Free image: data-vn-free-image-id#
All other <img src="…"> with a real address (decorative photos, logos, sample images) get data-vn-free-image-id="fiN". They too can be swapped with a click; the value is stored in imageOverrides.
Syntax
<img src="assets/images/team.jpg" alt="Team">Result (verified)
<img src="assets/images/team.jpg" alt="Team" data-vn-free-image-id="fi1">| Rule | Description |
|---|---|
| Not marked | img with {{placeholder}} without a matching image field, img without src |
| Format | fi + consecutive number starting at 1 |
| In the editor | Class vn-free-image, a click opens the image selection (stops the click from propagating) |
Background image in the inline style#
Elements with style="background-image:url(…)" (or in vn-style) and a real address are also free images (data-vn-free-image-id); the swap replaces the address in the attribute.
<div class="hero" style="background-image:url(assets/images/hero.jpg)"></div>Image selection and files#
A click on an image with an identifier opens “Change image”: upload a new file or (depending on the block) choose one of the project images. The file is copied into the project (assets/images/) and keeps its name (naming rule: same content = reuse the existing file, otherwise counter -2, -3). The export includes only files that are referenced and rewrites file:/// addresses as relative.
| Limit | Value |
|---|---|
| Allowed image formats | jpg, jpeg, png, gif, webp, svg (plus ico) |
| Size per file | at most 15 MB |
Alt text, title and link#
For every img with an image identifier (field image or free image), the image dialog offers alt text, title and link. The values are stored in imageAltOverrides and imageLinkOverrides.
Key in imageAltOverrides | Value | Effect |
|---|---|---|
<id> | Text | alt; empty text = deliberately empty (decorative image) |
t:<id> | Text | title (tooltip); empty removes the attribute |
s:<id> | "<width>%|<height>px" | Size (see Scaling) |
<id> is fiN for free images and k:<field> for field images.
Image link#
imageLinkOverrides[<id>] = { href, target, rel, download } puts an <a> around the image (or changes the existing one). In the editor, the link is marked (data-vn-img-link) and does not follow; link options such as rel, download and data-vn-cookie-settings apply as in Links.
<a href="https://example.com/team" target="_blank" rel="noopener"><img src="assets/images/team.jpg" alt="Team"></a>If the image is already inside an <a> of the template, the dialog changes its address. A logo in the brand link is such a case.
Scaling images with the mouse#
When the mouse hovers over an image with an identifier, three handles appear: right (width), bottom (height, the image is cropped instead of distorted), corner (both, aspect ratio stays; free with Shift). Double-clicking a handle resets it. Can be switched off in the page settings (“Scale images with the mouse”).
It is stored in imageAltOverrides["s:<id>"] as "<width in %>|<height in px>", for example "62%|240px", "62%|" (width only), "|240px" (height only).
| Part | Range | Effect |
|---|---|---|
| Width | 5–100 % | width in % of the surrounding width plus max-width:100%, both !important; keeps scaling along on phones |
| Height | 24–4000 px | height and object-fit: cover (!important) |
| width only | height:auto !important |
Dragging layers: data-vn-drag#
Scene blocks (several image layers on top of each other) mark a layer so that the user can move and scale it with the mouse on the work surface.
Syntax
<img class="haus" src="{{haus}}" alt=""
data-vn-drag="Haus" data-vn-drag-x="l2x" data-vn-drag-y="l2y" data-vn-drag-size="l2size">| Attribute | Value | Meaning |
|---|---|---|
data-vn-drag | Display name | Marks the element as draggable (name appears as a chip) |
data-vn-drag-x | Field name (range slider, %) | Horizontal center in % of the stage width |
data-vn-drag-y | Field name (%) | Distance from the floor in % of the stage height |
data-vn-drag-size | Field name (%) | Width in % of the stage width |
Operation: drag = move; corner handle = size; click selects, further clicks select the next layer below; arrow keys 1 % (with Shift 5 %); Esc deselects; double-click swaps the image. If the layer has the class vn-nox, only the height is changed. The three fields must be present in the vn-parameters block as number fields (type="range"); the program reads limits and step size from the field definition and writes only their values. You position the element itself via CSS from these fields.
On export, data-vn-drag, data-vn-drag-x, data-vn-drag-y and data-vn-drag-size are removed.
Icons#
Bootstrap icon: i.bi#
Every <i class="bi bi-NAME"> and <span class="bi bi-NAME"> in the template automatically becomes a changeable icon, unless it is inside a text field, a button, a menu item, or is itself a text icon (vn-ic).
Syntax
<i class="bi bi-check2-circle"></i>Result (verified)
<i class="" data-vn-icon-id="icon0" data-vn-icon-extra-classes=""></i>The classes bi and bi-NAME are removed from the template and set again on every render from the current icon value. All other classes stay (data-vn-icon-extra-classes).
data-vn-icon#
Explicitly marks an element as an icon, even if it is not a Bootstrap icon (for example an empty <span> or <i> for a custom SVG). The marker disappears after the import and is replaced by data-vn-icon-id="iconN".
Syntax
<a href="#" aria-label="Instagram"><i class="bi bi-instagram" data-vn-icon></i></a>
<i class="meinsymbol" data-vn-icon></i>| Attribute | Values | Meaning |
|---|---|---|
data-vn-icon | Switch (no value) | In the template: makes the element an icon |
data-vn-icon-id | icon + number | Set by the import, disappears on export |
data-vn-icon-extra-classes | Class list | The element's own classes (without bi, bi-*) |
Values of an icon#
The icon dialog (search across all Bootstrap icons) changes these values (iconOverrides[iconN]):
| Value | Type | Effect |
|---|---|---|
icon | Name (star) | Sets bi bi-star |
iconType | bootstrap or custom | custom: custom SVG (iconUrl) or flag |
iconUrl | Project path | Address of the SVG |
size | Number (rem) | font-size: <n>rem on the element |
color | #rrggbb | color with !important; for a custom SVG as a single-color mask |
mono | Switch | Custom SVG follows the text color (currentColor) |
href, newTab, rel, download | Link | The icon is wrapped in an <a> (new wrapper: color:inherit;text-decoration:none) |
If the icon already has a link wrapper from the template (an <a> that contains only the icon), that one is used. Without href in the override, links of the theme are left untouched.
Custom SVG icons and flags#
Custom SVG files and the flags (package in the icon dialog, about 270 countries, 4:3 or square, in vendor/flags) are copied into the project. Without a chosen color they appear as <img> with their own colors, with a color or “single-color” as a mask:
<span style="display:inline-block;width:1em;height:1em;vertical-align:-0.14em;background-color:currentColor;-webkit-mask:url('assets/icons/herz.svg') center/contain no-repeat;mask:url('assets/icons/herz.svg') center/contain no-repeat;"></span>The export rewrites the addresses as relative and includes the files.
Vertical alignment#
Custom icons (image, mask, embedded SVG) next to text should end flush with the middle of the capital letters, no matter how large they are. For this, the program sets vertical-align using the formula 0.36 − H/2 em (H = height in em; the middle of the capital letters lies 0.36 em above the baseline). In flex containers (buttons with align-items:center), vertical-align has no effect; there the container centers.
<img src="assets/icons/x.svg" alt="" style="height:1.2em;width:auto;vertical-align:-0.24em;">Preventing or excluding icons#
| Goal | How |
|---|---|
| Icon should not be changeable | Do not use <i class="bi …">/<span class="bi …">: use an inline SVG (<svg>), an <img> (then a free image) or a CSS mask in style.less |
Icon in text should not become vn-ic | Not possible in a text field; place the icon as a separate element outside the text field |
Buttons#
a.btn#
Every <a class="btn …"> is a button. The import sets data-vn-button-id="btnN" and reads the default values from the element (text, link, color, shape, icon). A click in the editor opens the button dialog instead of following the link.
Syntax
<a class="btn btn-primary" href="#kontakt">Kontakt</a>Result (verified)
<a class="btn btn-primary" href="#kontakt" data-vn-button-id="btn0" data-vn-btn-extra-classes="">Kontakt</a>| Attribute | Values | Meaning |
|---|---|---|
data-vn-button-id | btn + number from 0 | Identifier (key in buttonOverrides), removed on export |
data-vn-btn-extra-classes | Class list | All classes except btn, color and shape class; kept on every change, removed on export |
Values of a button#
buttonOverrides[btnN], defaults from the template (buttonDefaults):
| Value | Type | Default | Meaning |
|---|---|---|---|
text | Text | Text of the element | Label (written escaped) |
href | Address | href of the element; cookie link as #cookie-settings | Target |
target | Switch | target="_blank" | In a new window |
rel, download | see Link options | from element | Link extras |
color | primary, secondary, success, danger, warning, info, light, dark, custom | first color class, otherwise primary | Color |
customColor | #rrggbb | — | With custom: background, border; text color is chosen automatically as light or dark |
outline | Switch | btn-outline-… | Border only |
shape | default, rounded-pill, rounded-0, rounded-circle | from element | Shape |
icon, iconType, iconUrl, iconPosition, iconSize, iconColor, iconMono | see below | Icon in the button |
What is written is class = "btn <color> <shape> <extra>". With a custom color, the program sets background-color, border-color and color directly on the element (inline style without !important, the color class is dropped; see Custom color). Text and href are taken from the template as raw text: placeholders {{…}} are not evaluated there (Placeholders in buttons).
Icon in a button#
An <i class="bi bi-…"> or <img> inside the button counts as the button icon and is read from the template (front or back depending on its position in the text).
<a class="btn btn-outline-dark" href="#"><i class="bi bi-download"></i> Herunterladen</a>| Value | Meaning |
|---|---|
icon | Name of the Bootstrap icon |
iconType | bootstrap or custom |
iconUrl | Address of the custom SVG/image |
iconPosition | before or after |
iconSize | 0.3–6 (em; 1 = default) |
iconColor | #rrggbb; for a custom SVG as a mask |
iconMono | custom SVG in text color |
Containers vn-buttons and vn-theme-style#
vn-buttons is a marker on the container of several buttons. It has no editing effect of its own. Its only function: if the container carries vn-theme-style="display-7", the class is written to every .btn in the container (theme font size/style for all buttons of a group).
Syntax
<div vn-buttons vn-theme-style="display-7">
<a class="btn btn-primary" href="#">Eins</a>
<a class="btn btn-secondary" href="#">Zwei</a>
</div>| Attribute | Value | Meaning |
|---|---|---|
vn-buttons | Switch | Marker: container of a button group |
vn-theme-style | Classes (display-7) | Becomes the classes of the contained .btn elements (stored in the extra-classes value) |
Placeholders in buttons#
In <a class="btn"> a placeholder {{…}} stays literally in place, in the text and in the href, in the editor and in the export. The reason: tagButtons reads text and address as default values from the raw template before the placeholders are replaced, and rebuilds the button on every render from these values and the user's changes (applyButtonValue).
<a class="btn btn-primary" href="{{ziel}}">{{beschriftung}}</a> Write the text and the target directly into the template; the user changes them in the button dialog. If you want to feed both from the properties panel, use an ordinary link without the class btn (<a class="mein-knopf" href="{{ziel}}">{{text}}</a>) and style it yourself. See also Placeholders in buttons.
Custom color#
Besides the eight Bootstrap colors, the button dialog offers a custom color (color: 'custom', customColor: '#rrggbb'). Then:
- The color class (
btn-primary,btn-outline-primary…) is dropped; shape and extra classes stay. - The program sets
background-color,border-colorandcoloras an inline style on the element, without!important. With "outline only" (outline) the background istransparentand border and text use the chosen color; otherwise the program picks the text color by brightness (#212529or#fff). - If the user switches back to a Bootstrap color, the program removes the inline style again.
Colors and links in block CSS#
Buttons and links follow the same precedence as all block CSS (Precedence):
- A block rule without
!importantwins against Bootstrap in the editor and in the export (in the editor the block CSS sits in a later layer, in the export the higher specificity from the instance class wins). - A block rule with
!importantwins against Bootstrap rules without!important. Against an!importantrule from Bootstrap or the theme CSS it wins in the export but loses in the editor (layer reversal for!important). The result then differs between editor and finished page. !importanthelps against theme CSS with higher specificity and against the font and typography rules of the site settings (Site settings); this is why the supplied blocks set colors, borders and font of buttons and links with!important.
Menus#
A block is a menu block if its template contains navbar-nav or nav-link. Such blocks get additional sliders in the panel (menu font, dropdown colors, hamburger color).
Menu items and brand#
a.nav-link, a.dropdown-item and a.navbar-brand are text fields with special handling: a click selects the whole text (short labels), color, font and link via the text toolbar, a click does not follow the link.
Syntax (Bootstrap convention)
<nav class="navbar navbar-expand-lg">
<a class="navbar-brand" href="#"><img src="{{logo}}" alt="Logo"><span>Marke</span></a>
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#{{vn-id}}-nav"
aria-controls="{{vn-id}}-nav" aria-expanded="false" aria-label="Menü öffnen">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="{{vn-id}}-nav">
<ul class="navbar-nav ms-auto">
<li class="nav-item"><a class="nav-link" href="#leistungen">Leistungen</a></li>
<li class="nav-item"><a class="nav-link" href="#kontakt">Kontakt</a></li>
</ul>
</div>
</nav>(from themes/vn-studio-src/components/menu1)
| Action in the editor | Effect on the template |
|---|---|
| Add item | The menu item container (li, otherwise .dropdown) is cloned, text “Menu item” |
| Move item | Before/after the sibling element in the same menu |
| Delete item | Remove container including submenu |
| ▾ Menu | Converts an item into a dropdown or appends another entry |
Dropdown#
The program creates a Bootstrap 5 dropdown. A block can also bring the same structure itself.
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" role="button" aria-expanded="false">Leistungen</a>
<ul class="dropdown-menu" style="max-height:calc(100vh - 6rem);overflow-y:auto">
<li><a class="dropdown-item" href="#">Bad</a></li>
<li><a class="dropdown-item" href="#">Heizung</a></li>
</ul>
</li>If there is no li container (menus without a list structure), the program wraps the item in a <div class="dropdown">. In the editor, it additionally sets data-bs-auto-close="outside" on every [data-bs-toggle="dropdown"], so that a click on an entry does not close the menu before it can be edited. That attribute never makes it into the template.
Submenu: vn-submenu#
If the cursor is in an entry of a dropdown, the same button (“▾ Entry”) creates a submenu that opens sideways.
Syntax
<li class="vn-submenu">
<a class="dropdown-item vn-submenu-toggle" href="#" aria-expanded="false">Eintrag</a>
<ul class="dropdown-menu vn-submenu-list">
<li><a class="dropdown-item" href="#">Unterpunkt</a></li>
</ul>
</li>| Part | Meaning |
|---|---|
li.vn-submenu | Marker of the element with a submenu (triggers the export of vendor/vn-submenu) |
a.vn-submenu-toggle | Expand entry; an arrow › is drawn in front of it via CSS |
ul.dropdown-menu.vn-submenu-list | The sub-level |
Behavior (vendor/vn-submenu/vn-submenu.js): on a computer it opens on hover or keyboard focus to the right of the entry, or to the left if space is short; if it is taller than the window, it gets a scrollbar; on phones and in the collapsed hamburger menu it appears indented directly below the entry and opens by tapping (arrow ▾). The script needs no Bootstrap JS and also works in the work surface.
Hamburger icon#
The hamburger icon is .navbar-toggler-icon. The user sets its color in the panel (block.values._togglerColor). For this, the program generates a recolored SVG and neutralizes both common ways of drawing it (embedded SVG in the background-image or three CSS bars with ::before/::after):
.vn-imp-menu-b1 .navbar-toggler-icon { background-image: url("data:image/svg+xml,…") !important; width: 1.5em !important; height: 1.5em !important; }
.vn-imp-menu-b1 .navbar-toggler-icon::before, .vn-imp-menu-b1 .navbar-toggler-icon::after { content: none !important; background: none !important; }(.vn-imp-menu-b1 stands here for the instance class of the block.)
A block's own hamburger icon should therefore use the element .navbar-toggler-icon if the color selection is to work.
Sliders of a menu block#
All values are stored in block.values, are appended in renderer.js as CSS with !important, and apply equally in editor and export.
| Value | Range | Selectors |
|---|---|---|
_menuFontPx | 8–64 px (slider 10–40) | .navbar-nav, .navbar-nav .nav-link, .navbar-nav .dropdown-item |
_brandFontPx | 8–96 px (slider 10–60) | .navbar-brand, .navbar-caption-wrap, .navbar-caption |
_ddBg | #rrggbb | .dropdown-menu background |
_ddText | #rrggbb | .dropdown-menu .dropdown-item color |
_ddHoverBg, _ddHoverText | #rrggbb | :hover, :focus, :active of the entries; switches off the general darkening (filter:none) |
_togglerColor | #rrggbb | see Hamburger icon |
Icon before the menu item#
The icon button of the text toolbar puts an icon before or after a menu item (navIconOverrides[tN]: icon, iconType, iconUrl, size in rem, color, mono, pos = after or front). The program inserts an <i data-vn-nav-icon> as the first or last child of the a (spacing 0.4em). The marker data-vn-nav-icon is not part of the text and is protected when editing and saving the link text (see Image and menu icon in a text element).
The marker vn-menu#
Like vn-buttons, vn-menu is a marker on the container, here of the menu items (.nav-link, .dropdown-item). It has no editing effect; only vn-theme-style on this container is written to every menu item.
<ul vn-menu vn-theme-style="display-4" class="navbar-nav">
<li class="nav-item"><a class="nav-link" href="#">Start</a></li>
</ul>Links#
Link dialog and options#
All link dialogs (text toolbar and menu, image, button, icon) share the same additional choices from src/link-options.js. What is always stored is { href, newTab/target, rel, download }; the program writes the attributes on the <a> from it.
| Choice | Result on the <a> |
|---|---|
| Address | href |
| New window | target="_blank" and rel contains noopener |
| Link type (search engines) | rel="nofollow", rel="sponsored" or rel="ugc" |
| Download the file instead of opening it | download (not for tel:, mailto:, #… and cookie link) |
| Open cookie settings | href="#" and data-vn-cookie-settings |
In rel, the program manages only its own values (nofollow, sponsored, ugc, noopener); foreign rel values of the template are kept. A link override without a rel value (older projects) leaves the element unchanged.
Phone, WhatsApp and email#
If the user types a phone number or email address into the address field, it automatically becomes tel: or mailto: when leaving the field (normalizeLinkInput).
| Input | Result |
|---|---|
info@example.com | mailto:info@example.com |
+49 30 123456 or 030 123456 | tel:+4930123456; leading 00 becomes +; (0) is dropped |
| “Phone call (tel:)” / “WhatsApp message” | Toggle for numbers; WhatsApp yields https://wa.me/<digits> (+ ?text=… with preset text) and opens in a new window |
| Subject / message text | mailto:…?subject=…&body=… (URL-encoded) |
A national number with a leading 0 is treated as German (49) for WhatsApp. Existing schemes (https:, #, /) are not changed; dates such as 12.10.2026 are not recognized as phone numbers.
Link to a file#
“Or choose a file” copies the file to assets/dateien/ in the project and enters the path; the export includes it. For a PDF, “New tab” is ticked automatically.
| Rule | Value |
|---|---|
| Target | assets/dateien/<name>; umlauts are rewritten, only [A-Za-z0-9._-], at most 80 characters in the name |
| Same name | Same content (SHA-256) is reused, otherwise counter -2, -3 … |
| Size | at most 500 MB |
| Rejected | .php, .php3–.php7, .phtml, .phar, .cgi, .pl, .py, .sh, .asp, .aspx, .jsp, .htaccess, .htpasswd, .ini |
Anchor on this page#
“Or choose an anchor on this page” lists the anchor IDs of the blocks and enters #<anchor> (the anchor ID of a block is set in the panel, otherwise blk-<id>). Popup blocks appear as “Popup: …”.
Open cookie settings#
A link with data-vn-cookie-settings opens the VN Cookie Consent window on export. In the link dialog it is the button “Open cookie settings”; a second click withdraws the choice.
Syntax
<a href="#" data-vn-cookie-settings>Cookie-Einstellungen</a>| Attribute | Meaning |
|---|---|
data-vn-cookie-settings | Marker on the <a> (or any other element; vendor/vn-cookie-consent reacts to a click on any element with this attribute, preventDefault) |
| Placeholder address in the dialog | #cookie-settings (internal only, the link contains href="#") |
The attribute is on the allowlist of the text sanitizer (not on tags other than a). A prerequisite is the cookie banner being switched on in the project settings; see Cookie consent.
CMS: texts and images on the finished page#
Every block can be set up so that its operator changes texts, button labels, links and images later directly on the finished page (flat-file CMS without a database). The block author writes nothing special: all text fields, buttons and <img> images of the block are captured.
Enabling#
| Place | Meaning |
|---|---|
| Panel, section CMS, switch | block.cms = { enabled: true }; in the canvas the block carries the “CMS” mark |
| Password | One password per project; it lives in the program profile, not in the project, and arrives as a PBKDF2-SHA256 hash (100,000 rounds, 16-byte salt) in vendor/vn-cms/config.php |
| Page name | The page must be named .php (index.php), otherwise the PHP read-out code is missing |
| Without a password | Nobody can edit (config.php is empty); the export points this out |
| Template | The block “CMS block (text + image)” in the “Custom code” tab |
Markers in the finished HTML#
The export sets these attributes (before baking in the overrides, while the identifiers are still there). They should not be written by hand; they are listed here because extensions and the runtime rely on them.
| Attribute | Value | Effect |
|---|---|---|
data-vn-cms-block | <block> | On the root element of the block: editing surface |
data-vn-cms | <block>:<key> | Text field or button label is changeable |
data-vn-cms-img | <block>:<key> | <img>: click = swap, alt text, link |
data-vn-cms-link | <block>:<key> | <a>: address and “new window” changeable |
Nested text fields: only the outer one is captured. Buttons (a.btn) get data-vn-cms and data-vn-cms-link; text fields that are themselves a link also get data-vn-cms-link. Images lose srcset and sizes (the old image would otherwise win against the swapped one).
Key format#
A key has the form <block>:<key> with the rule ^([A-Za-z0-9_-]+):([A-Za-z0-9_.:-]+)$.
| Part | Example | Origin |
|---|---|---|
| Block | m3k9x2 | Block ID (only [A-Za-z0-9_-]), also the file name |
| Text | t0, t4 | data-vn-text-id |
| Button | btn0 | data-vn-button-id |
| Free image | fi1 | data-vn-free-image-id |
| Field image | k:bild | data-vn-image-key with prefix k: |
A complete attribute: data-vn-cms="m3k9x2:t0", data-vn-cms-img="m3k9x2:k:bild". Keys may be at most 60 characters long ([A-Za-z0-9_.:-]).
What happens to the page on export#
markCmsEditablesassigns the attributes.- After baking in,
finalizeCmsMarkupwraps the text content in placeholder comments (VNCMS-T). cmsToPhpturns these into PHP calls fromvendor/vn-cms/cms.php:vn_cms_t,vn_cms_img,vn_cms_alt,vn_cms_href,vn_cms_target,vn_cms_wrap_open,vn_cms_wrap_close. At the very top of the page goes<?php require_once __DIR__ . '/vendor/vn-cms/cms.php'; ?>.- On the page:
vendor/vn-cms/vn-cms.cssandvn-cms.js(only if the page contains a CMS block).
Result (excerpt)
<h2 data-vn-cms="m3k9x2:t0"><?php vn_cms_t('m3k9x2', 't0', <<<'VNCMS_D'
Aktuelles aus unserem Haus
VNCMS_D
); ?></h2>
<img data-vn-cms-img="m3k9x2:k:bild" src="<?php vn_cms_img('m3k9x2', 'k:bild', 'assets/images/team.jpg'); ?>" alt="<?php vn_cms_alt('m3k9x2', 'k:bild', ''); ?>">The stored content lives in vn-cms-data/<block>.json (t texts, i images, a alt texts, l links), the last version is kept as .prev.json, uploaded images go to uploads/cms/. These files are not overwritten when publishing.
Operation and security on the page#
| Topic | Behavior |
|---|---|
| Logging in | Double-click on the block or an address with #cms-login; password; afterwards a dashed outline around all fields |
| Saving | only when logged in, with a login token (CSRF) and same origin (Origin/Host) |
| Failed attempts | after 5 failed attempts a 10-minute pause (per visitor address) |
| Images | only JPG, PNG, GIF, WebP, at most 10 MB, type checked via getimagesize, random file name |
| Content | at most 1.5 MB per save operation |
| Allowed tags in text | b strong i em u s br span a p small mark sub sup h1–h6 ul ol li div blockquote code kbd abbr q |
| Removed | script style iframe object embed link meta form input button textarea select svg math noscript template base; event attributes |
| Attributes | a: href (no javascript:, data:, vbscript:, file:), target (_blank/_self), rel, title; all: class (simple names), lang, translate (language codes) |
| Links | only relative addresses, #anchor, http(s), mailto, tel |
Popup#
Every block can become a popup in the panel (section Popup, switch “Show as popup”). The block author does not have to change anything in the template.
How the popup is created#
The export wraps the block in a container (popupWrapperHtml), hidden until opened. The anchor ID of the block moves from the root element to the container.
Result (from popup.js)
<div class="vn-popup" id="blk-ab12" data-pos="center" data-size="md" data-anim="fade"
data-vn-popup='{"auto":"none","delay":5,"scroll":50,"freq":"session","anim":"fade","backdropClose":true,"escClose":true}'
style="--vnp-overlay:rgba(0, 0, 0, 0.60);--vnp-width:640px;--vnp-bg:#ffffff;--vnp-radius:12px" hidden aria-hidden="true">
<div class="vn-popup-backdrop"></div>
<div class="vn-popup-dialog" role="dialog" aria-modal="true" tabindex="-1">
<button type="button" class="vn-popup-close" aria-label="Schließen">×</button>
<div class="vn-popup-body"></div>
</div>
</div>Runtime: vendor/vn-popup/vn-popup.css and vn-popup.js (only if the page contains a popup).
Settings#
block.popup (all values are validated on load, errors fall back to the default):
| Key | Values | Default | Meaning |
|---|---|---|---|
enabled | Switch | off | Popup on |
auto | none, delay, scroll, exit | none | Open automatically (opening via link always works) |
delay | 0–600 | 5 | Seconds (with delay) |
scroll | 1–100 | 50 | Percent of the page (with scroll) |
freq | always, session, day, week, once | session | How often to open on its own (remembered in sessionStorage/localStorage, key vnpopup:<id>) |
size | sm, md, lg, full | md | Width 420 px, 640 px, 960 px, 100 % |
pos | center, top, bottom | center | Placement |
anim | none, fade, zoom, slide, left, right, flip, bounce | fade | Fade-in |
overlayColor, overlayOpacity | #rrggbb, 0–100 | #000000, 60 | Darkening |
backdropClose | Switch | on | A click outside closes |
escClose | Switch | on | Escape closes (off: only via own buttons, for example an age check) |
showClose | Switch | on | Close button at the top right |
bg | #rrggbb | #ffffff | Window background |
radius | 0–60 | 12 | Corner radius in px |
Opening via link: href="#anchor"#
Every link or button whose href points to the anchor ID of the popup block (#blk-ab12 or page.php#blk-ab12) opens the popup. In the link dialog: “Anchor on this page” → “Popup: …”. The address with #blk-ab12 also opens the popup on load.
<a class="btn btn-primary" href="#angebot">Angebot ansehen</a>Closing from the content: data-vn-popup-close#
Every element in the popup with data-vn-popup-close closes it on click (preventDefault), for example a “No thanks” button.
<a class="btn btn-secondary" href="#" data-vn-popup-close>Nein danke</a>JavaScript interface: VNPopup#
| Call | Return | Effect |
|---|---|---|
VNPopup.open(id) | true/false | Opens the popup with this container ID |
VNPopup.close(id) | — | Closes |
VNPopup.isOpen() | ID of the open popup or null | State |
Further runtime behavior rules: scrolling is locked; focus stays in the window (tab trap) and returns to the triggering element; videos and audio in the popup are paused on closing and YouTube/Vimeo frames are emptied (address in data-vn-src), and reloaded on opening. With “reduced motion” in the system or anim: none, it closes without animation.
The “Popup” template#
The “Custom code” tab offers a ready-made popup block (createPopupBlockEntry) that is already switched on.
<section class="vn-popup-content">
<vn-parameters>
<header>Farben</header>
<input type="color" title="Hintergrund" name="bgColor" value="#ffffff">
</vn-parameters>
<div class="vn-popup-inner">
<h2 class="vn-popup-title">Schön, dass du da bist!</h2>
<p class="vn-popup-text">Hier steht dein Text.</p>
<a class="btn btn-primary" href="#" data-vn-popup-close>Mehr erfahren</a>
</div>
</section>