Quick reference
Compact lookup tables: input types and attributes, directives and markers, placeholders and variables, root attributes, package files, manifest.json, all ctx functions and the libraries under vendor/, each with a link to the detail entry.
Input types#
All types go inside the <vn-parameters> block (chapter Input types). Anything not in the table becomes a single-line text field.
Tag and type | Field in the panel | Value in the template | Value in the LESS | Entry |
|---|---|---|---|---|
input type="text" (also any unknown type) | text field | text | text in quotation marks | text, Other types |
textarea | multi-line text field | text with line breaks | text in quotation marks | textarea |
input type="checkbox" | switch | true or false | true or false | checkbox |
input type="color" | color picker | text #rrggbb | color | color |
input type="range" | slider with number field | text ("4") | number | range |
select with option | selection list | text (value of the option) | text in quotation marks | select and option |
input type="image" | image field | text (image address) | text in quotation marks | image |
fieldset with image, color, video | background widget | object { type, value, parallax } | @bg-type, @bg-value, @bg-parallax | fieldset (background widget), Background variables |
input type="video" (only in the fieldset) | video as the third kind of the widget | bg.value.url | @bg-value | video (in the background widget) |
header | heading of a group | – | – | header |
Text fields with the names videoFile, videoFile2, subtitleFile | text field with “Choose file…” | text | text | File and video fields |
Attributes of the input fields#
| Attribute | Applies to | Meaning | Entry |
|---|---|---|---|
name | all fields | name of the value: JavaScript identifier and LESS variable @name; letters, digits, underscore, starts with a letter | name |
title | all fields | label in the panel (without it: the name) | title |
value | text, color, range, image, widget inputs | default value | value, Default values |
checked | checkbox | default “on” | checked |
min, max, step | range | range and step size (0, 100, 1) | min, max, step |
rows | textarea | height 2 to 30 (default 5) | rows |
selected | option, widget inputs | default of the selection or of the background kind | selected |
parallax | input type="image" in the fieldset | parallax switch on in advance | fieldset (background widget) |
condition | header, fields, fieldset | show the field only as long as the expression does not yield exactly false | condition |
inline | range | is not evaluated | inline |
type="background" | fieldset | is not read (writing convention) | fieldset (background widget) |
Reserved names with an underscore at the start and the automatic sections of the panel: Automatic sections. Automatic overlay fields (overlay, overlayColor, overlayOpacity): Automatic overlay fields.
Directives and markers in the template#
Directives#
| Name | Value | Effect | Entry |
|---|---|---|---|
vn-if | expression | removes the element for exactly false | vn-if |
vn-strict-if | switch | remove all vn-if of the block for any falsy value | vn-strict-if |
vn-class | object, list or text | add classes conditionally | vn-class |
vn-style | object | set inline styles conditionally (no --variables) | vn-style |
vn-theme-style | classes | add classes of the theme settings | vn-theme-style |
Class vn-overlay with opacity, bg-color | number 0 to 1, color | darkening layer (position:absolute; inset:0) | vn-overlay |
vn-buttons, vn-menu | switch | markers for the target of vn-theme-style | vn-buttons, vn-menu |
vn-video, data-vn-video-empty | switch | video container with an address field in the panel | vn-video, [The element [vn-video]](media.html#attr-vn-video) |
vn-article, data-multiline | switch | list (or div) as one text field with line input | vn-article, List fields: data-multiline and vn-article |
data-vn-icon | switch | mark the element as a changeable icon | data-vn-icon, data-vn-icon |
vn-parameters | block | input fields (is not output) | vn-parameters |
Expressions and evaluation order: Expressions. Older names (mbr-…): Older notations.
Further markers that an author writes#
| Marker | Location | Effect | Entry |
|---|---|---|---|
data-bg-video | root element | address of a background video | data-bg-video, Video background |
data-vn-editor-only | any element | visible only in the editor, removed in the export | Marker data-vn-editor-only |
data-vn-popup-close | element in the popup | closes the popup | Closing from the content: data-vn-popup-close |
data-vn-consent-category | iframe, script | blocks until consent to functional, statistics or marketing | data-vn-consent-category, Automatic blocking |
data-vn-cookie-settings | a | opens the cookie settings | Open cookie settings |
data-vn-anim, data-vn-anim-t | text, image | animation (set by the VN Animation tool) | data-vn-anim and data-vn-anim-t, Animations: VN Animation |
data-vn-drag, -x, -y, -size | image of a scene | layer can be dragged with the mouse, with field names for position and size | Dragging layers: data-vn-drag |
Class vn-zoom, vn-nozoom; data-vn-skip, -caption, -full, -group, -badge | image, container | lightbox | Markers |
Class vn-ic, vn-ic-svg; data-vn-svg, data-vn-svg-mode | icon in text | changeable text icon, own SVG | Icons in text |
Class vn-tip, vn-tip-plain; data-vn-tip-html, -bg, -fg, -trigger | word in text | tooltip | Tooltips on words |
Class notranslate | element | exclude from the VN Translator | Marking exceptions |
li.vn-submenu, a.vn-submenu-toggle, ul.vn-submenu-list | menu | submenu that opens to the side | Submenu: vn-submenu |
Class vn-bgvid, vn-bgvid-el, vn-bgvid-poster … | “Video background” block | hero with background video | The “Video background” block (vn-bgvid) |
data-position="top" | <script type="text/x-vn-php"> | PHP code at the start of the file | Relationship to the code editor, Baking in texts and adjustments |
type="text/x-vn-php" | script | protected PHP code (the export inserts it raw) | Protected PHP code in text, How the block includes the PHP |
Markers set by the program#
Do not write these yourself; they appear in the stored template and disappear in the export (Markers set by the program).
| Marker | Set on | Entry |
|---|---|---|
data-vn-text-id="tN" | editable texts | data-vn-text-id |
data-vn-image-key="feld" | images of image fields and root with widget | Image field: data-vn-image-key |
data-vn-free-image-id="fiN" | fixed images | Free image: data-vn-free-image-id |
data-vn-button-id="btnN", data-vn-btn-extra-classes | a.btn | a.btn |
data-vn-icon-id="iconN", data-vn-icon-extra-classes | icons | data-vn-icon |
data-vn-nav-icon | icon before/after a menu item | Icon before the menu item |
data-vn-cms-block, data-vn-cms, data-vn-cms-img, data-vn-cms-link | export with CMS | Markers in the finished HTML |
data-vn-cc-src, data-vn-cc-category, class vn-cc-gate | blocked embeds in the export | Automatic blocking |
data-vn-sform-ready, data-vnfr-pending, data-vnfr-rendered, data-vntabelle-ready | form and table scripts | The form element: data attributes, The Form Renderer block, CSV and XLSX as a table: VN Table |
Markers of forms, PDF, search, table#
| Marker | Effect | Entry |
|---|---|---|
form.vn-sform-form, div.vn-sform-field[data-type], .vn-sform-label, div.vn-sform-hp, a[data-vn-sform-submit], .vn-sform-status | static form | Basic structure, Field types |
data-recipient, data-subject, data-success, data-thankyou, data-mailer | settings on the form | The form element: data attributes |
style="--span:N" | field width (12 columns) | Grid: --span |
data-vn-captcha-q, -answer, -token, data-vn-copytosender | security question, copy to the sender | Math security question, Copy to the sender |
section.vn-formrender, .vnfr-data[data-…], .vnfr-out | Form Renderer block | The Form Renderer block |
iframe[data-vn-pdf-src] | PDF viewer | [PDF: iframe[data-vn-pdf-src]](media.html#pdf-viewer) |
data-vntabelle-root, th[data-vnsort], td[data-label] | VN Table | CSV and XLSX as a table: VN Table |
section.vn-search, .vns-data[data-…] | VN Search | Search: VN Search |
video.vn-video-el with data-start, -end, -rate, -volume, -viewplay, -exclusive, -lazy, -player | self-hosted video | Self-hosted video: the “Video” block |
vn-galerie-host, .vn-gal-wrap, .vn-gal-grid … | VN Gallery | Gallery: VN Gallery |
Placeholders and variables#
| Form | Location | Result | Entry |
|---|---|---|---|
{{name}} | template (text, attributes, script, style) | value of the field, unmasked as HTML | {{name}} |
{{expression}} | template | result of a JavaScript expression; an error yields empty text | Expressions |
{{bg.type}}, {{bg.value}}, {{bg.value.url}}, {{bg.parallax}} | template | fields of the background widget | Object fields |
{{vn-id}} | template (also in the script) | identifier of the instance (blk-… or anchor ID) | {{vn-id}} |
{{vnEnc(text)}} | template, conditions | encodeURIComponent for data- attributes | vnEnc(text), Text data in attributes: vnEnc |
{{vnEmbed(address)}} | template | YouTube/Vimeo address to embed address | vnEmbed(address) |
{{…}} in a.btn | template | stays literally | Placeholders in buttons |
@name | style.less | value of the field as a LESS variable | Variables from the properties |
@bg-type, @bg-value, @bg-parallax | style.less | background variables (only with a widget) | Background variables |
@primaryColor, @mainFont, @display1Size … | style.less | theme variables with defaults | Theme variables |
~"@{name}", e(@name) | style.less | output text without quotation marks | Outputting values as text in CSS |
{{secret:NAME}}, {{secret-php:NAME}} | files of an export contribution | insert a secret (secret-php masks \, " and from version 1.3.100 also $) | ctx.project.secrets |
{{mbr-id}} | older packages | same as {{vn-id}} | Older notations |
Attributes on the root element#
| Attribute | Effect | Entry |
|---|---|---|
global | site-wide block (only on the very first element) | global |
once | group of the site-wide block (menu, footers, own name); a new block replaces the old one | once |
plugins | plugin folder of a Bootstrap 4 theme | plugins |
data-bs-version | marks Bootstrap 5 blocks | data-bs-version |
data-bg-video | address of the background video | data-bg-video |
vn-strict-if | strict vn-if in the whole block | vn-strict-if |
id, class | are kept; instance class vn-imp-<alias>-<identifier> is added | id and class, Identifiers: alias, label, group |
group, always-top, not-draggable, position-absolute, data-app-selector, data-app-placeholder, data-toolbar | are not evaluated | group, Attributes that are not evaluated |
Package files and params.json#
Files in the ZIP#
| File | Required | Meaning | Entry |
|---|---|---|---|
params.json | yes | name, alias, list of blocks | params.json |
components/<name>/template.html | yes | markup and <vn-parameters> | template.html |
components/<name>/style.less (or style.css) | no | style of the block | style.less or style.css |
components/<name>/thumb.png | no | preview in the selection | thumb.png |
components/_images/ | no | shared images, reference ../_images/<file> | components/_images |
plugins/theme/css/style.css, fonts/style.css, further plugins/**/*.css | no | theme CSS (once per project) | Which files are loaded |
thumbnail.jpg | no | preview in the online gallery | thumbnail.jpg and the gallery preview |
plugins/ (JavaScript) | no | only for Bootstrap 4 themes | plugins/ and fonts/, Bootstrap attributes and Bootstrap mode |
Fields of params.json#
| Field | Meaning | Entry |
|---|---|---|
name | display name of the package | params.json |
alias | identifier of the package; forms alias and class | params.json, Identifiers: alias, label, group |
title | determines the identifier of the theme CSS | Only once per project |
components[].path | folder of the block (required) | params.json |
components[]._title, _group | display name, group | params.json |
components[]._once | display only “· site-wide” | params.json |
theme.settings[] (var, type, default, title, set) | theme variables for LESS | Theme properties (params.theme) |
theme.customLESS | LESS file whose CSS is added to the theme CSS | Theme properties (params.theme) |
appScript | a package with appScript but without components is rejected | params.json |
manifest.json of an extension#
| Field | Meaning | Entry |
|---|---|---|
id | required; 2 to 48 characters; never change | manifest.json |
name, name_<language> | name of the tile | manifest.json |
description, description_<language> | description | manifest.json |
version | display and update comparison | manifest.json |
icon | abbreviation in the tile's symbol | manifest.json |
author | author | manifest.json |
main | program file (default tool.js) | manifest.json, tool.js |
Further files of an extension: Package layout (payload.js, dom.js, style.css, *.vndext, thumbnail.jpg).
Program interface ctx#
All entries are in the chapter on extensions, section The interface ctx.
| Entry | Short description | Entry |
|---|---|---|
ctx.projectDir | folder of the opened project or null | The interface ctx |
ctx.getPages(), ctx.getGlobalBlocks() | pages and site-wide blocks (working objects, read only) | The interface ctx |
ctx.switchToPage(id) | switch to the page | The interface ctx |
ctx.askConfirm(text) | confirmation dialog, returns true/false | ctx.askConfirm |
ctx.openToolWindow(title, element, opts) | open a tool window | ctx.openToolWindow |
ctx.closeToolWindow() | close the tool window | ctx.closeToolWindow |
ctx.extension | { id, version, baseUrl } of the extension | The interface ctx |
ctx.project.getInfo() | copy of the project data | ctx.project.getInfo |
ctx.project.buildFiles() | build the finished pages in memory | ctx.project.buildFiles |
ctx.project.updatePage(id, patch) | change fields of a page | ctx.project.updatePage |
ctx.project.updateSite(patch) | change website settings | ctx.project.updateSite |
ctx.project.getGlobalHtml(), setGlobalHtml(patch) | global HTML insertions | ctx.project.getGlobalHtml and setGlobalHtml |
ctx.project.listImages(), setImageAlt(…) | read and set images with alt text | ctx.project.listImages and setImageAlt |
ctx.project.assetSizes(paths) | file sizes under assets/ and publish/ | ctx.project.assetSizes |
ctx.project.addPage(opts) | create a page with an HTML block | ctx.project.addPage |
ctx.project.newEmptyPage(opts) | create an empty page and switch to it | ctx.project.newEmptyPage |
ctx.project.findInBlocks(pattern) | search the HTML and CSS of all blocks for a pattern | ctx.project.findInBlocks |
ctx.project.selectBlock(…), showPage(id), canvas() | select a block, show a page, read the work area | ctx.project.selectBlock and showPage |
ctx.project.colorUsage(), replaceColors(map, opts) | list and replace adjustable colors | ctx.project.colorUsage and replaceColors |
ctx.project.settings.get(), set(obj) | settings of the extension in the project | ctx.project.settings |
ctx.project.exportContribution.get(), set(obj) | contribution to the export (head, bodyEnd, files) | ctx.project.exportContribution |
ctx.project.secrets.set(name, value), names() | secrets in the program profile | ctx.project.secrets |
ctx.project.ai.providers(), ask(…), openSettings(), speechProvider(), transcribe(…) | use AI access | ctx.project.ai |
ctx.blocks.importPackage(buffer, opts) | import and insert a block package | ctx.blocks.importPackage |
ctx.blocks.importToLibrary(buffer) | put a package into the library | ctx.blocks.importToLibrary |
ctx.blocks.findByAlias(alias), setValues(id, patch) | find blocks of a block type, set values | ctx.blocks.findByAlias and setValues |
ctx.blocks.describe(id), selected(), pageBlocks() | describe properties and blocks | ctx.blocks.describe, selected, pageBlocks |
ctx.blocks.catalog(), addFromCatalog(key, opts) | list insertable blocks and insert them | ctx.blocks.catalog and addFromCatalog |
ctx.blocks.texts.list(), set(entries) | read and write editable texts | ctx.blocks.texts |
ctx.blocks.images.list(), set(entries) | read and set image slots | ctx.blocks.images |
ctx.blocks.addBlock, findGalleries, updateGallery, anim.* | interfaces of the built-in tools | Further entries of ctx.blocks |
window.vnDesigner.* | program bridge (saveAsset, listAssetImages, openExternal, loadSmtpConfig, netCheckUrl …) | The interface ctx |
Libraries under vendor/#
The export copies only what the pages use (Shipped libraries, Runtime files from vendor/).
| Library | Folder | Trigger in the export | Entry |
|---|---|---|---|
| Bootstrap 5.0.1 (CSS and bundle JS) | vendor/bootstrap.min.css, vendor/bootstrap.bundle.min.js | always (except Bootstrap mode “from the theme”) | Bootstrap 5.0.1 and Bootstrap Icons |
| Bootstrap Icons | vendor/bootstrap-icons/ | always | Bootstrap 5.0.1 and Bootstrap Icons |
| Flags | vendor/flags | as project files under assets/ | Custom SVG icons and flags |
| jQuery 3.5.1 | vendor/jquery.min.js | only Bootstrap mode “from the theme” | jQuery and theme plugins (Bootstrap theme mode) |
| VN Lightbox | vendor/vn-lightbox/ | site setting | VN Lightbox, Lightbox |
| VN Cookie Consent | vendor/vn-cookie-consent/ | site setting | VN Cookie Consent, Cookie consent and privacy |
| VN Popup | vendor/vn-popup/ | page contains a popup | VN Popup, Popup |
| VN CMS | vendor/vn-cms/ | page contains a CMS block | VN CMS, CMS: texts and images on the finished page |
| VN Submenu | vendor/vn-submenu/ | li.vn-submenu in the HTML | VN Submenu |
| VN Tooltip | vendor/vn-tooltip/ | span.vn-tip in the HTML | VN Tooltip |
| VN Video | vendor/vn-video/ | video.vn-video-el in the HTML | Self-hosted video: the “Video” block |
| VN Background video | vendor/vn-bgvideo/ | data-bg-video with a value or .vn-bgvid | Video background |
| VN Translator | vendor/vn-translate/ | site setting | VN Translator, Translator: VN Translator |
| VN WhatsApp | vendor/vn-whatsapp/ | site setting (with number) | VN WhatsApp |
| VN Form, Form Renderer | vendor/vn-sform/, vendor/vn-formrender/ | form.vn-sform-form or Form Renderer block | Overview, Export behavior |
| VN PDF viewer (PDF.js 3.11.174) | vendor/vn-pdf-viewer/ | block with a viewer address | [PDF: iframe[data-vn-pdf-src]](media.html#pdf-viewer) |
| VN Search, VN Blog | vendor/vn-search/, vendor/vn-blog/ | the respective blocks | Search: VN Search, Blog: VN Blog |
| jszip, less, CodeMirror | vendor/ | editor only, never in the export | Shipped libraries |
Runtime interfaces of the page: window.vnCookieConsent with getConsent(), openSettings(), labelGates() (Own gate in the block (gate markup)); events vn-cc-activated (Own gate in the block (gate markup)) and vn-cc-consent (Event vn-cc-consent); VNPopup.open(id), close(id), isOpen() (JavaScript interface: VNPopup).
Block values and overrides#
| Name | Meaning | Entry |
|---|---|---|
block.values[<field>] | values of the input fields | How values reach the template and the LESS |
block.anchorId, block.popup, block.cms | anchor ID, popup and CMS settings | Automatic sections, Settings, Enabling |
_textScalePct, _textWidthPct, _textOffsetYPx | sliders for text size, width, position | Size, width and position per block |
_menuFontPx, _brandFontPx, _togglerColor, _ddBg, _ddText, _ddHoverBg, _ddHoverText | sliders of a menu block | Sliders of a menu block |
_videoUrl<i>, _videoAuto<i>, _videoLoop<i> | video address, autostart, repeat per vn-video container | [The element [vn-video]](media.html#attr-vn-video) |
textOverrides, textTagOverrides, textLinkOverrides, textAlignOverrides | changes to texts | Overview |
buttonOverrides, iconOverrides, navIconOverrides | changes to buttons and icons | Values of a button, Values of an icon |
imageOverrides, imageLinkOverrides, imageAltOverrides, animOverrides | changes to images and animations | Alt text, title and link, Animations: VN Animation |
schemaEntry.builder, schemaEntry.freeSurface | data model of the builder and the free surface | The stored data model, Free surface |