VN-Designer Developer Documentation
15

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 typeField in the panelValue in the templateValue in the LESSEntry
input type="text" (also any unknown type)text fieldtexttext in quotation markstext, Other types
textareamulti-line text fieldtext with line breakstext in quotation markstextarea
input type="checkbox"switchtrue or falsetrue or falsecheckbox
input type="color"color pickertext #rrggbbcolorcolor
input type="range"slider with number fieldtext ("4")numberrange
select with optionselection listtext (value of the option)text in quotation marksselect and option
input type="image"image fieldtext (image address)text in quotation marksimage
fieldset with image, color, videobackground widgetobject { type, value, parallax }@bg-type, @bg-value, @bg-parallaxfieldset (background widget), Background variables
input type="video" (only in the fieldset)video as the third kind of the widgetbg.value.url@bg-valuevideo (in the background widget)
headerheading of a group––header
Text fields with the names videoFile, videoFile2, subtitleFiletext field with “Choose file…”texttextFile and video fields

Attributes of the input fields#

AttributeApplies toMeaningEntry
nameall fieldsname of the value: JavaScript identifier and LESS variable @name; letters, digits, underscore, starts with a lettername
titleall fieldslabel in the panel (without it: the name)title
valuetext, color, range, image, widget inputsdefault valuevalue, Default values
checkedcheckboxdefault “on”checked
min, max, steprangerange and step size (0, 100, 1)min, max, step
rowstextareaheight 2 to 30 (default 5)rows
selectedoption, widget inputsdefault of the selection or of the background kindselected
parallaxinput type="image" in the fieldsetparallax switch on in advancefieldset (background widget)
conditionheader, fields, fieldsetshow the field only as long as the expression does not yield exactly falsecondition
inlinerangeis not evaluatedinline
type="background"fieldsetis 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#

NameValueEffectEntry
vn-ifexpressionremoves the element for exactly falsevn-if
vn-strict-ifswitchremove all vn-if of the block for any falsy valuevn-strict-if
vn-classobject, list or textadd classes conditionallyvn-class
vn-styleobjectset inline styles conditionally (no --variables)vn-style
vn-theme-styleclassesadd classes of the theme settingsvn-theme-style
Class vn-overlay with opacity, bg-colornumber 0 to 1, colordarkening layer (position:absolute; inset:0)vn-overlay
vn-buttons, vn-menuswitchmarkers for the target of vn-theme-stylevn-buttons, vn-menu
vn-video, data-vn-video-emptyswitchvideo container with an address field in the panelvn-video, [The element [vn-video]](media.html#attr-vn-video)
vn-article, data-multilineswitchlist (or div) as one text field with line inputvn-article, List fields: data-multiline and vn-article
data-vn-iconswitchmark the element as a changeable icondata-vn-icon, data-vn-icon
vn-parametersblockinput fields (is not output)vn-parameters

Expressions and evaluation order: Expressions. Older names (mbr-…): Older notations.

Further markers that an author writes#

MarkerLocationEffectEntry
data-bg-videoroot elementaddress of a background videodata-bg-video, Video background
data-vn-editor-onlyany elementvisible only in the editor, removed in the exportMarker data-vn-editor-only
data-vn-popup-closeelement in the popupcloses the popupClosing from the content: data-vn-popup-close
data-vn-consent-categoryiframe, scriptblocks until consent to functional, statistics or marketingdata-vn-consent-category, Automatic blocking
data-vn-cookie-settingsaopens the cookie settingsOpen cookie settings
data-vn-anim, data-vn-anim-ttext, imageanimation (set by the VN Animation tool)data-vn-anim and data-vn-anim-t, Animations: VN Animation
data-vn-drag, -x, -y, -sizeimage of a scenelayer can be dragged with the mouse, with field names for position and sizeDragging layers: data-vn-drag
Class vn-zoom, vn-nozoom; data-vn-skip, -caption, -full, -group, -badgeimage, containerlightboxMarkers
Class vn-ic, vn-ic-svg; data-vn-svg, data-vn-svg-modeicon in textchangeable text icon, own SVGIcons in text
Class vn-tip, vn-tip-plain; data-vn-tip-html, -bg, -fg, -triggerword in texttooltipTooltips on words
Class notranslateelementexclude from the VN TranslatorMarking exceptions
li.vn-submenu, a.vn-submenu-toggle, ul.vn-submenu-listmenusubmenu that opens to the sideSubmenu: vn-submenu
Class vn-bgvid, vn-bgvid-el, vn-bgvid-poster …“Video background” blockhero with background videoThe “Video background” block (vn-bgvid)
data-position="top"<script type="text/x-vn-php">PHP code at the start of the fileRelationship to the code editor, Baking in texts and adjustments
type="text/x-vn-php"scriptprotected 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).

