VN-Designer Developer Documentation
06

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:

  1. 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).
  2. Editing: The user's changes do not end up in the template but in overrides on the block. The template stays unchanged.
  3. Rendering (editor): After every render, the program lays the overrides over the freshly rendered HTML again and makes the elements clickable.
  4. Export: The same overrides are baked in permanently; all editor traces (identifiers, contenteditable, helper classes) are removed.
Override on the blockKeyContent
textOverridest0, t1 …changed content (innerHTML) of a text field
textTagOverridest0 …chosen tag (H1, H2, H3, P …)
textLinkOverridest0 …{ href, newTab, colorClass, rel, download } for text fields that are themselves an <a>
textAlignOverridest0 …left, center, right, justify
buttonOverridesbtn0 …text, link, color, shape, icon of a button
iconOverridesicon0 …icon, size, color, link
navIconOverridest0 … (menu item)icon before/after a menu item
imageOverridesfi1 …address of a free image
imageLinkOverridesfi1 or k:<field>{ href, target, rel, download } around an image
imageAltOverridesfi1, k:<field>; t:<id>; s:<id>alt text; title (t:); size (s:)
animOverridest0, 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:

  1. 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).
  2. List fields ul/ol with data-multiline or vn-article (see List fields).
  3. Leaf elements: every other element that contains only text and inline tags, for example <div>Text</div>, <span>, <td>, <label>, <small>, <em>, <dt>.

Syntax

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

html
<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.

ElementText field?Remark
h1–h6, p, li, blockquote, figcaptionyesOutside navigation, form, button, link
div, span, td, th, label, small, em, dt …yes, if leafOnly text and inline tags inside
Container with paragraph/heading children (div.wrap > p)noOnly the children become fields
a.nav-link, a.navbar-brand, a.dropdown-itemyesSeparate branch, also inside nav
a (loose links, not .btn) with textyesThe <a> itself is the field, link via the text toolbar
Text consisting only of {{placeholder}}noBelongs to the properties panel
script, style, textarea, option, select, button, iframe, svg, noscript, template, pre, code, input, header (panel header), fieldsetneverNEVER_TEXT_TAGS
Everything inside nav, button, select, form, a, vn-parametersnoSKIP_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

html
<h2 data-vn-text-id="t0">Titel</h2>
PropertyValueMeaning
Formatt + number (t0, t1 …)Consecutive, starting from the highest existing index
LifetimeEditor and templateRemoved 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

html
<ul data-multiline>
  <li>Erster Punkt</li>
  <li>Zweiter Punkt</li>
</ul>
<ol vn-article>
  <li>Schritt eins</li>
</ol>
AttributeValueDefaultMeaning
data-multilineSwitch (no value)offOn ul, ol (expandable list) or on div: the field may contain lists, paragraphs, quotes and headings
vn-articleSwitchoffLike 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.

html
<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:

GroupTags
Inline allowedstrong, 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
RemovedComments
Unchanged<script type="text/x-vn-php"> (protected PHP code)

Verified example (input as a saved override, result after baking in):

html

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:

TagAllowed attributes
ahref, target, rel, download, title, aria-label, data-vn-cookie-settings
qcite
timedatetime
datavalue
abbr, dfntitle
del, insdatetime, cite
bdodir
spanstyle (filtered, see below), data-vn-text-color, data-vn-anim, data-vn-anim-t, data-vn-svg, data-vn-svg-mode, tooltip attributes
allclass (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:

SourceProperties
Text toolbarcolor, font-family, font-size, font-weight, font-style
VN Text Effectstext-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 Animationthe variables --vn-a, --vn-d, --vn-dl, --vn-e, --vn-n and display:inline-block
Custom SVG iconStyle 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>.
  • stripForeignFrameworkMarkup cleans 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.

OverrideEffect 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 entryResult
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)
html
<p>Wir nutzen <span class="notranslate">VN-Designer</span> seit 2024.</p>

A link in the text gets a color class directly on the <a> via the text toolbar. The list is also the allowlist.

