VN-Designer Developer Documentation
14

Pitfalls and checklist

Tick-off checklists to work through before publishing a block, a theme or an extension, and a table of all pitfalls described in the chapters (symptom, cause, solution) with links to the detail entries.

Checklist before publishing#

Go through the list item by item before you pass a block, a theme or an extension on or upload it to the gallery. Each item links to the entry with the details.

Block#

Structure and input fields

  • ☐ The template has one root element; <vn-parameters> sits inside it, contains only direct children and appears exactly once (The root element, Overview).
  • ☐ Field names in camelCase made of letters and digits, no hyphen, no umlaut, no underscore at the start (name, Automatic sections).
  • ☐ Color defaults with six digits (#ffffff), slider defaults on the grid min + n × step, image defaults as ../_images/<file> (color, range, image).
  • ☐ Write conditions on text and numbers as a comparison or !!name; slider values are text, calculate with Number(n) (vn-if, Expressions).
  • ☐ Use the word overlay only if you want the automatic overlay fields; otherwise declare your own fields (Automatic overlay fields).
  • ☐ Text from the panel appears in attributes only as {{vnEnc(…)}} (vnEnc(text), Text data in attributes: vnEnc).
  • ☐ No fixed IDs: use {{vn-id}} for references inside the block, because the same block can appear several times on a page ({{vn-id}}).

Style

  • ☐ Give your own class names and @keyframes/@font-face a short prefix for the block (Bootstrap and classes, Scope and root).
  • ☐ @bg-… only with a background widget and inside a condition on @bg-type; selection values in selectors with e() or ~"@{…}"; no BOM, no @import, no default() (Checklist).
  • ☐ No body, html or :root in the block LESS; set variables for the block directly on the root (Scope and root).
  • ☐ Set sizes of body text (p, li) deliberately: otherwise the font size of the site wins (Site settings that override your CSS).
  • ☐ Use !important only selectively (buttons, links) and cross-check it afterwards in the live preview (F5): in the editor it loses against !important from Bootstrap and the theme (Who wins (measured), Colors and links in block CSS).
  • ☐ Check media queries in the live preview (tablet, phone), not in the editor (The #canvas trap in the theme CSS).

Editable content

Scripts

Forms, media, privacy

Theme or package#

Extension#

  • ☐ manifest.json: valid id that you never change; raise version with every change (manifest.json).
  • ☐ Include imported modules (dom.js, payload.js …) with an incremented ?v= (Lifecycle).
  • ☐ Handle missing entries of ctx (older program version) (The interface ctx).
  • ☐ Export contribution only under assets/<own id>/…, at most 30 files, 400000 characters each (ctx.project.exportContribution).
  • ☐ Secrets only via ctx.project.secrets; {{secret-php:NAME}} only in PHP strings with double quotes (from version 1.3.100 $ is also masked) (ctx.project.secrets).
  • ☐ PHP server parts: PHP 7.3 and newer, php -l, protect data/ yourself, validate input, escape output (PHP server parts).
  • ☐ No foreign servers, no eval, no innerHTML with raw data (Security rules).
  • ☐ Set the contribution to null and export again: the files must disappear (Build, test, deliver).
  • ☐ thumbnail.jpg in the package if the extension is to go into the gallery (Build, test, deliver).

Pitfalls at a glance#

Each table groups the pitfalls of one topic area: how you recognize them, what causes them, what helps and where the details are.

Package, import and files#

SymptomCauseSolutionDetails
Import reports "template.html not found under components/…"ZIP with backslashes (Compress-Archive of Windows PowerShell 5.1, ZipFile.CreateFromDirectory of the .NET Framework)pack with tar.exe or Python (paths with /)2. Pack it as a package
Import reports "params.json is not valid JSON"; block with “⚠ CSS error”BOM at the start of params.json or style.less (Set-Content -Encoding UTF8 of PowerShell 5.1)save as UTF-8 without BOM1. Create the folder and files, Errors in the LESS
Package is rejectedcomponents is missing or empty; appScript without components; params.json is missingcomponents with at least one entryparams.json
Background or field image is missing after the importdefault file:///… points to the author's computerimages in components/_images/, default ../_images/<file>image, Images and file names
Video or avif is missing in the packagefrom _images only jpg, jpeg, png, gif, svg, webp are extracteddo not put videos in the package; the user chooses a file or address in the “Video” fieldcomponents/_images
script.js next to the block has no effectthe import reads only template.html, style.less/style.css, thumb.pngJavaScript as <script> in template.htmlNo script file per block
Importing again creates another entry; a block on the page does not changeevery import is a new entry; existing blocks keep their stored templateinsert the block again; use the code editor for testing5. Keep working
Theme CSS is not updated on re-importthe identifier vn-theme-css-<title> already exists in the project: nothing is reloaded; packages with the same title share one theme CSScheck the theme CSS before the first import; in a new project the new CSS appliesOnly once per project
Colors or buttons of two themes collidetheme CSS and Bootstrap classes act on the whole page, not just in the block; identical class namesown classes with a prefix per theme; unique titleBootstrap and classes, Storage and self-healing
A newly inserted menu replaces the old one (or the footer)there is at most one block per once group in the projectchoose group names deliberately (menu, footers or your own name)once, Site-wide blocks: global and once
global is not recognized; once has no effectglobal must be on the very first element of the file (a <vn-parameters> block placed before it or a wrapping div prevents detection); once without global has no effectglobal and once on the root elementglobal
Block shows no preview imagethumb.png is missing; the gallery reads thumbnail.jpg, the program does notthumb.png per block, thumbnail.jpg for the packagethumb.png, thumbnail.jpg and the gallery preview
Video file is missing in the block you passed on (⇩ / ⤓)references to assets/… go into the package, but on import only images are extractedvideo via address (YouTube/Vimeo) or file selection in the blockExport as .vndext
Adjustments are missing in the exported user block⇩ (“Export as .vndext file”) takes the stored template unchangeduse ⤓ in the properties panelExport as .vndext
The code button of a builder block is lockedthe builder and the free surface are only rebuilt via “+” and the panelbuild the block in the “Custom code” tab or use the builderRelationship to the code editor

Template and input fields#

SymptomCauseSolutionDetails
The CSS does not reach a second top-level elementonly the first element gets the instance classwrap everything in one root elementThe root element
A field does not appear in the panelthe field is not a direct child of <vn-parameters>, has no name or sits in a second parameter blockdirect child, set name, only one blockOverview
{{…}} yields empty text everywhere; vn-if hides nothinga field name is not a valid identifier in JavaScript (hyphen, dot, digit at the start, reserved word)camelCase made of letters and digitsname
Block shows “⚠ CSS error”a field name with an umlaut or $ breaks the LESSname without umlaut and $name
{{n + 1}} yields 41 instead of 5the values of sliders are textNumber(n) + 1, n * 1range
The slider shows a different value than the LESS seesthe default is not on the grid min + n × step; the default stays storedput defaults on the gridrange
The panel shows black instead of the default colorcolor is not six digits (#fff, white)#rrggbbcolor
A field stays visible despite conditionit is hidden only for exactly false; an error (typo in the name) or undefined shows the field; the value is also kept in the hidden fieldwrite a comparison or !!name; coordinate the markup with vn-if yourselfcondition
An element stays despite vn-ifvn-if removes only for exactly false; an empty text, undefined or a typo leaves it in place!!name or a comparison; if needed vn-strict-ifvn-if, vn-strict-if
vn-class with a computed name does nothinga key such as {'n-' + mode: true} is a syntax errortext form vn-class="'n-' + mode"vn-class
vn-style does not set --variablecustom properties are discardedstyle="--k:{{k}}" or a variable in the LESS on the rootvn-style
Darkening (vn-overlay) lies over text or page headerthe layer fills the nearest positioned parent elementroot position: relative, content position: relative; z-index: 1vn-overlay
Overlay fields appear unintentionallythe word overlay appears in the template (also as a class or comment) and no field overlay of your own is declareddeclare your own fields or avoid the wordAutomatic overlay fields
A text from the panel breaks the markup or is inserted as HTML{{name}} inserts the value unmasked as HTMLin attributes {{vnEnc(name)}}, otherwise only in text content{{name}}, vnEnc(text)
{{ or }} in the script yields nonsense or empty textevery {{ … }} in the template is evaluated as an expression, also in the scriptbrackets with a space ({ {) or on separate linesPlaceholders in scripts and attributes
{{beschriftung}} appears literally in the buttonin <a class="btn"> placeholders in text and href are not evaluated (editor and export)put text and target fixed in the template; for panel values use an ordinary link without btnPlaceholders in buttons, Placeholders in buttons
A changed default in the package has no effect in existing blocksthe values are stored in the blockinsert the block againDefault values
Two fields behave like onethe same name shares one valueunique namesname

Style, LESS and CSS#

SymptomCauseSolutionDetails
Block without any CSS, label “⚠ CSS error”error in the LESS: @bg-type without a background widget, unknown variable, @import, when (default()), open blockread the message in the tooltip; fix the causeErrors in the LESS, Background variables
url(@bg-value) yields url(#f3f4f6)with a color, @bg-value is a coloralways inside when (@bg-type = 'image')Background variables
Selector .'grid'-x is invalid; aspect-ratio: '16/9' is discardedselection and text values arrive as LESS text with quotation markse(@x) or ~"@{x}"Outputting values as text in CSS
when (@text = abc) is never truealways compare texts in quotation marks; number against text (= "2") is never true@x = 'abc', numbers without quotation marksComparisons and conditions
Division gives a wrong result10px / 2 from literals is not rewrittenparentheses: (10px / 2), (@n / 2)Calculating
body, html, :root in the block LESS do nothingthey end up behind the instance class (.root :root)set variables on the root; site-wide rules in theme CSS or “Custom CSS”Scope and root
Two blocks overwrite each other's animation or font@keyframes and @font-face apply globallyprefix in the nameScope and root
p { font-size: 3rem; } in the block has no effectthe site's body text font size sets font-size on p, li … with !importantput sizes on div/span or set !importantSite settings that override your CSS
The block looks different in the editor than in the exportlayer reversal with !important: in the editor, block !important loses against !important from Bootstrap and the theme, in the export it wins; “Custom CSS” has no layer in the editorcheck in the live preview (F5) or in the export; !important only selectivelyWho wins (measured)
A rule in the theme CSS has no effect in the editor#canvas .x, html, body, :root inside @scope match nothing.x; for the editor :scope#canvas .x; for variables :scope { … }The #canvas trap in the theme CSS
Media queries switch “wrongly” in the editorin the editor the width of the program window applieslive preview with tablet/phoneThe #canvas trap in the theme CSS
Button or link color from the block LESS does not prevailtheme CSS with higher specificity or the font rules of the site win!important for colors, borders, font of buttons and links; check in the exportButtons and links, Colors and links in block CSS
An !important rule on .btn overrides the user's “Custom color”the dialog sets the color as an inline style without !important and removes the color class!important on the color class (.btn-primary)Custom color
A background image from style.less cannot be changed by clickimages only in the LESS cannot be assignedimage field, background widget or inline styleBackground image in the inline style
@primaryColor etc. is “undefined”theme variables are missing without a themeparams.theme.settings or your own fieldsTheme variables, Theme properties (params.theme)
Parallax has no effect on the phonebackground-attachment: fixedplan the image so that it also looks good without the effectParallax

Editable content#

SymptomCauseSolutionDetails
Edits end up on the wrong elementidentifiers (t3, btn0 …) are position numbers from the import; a template changed afterwards or identifiers deleted by hand shift themnever change identifiers by hand; add an element at the end instead of in betweenOverview
A clickable card (<a class="card">) becomes a single text fielda bare link is the field, its children do not countcard as a div with its own link or buttonWhich elements become text fields
Labels in the <form> are not clickablenothing inside form is captured as a text fieldchange field texts in the code editorWhich elements become text fields
<button class="btn"> cannot be editedonly <a class="btn"> is a button<a class="btn" role="button">a.btn
A custom attribute in the text disappears on the next savethe text sanitizer lets only an allowlist throughbuild the element outside text fieldsAllowed attributes and classes
A panel placeholder disappears after the text is editeda text field with a placeholder is replaced completely when editedpanel value and free text in separate elementsPlaceholders in text
The hamburger color has no effectthe block uses its own icon instead of .navbar-toggler-iconuse .navbar-toggler-iconHamburger icon
Text color and effects are missing on the finished page (CMS)in CMS text style is removedclasses in the block CSSOperation and security on the page
CMS block changes nothingpage is named .html or no password is setpage .php, set the password in the programEnabling
Image handles do not fitimage without a reliably determinable container (inline, position:absolute)background widget for filling imagesScaling images with the mouse
The icon cannot be changedan SVG, <img> or a CSS mask is not a changeable icon<i class="bi bi-…"> or data-vn-iconPreventing or excluding icons

Scripts#

SymptomCauseSolutionDetails
Panel changes are invisible in the editor (for example “typewriter does not show the new word”)if (closest('#canvas')) return; comes before setting the initial stateset the initial state, then returnRules for scripts in the editor
The content of a block is missing or not clickablethe script hides or moves DOM (opacity:0, reveal, carousel rebuild) in the editor toohide or move nothing in the editorRules for scripts in the editor
The text of a text field is “destroyed” after typingthe script rewrites the content of a data-vn-text-id element (letter spans); the intermediate state is saved while typingsplit text only at runtime outside #canvas; the template holds the plain textText animations at runtime, Rules for scripts in the editor
New blocks are never initializedthe init flag is a data- attribute and an old script has marked elements of new blocks with itflag as a JavaScript property (box.vnInit = 1)One-time initialization
After the first redraw in the editor the script never starts againa guard on window (window.fertig) is discarded with every render, on the real page it staysflag on the elementwindow properties apply for one pass only
The second instance of a block is brokenfixed IDs or global stateclasses, {{vn-id}}, namespaceOne-time initialization
is-builder or currentScript does not detect the editorthe program never sets is-builder; currentScript is null; there is no iframeel.closest('#canvas'); fall back to document.querySelector(…)What is not suitable for detection
bootstrap, vnCookieConsent, VNPopup are undefinedthe block script runs during parsing, before Bootstrap and the VN librarieswait for DOMContentLoadedOrder and waiting
$ or jQuery is undefinedjQuery exists only in Bootstrap theme modeplain JavaScriptjQuery and theme plugins (Bootstrap theme mode)
import in <script type="module"> fails in the editorthe editor runs scripts in new Functionclassic scriptPitfalls: script runs in the editor and destroys content
window.vnEnc is undefinedvnEnc, vnEmbed and {{vn-id}} are helpers of the template expression, not global functionsin the template data-x="{{vnEnc(x)}}", in the script decodeURIComponentText data in attributes: vnEnc
A text in a stand-in (data-vn-editor-only) can be edited in the editorin the editor the stand-in is an ordinary elementcreate it without body text or allow for itMarker data-vn-editor-only

Forms#

SymptomCauseSolutionDetails
Form sends nothing (“Form is not yet configured” or dead)without form.vn-sform-form the export delivers neither script nor PHP nor configuration; SMTP is not set up; data-mailer is missingform.vn-sform-form with data-mailer, set up SMTP in the programExample: contact form in a theme, SMTP settings in the program
Several recipients in data-recipient do not workmailer.php accepts exactly one address per formforwarding in the mailbox or several formsRecipients
“This recipient is not authorized for the form”the address is not in recipients.php (the export writes it from the exported pages)export the page again and upload itRecipients
A custom HTML form via native-form-handler.php sends to any addresswithout recipients.php (export with a version before 1.3.100) there is no recipient listfrom version 1.3.100 export again and upload: then only addresses on the list and the sender addressnative-form-handler.php
Required fields can be bypassed“required” is checked only by the browseradditionally honeypot and IP limit; do not rely on required as a security featureRequired fields
The security question can be bypassedthe server checks it only if the answer or token is sent alongadditionally honeypot and IP limitMath security question
File upload failsbrowser limit 3 MB, server limit 8 MB; upload_max_filesize or post_max_size too smallcheck the server values; with the Form Renderer maxFileSizeMBFile uploads
The Form Renderer shows nothing when the page is opened by double-clickrender.js loads the form JSON via fetchopen the page from a server or from the previewHow it works together
A rule makes a field always visiblea condition group without conditions counts as fulfilledremove empty groupsRules
Google Font or hCaptcha load without consentdata-customfont and hcaptcha embed third-party services, the cookie consent does not block themleave customFont empty; mention them in the privacy policyThe Form Renderer block, hCaptcha (Form Renderer only)
config.php shows the SMTP passwordthe file contains it in plain textdeliver only through PHP, use a separate mailbox for sendingconfig.php (assets/vn-shared)

Media, privacy and publishing#

SymptomCauseSolutionDetails
YouTube/Vimeo background video, with cookie consent switched on, loads only after a click on “Marketing”from version 1.3.100 vendor/vn-bgvideo waits for consent to “Marketing” (the fallback image stays); without cookie consent on the page it loads immediatelyintended; for backgrounds without consent use your own video filePlayback on the page, Event vn-cc-consent
A custom provider iframe or a script loads immediately despite cookie consentonly known providers (Google Maps, YouTube, Vimeo from 1.3.100, Google Analytics/Tag Manager, Facebook) are blocked automaticallyset data-vn-consent-category="functional|statistics|marketing"Automatic blocking, Privacy
The background video takes the YouTube address although a file is chosenthe template always sets data-bg-video from videoUrldo not enter bothThe “Video background” block (vn-bgvid)
The block creates its own third-party connections (CDN, web fonts)everything third-party must be shipped with the blockfiles in the package, no CDNShipped libraries, Privacy
The VN Translator translates a word anywaytranslate="no" is not respectedclass notranslateMarking exceptions
PHP in the block does not runthe page is named .html; the program does not rename it, it only reportsset the page to .phpPages and file names
Export aborts with “Invalid file name”page name does not match ^[a-z0-9_-]+\.(html|php)$only lowercase letters, digits, _, -Pages and file names
The server still has old filesthe program deletes nothing on the serverremove files you no longer need yourselfPublishing via FTP
In the preview no mail goes outmails go as .eml files to a local mail catchertest in the real export and on the serverPreview and export

Extensions#

SymptomCauseSolutionDetails
An update appears as a second toolthe id was changednever change the idmanifest.json
After a change the old code still runsthe program keeps imported modules until restart; only tool.js gets the modification time as ?v=increment ?v= on imported files, raise version, restart the programLifecycle
ctx.project… is undefinedolder program versioncheck entries before using themThe interface ctx
“Invalid file in the export contribution”path not under assets/<own id>/…, too long or file too largekeep to the paths and limits (30 files, 400000 characters)ctx.project.exportContribution
A password with $ arrives wrongly in PHPbefore version 1.3.100 {{secret-php:NAME}} does not mask the $; from version 1.3.100 it does (only in PHP strings with double quotes)put the placeholder in "…"; for older versions use values without $ctx.project.secrets
The editor behaves strangely after the extension changed page objectsctx.getPages() returns working objects, not copiesread only, make changes via ctx.project/ctx.blocksThe interface ctx, Security rules
The extension's data/ directory can be retrievedthe program writes no .htaccess for contributionsthe PHP code creates the protection itselfPHP server parts
The gallery shows no preview image of the extensionthe preview is only found in the packagethumbnail.jpg in the packageBuild, test, deliver
A file stays on the server after the contribution is removedthe program deletes nothing on the serverremove it yourselfctx.project.exportContribution