MarkerSet onEntry
data-vn-text-id="tN"editable textsdata-vn-text-id
data-vn-image-key="feld"images of image fields and root with widgetImage field: data-vn-image-key
data-vn-free-image-id="fiN"fixed imagesFree image: data-vn-free-image-id
data-vn-button-id="btnN", data-vn-btn-extra-classesa.btna.btn
data-vn-icon-id="iconN", data-vn-icon-extra-classesiconsdata-vn-icon
data-vn-nav-iconicon before/after a menu itemIcon before the menu item
data-vn-cms-block, data-vn-cms, data-vn-cms-img, data-vn-cms-linkexport with CMSMarkers in the finished HTML
data-vn-cc-src, data-vn-cc-category, class vn-cc-gateblocked embeds in the exportAutomatic blocking
data-vn-sform-ready, data-vnfr-pending, data-vnfr-rendered, data-vntabelle-readyform and table scriptsThe form element: data attributes, The Form Renderer block, CSV and XLSX as a table: VN Table

Markers of forms, PDF, search, table#

MarkerEffectEntry
form.vn-sform-form, div.vn-sform-field[data-type], .vn-sform-label, div.vn-sform-hp, a[data-vn-sform-submit], .vn-sform-statusstatic formBasic structure, Field types
data-recipient, data-subject, data-success, data-thankyou, data-mailersettings on the formThe form element: data attributes
style="--span:N"field width (12 columns)Grid: --span
data-vn-captcha-q, -answer, -token, data-vn-copytosendersecurity question, copy to the senderMath security question, Copy to the sender
section.vn-formrender, .vnfr-data[data-…], .vnfr-outForm Renderer blockThe 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 TableCSV and XLSX as a table: VN Table
section.vn-search, .vns-data[data-…]VN SearchSearch: VN Search
video.vn-video-el with data-start, -end, -rate, -volume, -viewplay, -exclusive, -lazy, -playerself-hosted videoSelf-hosted video: the “Video” block
vn-galerie-host, .vn-gal-wrap, .vn-gal-grid …VN GalleryGallery: VN Gallery

Placeholders and variables#