EntryClass
Link color: default(none)
Primary, Secondary, Success, Info, Warning, Danger, Light, Darktext-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

html
<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>
PartValuesMeaning
bi bi-NAMEName from Bootstrap Icons ([a-z0-9-]{1,60})Icon font, drawn via ::before
vn-icClassMarker: clickable and changeable in the editor
style="font-size:…em"^\d+(\.\d+)?em$Size relative to the text
style="color:#rrggbb"HexColor (empty = text color)
vn-ic-svg + data-vn-svgassets/icons/….svg or file:///….svgCustom SVG from the project; other addresses are discarded (SVG_ICON_SRC_RE)
data-vn-svg-modemask or imagemask: 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

html
<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>
AttributeValuesDefaultMeaning
classvn-tip (+ vn-tip-plain)—Marker; vn-tip-plain: without underline
titleText—Tooltip text (plain-text version)
data-vn-tip-htmlsanitized HTML—Tooltip with line break/formatting; title then carries the plain-text version
data-bs-placementtop, bottom, left, righttopPlacement
data-vn-tip-bg, data-vn-tip-fg#rrggbbThemeColors of surface and text
data-vn-tip-triggerhover focus or clickhover focusTrigger; 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.valuesRangeEffect (same in editor and export)
_textScalePct50–200 %zoom on the element: proportional to its own theme size, hierarchy stays
_textWidthPct20–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.

html
<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.

html
<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

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

html
<img src="{{bild}}" alt="Landschaft" data-vn-image-key="bild">
RuleDescription
Detectionimg[src] with src="{{field}}" (spaces allowed), where field is an image field
Background in stylestyle="background-image:url({{field}})" (also in vn-style) gets the same marker on the element
Background widgetIf 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)
EffectA 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

html
<img src="assets/images/team.jpg" alt="Team">

Result (verified)

html
<img src="assets/images/team.jpg" alt="Team" data-vn-free-image-id="fi1">
RuleDescription
Not markedimg with {{placeholder}} without a matching image field, img without src
Formatfi + consecutive number starting at 1
In the editorClass 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.

html
<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.

LimitValue
Allowed image formatsjpg, jpeg, png, gif, webp, svg (plus ico)
Size per fileat 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 imageAltOverridesValueEffect
<id>Textalt; empty text = deliberately empty (decorative image)
t:<id>Texttitle (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.

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.

html
<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).

PartRangeEffect
Width5–100 %width in % of the surrounding width plus max-width:100%, both !important; keeps scaling along on phones
Height24–4000 pxheight and object-fit: cover (!important)
width onlyheight: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

html
<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">
AttributeValueMeaning
data-vn-dragDisplay nameMarks the element as draggable (name appears as a chip)
data-vn-drag-xField name (range slider, %)Horizontal center in % of the stage width
data-vn-drag-yField name (%)Distance from the floor in % of the stage height
data-vn-drag-sizeField 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

html
<i class="bi bi-check2-circle"></i>

Result (verified)

html
<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

html
<a href="#" aria-label="Instagram"><i class="bi bi-instagram" data-vn-icon></i></a>
<i class="meinsymbol" data-vn-icon></i>
AttributeValuesMeaning
data-vn-iconSwitch (no value)In the template: makes the element an icon
data-vn-icon-idicon + numberSet by the import, disappears on export
data-vn-icon-extra-classesClass listThe element's own classes (without bi, bi-*)

Values of an icon#

The icon dialog (search across all Bootstrap icons) changes these values (iconOverrides[iconN]):

ValueTypeEffect
iconName (star)Sets bi bi-star
iconTypebootstrap or customcustom: custom SVG (iconUrl) or flag
iconUrlProject pathAddress of the SVG
sizeNumber (rem)font-size: <n>rem on the element
color#rrggbbcolor with !important; for a custom SVG as a single-color mask
monoSwitchCustom SVG follows the text color (currentColor)
href, newTab, rel, downloadLinkThe 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:

html
<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.

html
<img src="assets/icons/x.svg" alt="" style="height:1.2em;width:auto;vertical-align:-0.24em;">

Preventing or excluding icons#

GoalHow
Icon should not be changeableDo 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-icNot 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

html
<a class="btn btn-primary" href="#kontakt">Kontakt</a>

Result (verified)

html
<a class="btn btn-primary" href="#kontakt" data-vn-button-id="btn0" data-vn-btn-extra-classes="">Kontakt</a>
AttributeValuesMeaning
data-vn-button-idbtn + number from 0Identifier (key in buttonOverrides), removed on export
data-vn-btn-extra-classesClass listAll 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):

ValueTypeDefaultMeaning
textTextText of the elementLabel (written escaped)
hrefAddresshref of the element; cookie link as #cookie-settingsTarget
targetSwitchtarget="_blank"In a new window
rel, downloadsee Link optionsfrom elementLink extras
colorprimary, secondary, success, danger, warning, info, light, dark, customfirst color class, otherwise primaryColor
customColor#rrggbb—With custom: background, border; text color is chosen automatically as light or dark
outlineSwitchbtn-outline-…Border only
shapedefault, rounded-pill, rounded-0, rounded-circlefrom elementShape
icon, iconType, iconUrl, iconPosition, iconSize, iconColor, iconMonosee belowIcon 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).

html
<a class="btn btn-outline-dark" href="#"><i class="bi bi-download"></i> Herunterladen</a>
ValueMeaning
iconName of the Bootstrap icon
iconTypebootstrap or custom
iconUrlAddress of the custom SVG/image
iconPositionbefore or after
iconSize0.3–6 (em; 1 = default)
iconColor#rrggbb; for a custom SVG as a mask
iconMonocustom 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

html
<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>
AttributeValueMeaning
vn-buttonsSwitchMarker: container of a button group
vn-theme-styleClasses (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).

html
<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-color and color as an inline style on the element, without !important. With "outline only" (outline) the background is transparent and border and text use the chosen color; otherwise the program picks the text color by brightness (#212529 or #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 !important wins 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 !important wins against Bootstrap rules without !important. Against an !important rule 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.
  • !important helps 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.

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

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)

html
<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 editorEffect on the template
Add itemThe menu item container (li, otherwise .dropdown) is cloned, text “Menu item”
Move itemBefore/after the sibling element in the same menu
Delete itemRemove container including submenu
▾ MenuConverts an item into a dropdown or appends another entry

The program creates a Bootstrap 5 dropdown. A block can also bring the same structure itself.

html
<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.

If the cursor is in an entry of a dropdown, the same button (“▾ Entry”) creates a submenu that opens sideways.

Syntax

html
<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>
PartMeaning
li.vn-submenuMarker of the element with a submenu (triggers the export of vendor/vn-submenu)
a.vn-submenu-toggleExpand entry; an arrow › is drawn in front of it via CSS
ul.dropdown-menu.vn-submenu-listThe 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.

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

css
.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.

All values are stored in block.values, are appended in renderer.js as CSS with !important, and apply equally in editor and export.

ValueRangeSelectors
_menuFontPx8–64 px (slider 10–40).navbar-nav, .navbar-nav .nav-link, .navbar-nav .dropdown-item
_brandFontPx8–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#rrggbbsee Hamburger icon

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

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.

html
<ul vn-menu vn-theme-style="display-4" class="navbar-nav">
  <li class="nav-item"><a class="nav-link" href="#">Start</a></li>
</ul>

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.