FormLocationResultEntry
{{name}}template (text, attributes, script, style)value of the field, unmasked as HTML{{name}}
{{expression}}templateresult of a JavaScript expression; an error yields empty textExpressions
{{bg.type}}, {{bg.value}}, {{bg.value.url}}, {{bg.parallax}}templatefields of the background widgetObject fields
{{vn-id}}template (also in the script)identifier of the instance (blk-… or anchor ID){{vn-id}}
{{vnEnc(text)}}template, conditionsencodeURIComponent for data- attributesvnEnc(text), Text data in attributes: vnEnc
{{vnEmbed(address)}}templateYouTube/Vimeo address to embed addressvnEmbed(address)
{{…}} in a.btntemplatestays literallyPlaceholders in buttons
@namestyle.lessvalue of the field as a LESS variableVariables from the properties
@bg-type, @bg-value, @bg-parallaxstyle.lessbackground variables (only with a widget)Background variables
@primaryColor, @mainFont, @display1Size …style.lesstheme variables with defaultsTheme variables
~"@{name}", e(@name)style.lessoutput text without quotation marksOutputting values as text in CSS
{{secret:NAME}}, {{secret-php:NAME}}files of an export contributioninsert a secret (secret-php masks \, " and from version 1.3.100 also $)ctx.project.secrets
{{mbr-id}}older packagessame as {{vn-id}}Older notations

Attributes on the root element#

AttributeEffectEntry
globalsite-wide block (only on the very first element)global
oncegroup of the site-wide block (menu, footers, own name); a new block replaces the old oneonce
pluginsplugin folder of a Bootstrap 4 themeplugins
data-bs-versionmarks Bootstrap 5 blocksdata-bs-version
data-bg-videoaddress of the background videodata-bg-video
vn-strict-ifstrict vn-if in the whole blockvn-strict-if
id, classare kept; instance class vn-imp-<alias>-<identifier> is addedid and class, Identifiers: alias, label, group
group, always-top, not-draggable, position-absolute, data-app-selector, data-app-placeholder, data-toolbarare not evaluatedgroup, Attributes that are not evaluated

Package files and params.json#

Files in the ZIP#

FileRequiredMeaningEntry
params.jsonyesname, alias, list of blocksparams.json
components/<name>/template.htmlyesmarkup and <vn-parameters>template.html
components/<name>/style.less (or style.css)nostyle of the blockstyle.less or style.css
components/<name>/thumb.pngnopreview in the selectionthumb.png
components/_images/noshared images, reference ../_images/<file>components/_images
plugins/theme/css/style.css, fonts/style.css, further plugins/**/*.cssnotheme CSS (once per project)Which files are loaded
thumbnail.jpgnopreview in the online gallerythumbnail.jpg and the gallery preview
plugins/ (JavaScript)noonly for Bootstrap 4 themesplugins/ and fonts/, Bootstrap attributes and Bootstrap mode

Fields of params.json#

FieldMeaningEntry
namedisplay name of the packageparams.json
aliasidentifier of the package; forms alias and classparams.json, Identifiers: alias, label, group
titledetermines the identifier of the theme CSSOnly once per project
components[].pathfolder of the block (required)params.json
components[]._title, _groupdisplay name, groupparams.json
components[]._oncedisplay only “· site-wide”params.json
theme.settings[] (var, type, default, title, set)theme variables for LESSTheme properties (params.theme)
theme.customLESSLESS file whose CSS is added to the theme CSSTheme properties (params.theme)
appScripta package with appScript but without components is rejectedparams.json

manifest.json of an extension#

FieldMeaningEntry
idrequired; 2 to 48 characters; never changemanifest.json
name, name_<language>name of the tilemanifest.json
description, description_<language>descriptionmanifest.json
versiondisplay and update comparisonmanifest.json
iconabbreviation in the tile's symbolmanifest.json
authorauthormanifest.json
mainprogram 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.

EntryShort descriptionEntry
ctx.projectDirfolder of the opened project or nullThe interface ctx
ctx.getPages(), ctx.getGlobalBlocks()pages and site-wide blocks (working objects, read only)The interface ctx
ctx.switchToPage(id)switch to the pageThe interface ctx
ctx.askConfirm(text)confirmation dialog, returns true/falsectx.askConfirm
ctx.openToolWindow(title, element, opts)open a tool windowctx.openToolWindow
ctx.closeToolWindow()close the tool windowctx.closeToolWindow
ctx.extension{ id, version, baseUrl } of the extensionThe interface ctx
ctx.project.getInfo()copy of the project datactx.project.getInfo
ctx.project.buildFiles()build the finished pages in memoryctx.project.buildFiles
ctx.project.updatePage(id, patch)change fields of a pagectx.project.updatePage
ctx.project.updateSite(patch)change website settingsctx.project.updateSite
ctx.project.getGlobalHtml(), setGlobalHtml(patch)global HTML insertionsctx.project.getGlobalHtml and setGlobalHtml
ctx.project.listImages(), setImageAlt(…)read and set images with alt textctx.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 blockctx.project.addPage
ctx.project.newEmptyPage(opts)create an empty page and switch to itctx.project.newEmptyPage
ctx.project.findInBlocks(pattern)search the HTML and CSS of all blocks for a patternctx.project.findInBlocks
ctx.project.selectBlock(…), showPage(id), canvas()select a block, show a page, read the work areactx.project.selectBlock and showPage
ctx.project.colorUsage(), replaceColors(map, opts)list and replace adjustable colorsctx.project.colorUsage and replaceColors
ctx.project.settings.get(), set(obj)settings of the extension in the projectctx.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 profilectx.project.secrets
ctx.project.ai.providers(), ask(…), openSettings(), speechProvider(), transcribe(…)use AI accessctx.project.ai
ctx.blocks.importPackage(buffer, opts)import and insert a block packagectx.blocks.importPackage
ctx.blocks.importToLibrary(buffer)put a package into the libraryctx.blocks.importToLibrary
ctx.blocks.findByAlias(alias), setValues(id, patch)find blocks of a block type, set valuesctx.blocks.findByAlias and setValues
ctx.blocks.describe(id), selected(), pageBlocks()describe properties and blocksctx.blocks.describe, selected, pageBlocks
ctx.blocks.catalog(), addFromCatalog(key, opts)list insertable blocks and insert themctx.blocks.catalog and addFromCatalog
ctx.blocks.texts.list(), set(entries)read and write editable textsctx.blocks.texts
ctx.blocks.images.list(), set(entries)read and set image slotsctx.blocks.images
ctx.blocks.addBlock, findGalleries, updateGallery, anim.*interfaces of the built-in toolsFurther 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/).

LibraryFolderTrigger in the exportEntry
Bootstrap 5.0.1 (CSS and bundle JS)vendor/bootstrap.min.css, vendor/bootstrap.bundle.min.jsalways (except Bootstrap mode “from the theme”)Bootstrap 5.0.1 and Bootstrap Icons
Bootstrap Iconsvendor/bootstrap-icons/alwaysBootstrap 5.0.1 and Bootstrap Icons
Flagsvendor/flagsas project files under assets/Custom SVG icons and flags
jQuery 3.5.1vendor/jquery.min.jsonly Bootstrap mode “from the theme”jQuery and theme plugins (Bootstrap theme mode)
VN Lightboxvendor/vn-lightbox/site settingVN Lightbox, Lightbox
VN Cookie Consentvendor/vn-cookie-consent/site settingVN Cookie Consent, Cookie consent and privacy
VN Popupvendor/vn-popup/page contains a popupVN Popup, Popup
VN CMSvendor/vn-cms/page contains a CMS blockVN CMS, CMS: texts and images on the finished page
VN Submenuvendor/vn-submenu/li.vn-submenu in the HTMLVN Submenu
VN Tooltipvendor/vn-tooltip/span.vn-tip in the HTMLVN Tooltip
VN Videovendor/vn-video/video.vn-video-el in the HTMLSelf-hosted video: the “Video” block
VN Background videovendor/vn-bgvideo/data-bg-video with a value or .vn-bgvidVideo background
VN Translatorvendor/vn-translate/site settingVN Translator, Translator: VN Translator
VN WhatsAppvendor/vn-whatsapp/site setting (with number)VN WhatsApp
VN Form, Form Renderervendor/vn-sform/, vendor/vn-formrender/form.vn-sform-form or Form Renderer blockOverview, 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 Blogvendor/vn-search/, vendor/vn-blog/the respective blocksSearch: VN Search, Blog: VN Blog
jszip, less, CodeMirrorvendor/editor only, never in the exportShipped 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#

NameMeaningEntry
block.values[<field>]values of the input fieldsHow values reach the template and the LESS
block.anchorId, block.popup, block.cmsanchor ID, popup and CMS settingsAutomatic sections, Settings, Enabling
_textScalePct, _textWidthPct, _textOffsetYPxsliders for text size, width, positionSize, width and position per block
_menuFontPx, _brandFontPx, _togglerColor, _ddBg, _ddText, _ddHoverBg, _ddHoverTextsliders of a menu blockSliders 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, textAlignOverrideschanges to textsOverview
buttonOverrides, iconOverrides, navIconOverrideschanges to buttons and iconsValues of a button, Values of an icon
imageOverrides, imageLinkOverrides, imageAltOverrides, animOverrideschanges to images and animationsAlt text, title and link, Animations: VN Animation
schemaEntry.builder, schemaEntry.freeSurfacedata model of the builder and the free surfaceThe stored data model, Free surface