ChoiceResult on the <a>
Addresshref
New windowtarget="_blank" and rel contains noopener
Link type (search engines)rel="nofollow", rel="sponsored" or rel="ugc"
Download the file instead of opening itdownload (not for tel:, mailto:, #… and cookie link)
Open cookie settingshref="#" 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.

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

InputResult
info@example.commailto:info@example.com
+49 30 123456 or 030 123456tel:+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 textmailto:…?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.

“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.

RuleValue
Targetassets/dateien/<name>; umlauts are rewritten, only [A-Za-z0-9._-], at most 80 characters in the name
Same nameSame content (SHA-256) is reused, otherwise counter -2, -3 …
Sizeat most 500 MB
Rejected.php, .php3–.php7, .phtml, .phar, .cgi, .pl, .py, .sh, .asp, .aspx, .jsp, .htaccess, .htpasswd, .ini

“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: …”.

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

html
<a href="#" data-vn-cookie-settings>Cookie-Einstellungen</a>
AttributeMeaning
data-vn-cookie-settingsMarker 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#

PlaceMeaning
Panel, section CMS, switchblock.cms = { enabled: true }; in the canvas the block carries the “CMS” mark
PasswordOne 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 nameThe page must be named .php (index.php), otherwise the PHP read-out code is missing
Without a passwordNobody can edit (config.php is empty); the export points this out
TemplateThe 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.

AttributeValueEffect
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_.:-]+)$.

PartExampleOrigin
Blockm3k9x2Block ID (only [A-Za-z0-9_-]), also the file name
Textt0, t4data-vn-text-id
Buttonbtn0data-vn-button-id
Free imagefi1data-vn-free-image-id
Field imagek:bilddata-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#

  1. markCmsEditables assigns the attributes.
  2. After baking in, finalizeCmsMarkup wraps the text content in placeholder comments (VNCMS-T).
  3. cmsToPhp turns these into PHP calls from vendor/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'; ?>.
  4. On the page: vendor/vn-cms/vn-cms.css and vn-cms.js (only if the page contains a CMS block).

Result (excerpt)

html
<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#

TopicBehavior
Logging inDouble-click on the block or an address with #cms-login; password; afterwards a dashed outline around all fields
Savingonly when logged in, with a login token (CSRF) and same origin (Origin/Host)
Failed attemptsafter 5 failed attempts a 10-minute pause (per visitor address)
Imagesonly JPG, PNG, GIF, WebP, at most 10 MB, type checked via getimagesize, random file name
Contentat most 1.5 MB per save operation
Allowed tags in textb strong i em u s br span a p small mark sub sup h1–h6 ul ol li div blockquote code kbd abbr q
Removedscript style iframe object embed link meta form input button textarea select svg math noscript template base; event attributes
Attributesa: href (no javascript:, data:, vbscript:, file:), target (_blank/_self), rel, title; all: class (simple names), lang, translate (language codes)
Linksonly relative addresses, #anchor, http(s), mailto, tel

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.

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)

html
<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">&times;</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).

block.popup (all values are validated on load, errors fall back to the default):

KeyValuesDefaultMeaning
enabledSwitchoffPopup on
autonone, delay, scroll, exitnoneOpen automatically (opening via link always works)
delay0–6005Seconds (with delay)
scroll1–10050Percent of the page (with scroll)
freqalways, session, day, week, oncesessionHow often to open on its own (remembered in sessionStorage/localStorage, key vnpopup:<id>)
sizesm, md, lg, fullmdWidth 420 px, 640 px, 960 px, 100 %
poscenter, top, bottomcenterPlacement
animnone, fade, zoom, slide, left, right, flip, bouncefadeFade-in
overlayColor, overlayOpacity#rrggbb, 0–100#000000, 60Darkening
backdropCloseSwitchonA click outside closes
escCloseSwitchonEscape closes (off: only via own buttons, for example an age check)
showCloseSwitchonClose button at the top right
bg#rrggbb#ffffffWindow background
radius0–6012Corner radius in px

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.

html
<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.

html
<a class="btn btn-secondary" href="#" data-vn-popup-close>Nein danke</a>
CallReturnEffect
VNPopup.open(id)true/falseOpens the popup with this container ID
VNPopup.close(id)—Closes
VNPopup.isOpen()ID of the open popup or nullState

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 “Custom code” tab offers a ready-made popup block (createPopupBlockEntry) that is already switched on.

html
<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>