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
camelCasemade 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 gridmin + 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 withNumber(n)(vn-if, Expressions). - ☐ Use the word
overlayonly 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-facea 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 withe()or~"@{…}"; no BOM, no@import, nodefault()(Checklist). - ☐ No
body,htmlor:rootin 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
!importantonly selectively (buttons, links) and cross-check it afterwards in the live preview (F5): in the editor it loses against!importantfrom 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
- ☐ Buttons as
<a class="btn">with fixed text and target; no placeholders in buttons (Placeholders in buttons, a.btn). - ☐ Panel values and freely editable text sit in different elements (Placeholders in text).
- ☐ Background images via an image field, a background widget or an inline style, not only in the LESS (Background image in the inline style).
- ☐ Never change or delete identifiers (
data-vn-text-id…) by hand (Overview).
Scripts
- ☐ Init flag as a JavaScript property on the element, not as a
data-attribute (One-time initialization). - ☐ Detect the editor only with
el.closest('#canvas'); set the parameter-dependent initial state before returning (Detection with el.closest('#canvas'), Rules for scripts in the editor). - ☐ Never rewrite the text of text fields (
data-vn-text-id); text effects only at runtime (Text animations at runtime). - ☐ Access
bootstrap,vnCookieConsent,VNPopuponly afterDOMContentLoaded; no jQuery (Order and waiting, jQuery and theme plugins (Bootstrap theme mode)). - ☐ Respect “reduced motion” (Reduced motion).
Forms, media, privacy
- ☐ Forms with
form.vn-sform-formanddata-mailer, never as mere decoration (Example: contact form in a theme). - ☐ Load nothing from third parties (CDN, web fonts, scripts); build embeds so that the cookie consent can block them (Privacy, Automatic blocking).
- ☐ Background video: do not enter a file and an address; for backgrounds without consent use your own video file (The “Video background” block (vn-bgvid), Playback on the page).
- ☐ Test in the real export: open
publish/index.html, console without errors, network tab without requests to foreign servers (What authors can influence).
Theme or package#
- ☐ Files as UTF-8 without BOM; ZIP with forward slashes (built-in
tar.exeor Python, notCompress-Archiveof Windows PowerShell 5.1) (2. Pack it as a package). - ☐
params.json:name, uniquealiasandtitle,componentswithpath,_group,_title(params.json). - ☐ Images in
components/_images/and referenced as../_images/<file>; no videos, noavif(components/_images, Images and file names). - ☐ Menu and footer with
global once="menu"andglobal once="footers"on the very first element (Site-wide blocks: global and once, global). - ☐
thumb.pngper block,thumbnail.jpgin the package for the gallery (thumb.png, thumbnail.jpg and the gallery preview). - ☐ Theme CSS without
@scopeand@layer; use:scopeinstead of:rootfor the top level; fonts as a file in the package (In the editor: layer and scope, The #canvas trap in the theme CSS, Fonts and images in the theme CSS). - ☐ The theme CSS cannot be renewed in a project after the first import: check it thoroughly, change
titleonly deliberately (Only once per project). - ☐ Own class prefix per theme so that mixed themes do not overwrite each other (Bootstrap and classes).
- ☐ Import the package in a new project, insert every block, export (Checklist before passing it on).
- ☐ Sample texts without real names, addresses only
example.com.
Extension#
- ☐
manifest.json: valididthat you never change; raiseversionwith 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, protectdata/yourself, validate input, escape output (PHP server parts). - ☐ No foreign servers, no
eval, noinnerHTMLwith raw data (Security rules). - ☐ Set the contribution to
nulland export again: the files must disappear (Build, test, deliver). - ☐
thumbnail.jpgin 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#
| Symptom | Cause | Solution | Details |
|---|---|---|---|
| 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 BOM | 1. Create the folder and files, Errors in the LESS |
| Package is rejected | components is missing or empty; appScript without components; params.json is missing | components with at least one entry | params.json |
| Background or field image is missing after the import | default file:///… points to the author's computer | images in components/_images/, default ../_images/<file> | image, Images and file names |
Video or avif is missing in the package | from _images only jpg, jpeg, png, gif, svg, webp are extracted | do not put videos in the package; the user chooses a file or address in the “Video” field | components/_images |
script.js next to the block has no effect | the import reads only template.html, style.less/style.css, thumb.png | JavaScript as <script> in template.html | No script file per block |
| Importing again creates another entry; a block on the page does not change | every import is a new entry; existing blocks keep their stored template | insert the block again; use the code editor for testing | 5. Keep working |
| Theme CSS is not updated on re-import | the identifier vn-theme-css-<title> already exists in the project: nothing is reloaded; packages with the same title share one theme CSS | check the theme CSS before the first import; in a new project the new CSS applies | Only once per project |
| Colors or buttons of two themes collide | theme CSS and Bootstrap classes act on the whole page, not just in the block; identical class names | own classes with a prefix per theme; unique title | Bootstrap 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 project | choose group names deliberately (menu, footers or your own name) | once, Site-wide blocks: global and once |
global is not recognized; once has no effect | global 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 effect | global and once on the root element | global |
| Block shows no preview image | thumb.png is missing; the gallery reads thumbnail.jpg, the program does not | thumb.png per block, thumbnail.jpg for the package | thumb.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 extracted | video via address (YouTube/Vimeo) or file selection in the block | Export as .vndext |
| Adjustments are missing in the exported user block | ⇩ (“Export as .vndext file”) takes the stored template unchanged | use ⤓ in the properties panel | Export as .vndext |
| The code button of a builder block is locked | the builder and the free surface are only rebuilt via “+” and the panel | build the block in the “Custom code” tab or use the builder | Relationship to the code editor |
Template and input fields#
| Symptom | Cause | Solution | Details |
|---|---|---|---|
| The CSS does not reach a second top-level element | only the first element gets the instance class | wrap everything in one root element | The root element |
| A field does not appear in the panel | the field is not a direct child of <vn-parameters>, has no name or sits in a second parameter block | direct child, set name, only one block | Overview |
{{…}} yields empty text everywhere; vn-if hides nothing | a field name is not a valid identifier in JavaScript (hyphen, dot, digit at the start, reserved word) | camelCase made of letters and digits | name |
| Block shows “⚠ CSS error” | a field name with an umlaut or $ breaks the LESS | name without umlaut and $ | name |
{{n + 1}} yields 41 instead of 5 | the values of sliders are text | Number(n) + 1, n * 1 | range |
| The slider shows a different value than the LESS sees | the default is not on the grid min + n × step; the default stays stored | put defaults on the grid | range |
| The panel shows black instead of the default color | color is not six digits (#fff, white) | #rrggbb | color |
A field stays visible despite condition | it 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 field | write a comparison or !!name; coordinate the markup with vn-if yourself | condition |
An element stays despite vn-if | vn-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-if | vn-if, vn-strict-if |
vn-class with a computed name does nothing | a key such as {'n-' + mode: true} is a syntax error | text form vn-class="'n-' + mode" | vn-class |
vn-style does not set --variable | custom properties are discarded | style="--k:{{k}}" or a variable in the LESS on the root | vn-style |
Darkening (vn-overlay) lies over text or page header | the layer fills the nearest positioned parent element | root position: relative, content position: relative; z-index: 1 | vn-overlay |
| Overlay fields appear unintentionally | the word overlay appears in the template (also as a class or comment) and no field overlay of your own is declared | declare your own fields or avoid the word | Automatic overlay fields |
| A text from the panel breaks the markup or is inserted as HTML | {{name}} inserts the value unmasked as HTML | in attributes {{vnEnc(name)}}, otherwise only in text content | {{name}}, vnEnc(text) |
{{ or }} in the script yields nonsense or empty text | every {{ … }} in the template is evaluated as an expression, also in the script | brackets with a space ({ {) or on separate lines | Placeholders in scripts and attributes |
{{beschriftung}} appears literally in the button | in <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 btn | Placeholders in buttons, Placeholders in buttons |
| A changed default in the package has no effect in existing blocks | the values are stored in the block | insert the block again | Default values |
| Two fields behave like one | the same name shares one value | unique names | name |
Style, LESS and CSS#
| Symptom | Cause | Solution | Details |
|---|---|---|---|
| Block without any CSS, label “⚠ CSS error” | error in the LESS: @bg-type without a background widget, unknown variable, @import, when (default()), open block | read the message in the tooltip; fix the cause | Errors in the LESS, Background variables |
url(@bg-value) yields url(#f3f4f6) | with a color, @bg-value is a color | always inside when (@bg-type = 'image') | Background variables |
Selector .'grid'-x is invalid; aspect-ratio: '16/9' is discarded | selection and text values arrive as LESS text with quotation marks | e(@x) or ~"@{x}" | Outputting values as text in CSS |
when (@text = abc) is never true | always compare texts in quotation marks; number against text (= "2") is never true | @x = 'abc', numbers without quotation marks | Comparisons and conditions |
| Division gives a wrong result | 10px / 2 from literals is not rewritten | parentheses: (10px / 2), (@n / 2) | Calculating |
body, html, :root in the block LESS do nothing | they 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 globally | prefix in the name | Scope and root |
p { font-size: 3rem; } in the block has no effect | the site's body text font size sets font-size on p, li … with !important | put sizes on div/span or set !important | Site settings that override your CSS |
| The block looks different in the editor than in the export | layer 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 editor | check in the live preview (F5) or in the export; !important only selectively | Who 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 editor | in the editor the width of the program window applies | live preview with tablet/phone | The #canvas trap in the theme CSS |
| Button or link color from the block LESS does not prevail | theme CSS with higher specificity or the font rules of the site win | !important for colors, borders, font of buttons and links; check in the export | Buttons 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 click | images only in the LESS cannot be assigned | image field, background widget or inline style | Background image in the inline style |
@primaryColor etc. is “undefined” | theme variables are missing without a theme | params.theme.settings or your own fields | Theme variables, Theme properties (params.theme) |
| Parallax has no effect on the phone | background-attachment: fixed | plan the image so that it also looks good without the effect | Parallax |
Editable content#
| Symptom | Cause | Solution | Details |
|---|---|---|---|
| Edits end up on the wrong element | identifiers (t3, btn0 …) are position numbers from the import; a template changed afterwards or identifiers deleted by hand shift them | never change identifiers by hand; add an element at the end instead of in between | Overview |
A clickable card (<a class="card">) becomes a single text field | a bare link is the field, its children do not count | card as a div with its own link or button | Which elements become text fields |
Labels in the <form> are not clickable | nothing inside form is captured as a text field | change field texts in the code editor | Which elements become text fields |
<button class="btn"> cannot be edited | only <a class="btn"> is a button | <a class="btn" role="button"> | a.btn |
| A custom attribute in the text disappears on the next save | the text sanitizer lets only an allowlist through | build the element outside text fields | Allowed attributes and classes |
| A panel placeholder disappears after the text is edited | a text field with a placeholder is replaced completely when edited | panel value and free text in separate elements | Placeholders in text |
| The hamburger color has no effect | the block uses its own icon instead of .navbar-toggler-icon | use .navbar-toggler-icon | Hamburger icon |
| Text color and effects are missing on the finished page (CMS) | in CMS text style is removed | classes in the block CSS | Operation and security on the page |
| CMS block changes nothing | page is named .html or no password is set | page .php, set the password in the program | Enabling |
| Image handles do not fit | image without a reliably determinable container (inline, position:absolute) | background widget for filling images | Scaling images with the mouse |
| The icon cannot be changed | an SVG, <img> or a CSS mask is not a changeable icon | <i class="bi bi-…"> or data-vn-icon | Preventing or excluding icons |
Scripts#
| Symptom | Cause | Solution | Details |
|---|---|---|---|
| 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 state | set the initial state, then return | Rules for scripts in the editor |
| The content of a block is missing or not clickable | the script hides or moves DOM (opacity:0, reveal, carousel rebuild) in the editor too | hide or move nothing in the editor | Rules for scripts in the editor |
| The text of a text field is “destroyed” after typing | the script rewrites the content of a data-vn-text-id element (letter spans); the intermediate state is saved while typing | split text only at runtime outside #canvas; the template holds the plain text | Text animations at runtime, Rules for scripts in the editor |
| New blocks are never initialized | the init flag is a data- attribute and an old script has marked elements of new blocks with it | flag as a JavaScript property (box.vnInit = 1) | One-time initialization |
| After the first redraw in the editor the script never starts again | a guard on window (window.fertig) is discarded with every render, on the real page it stays | flag on the element | window properties apply for one pass only |
| The second instance of a block is broken | fixed IDs or global state | classes, {{vn-id}}, namespace | One-time initialization |
is-builder or currentScript does not detect the editor | the program never sets is-builder; currentScript is null; there is no iframe | el.closest('#canvas'); fall back to document.querySelector(…) | What is not suitable for detection |
bootstrap, vnCookieConsent, VNPopup are undefined | the block script runs during parsing, before Bootstrap and the VN libraries | wait for DOMContentLoaded | Order and waiting |
$ or jQuery is undefined | jQuery exists only in Bootstrap theme mode | plain JavaScript | jQuery and theme plugins (Bootstrap theme mode) |
import in <script type="module"> fails in the editor | the editor runs scripts in new Function | classic script | Pitfalls: script runs in the editor and destroys content |
window.vnEnc is undefined | vnEnc, vnEmbed and {{vn-id}} are helpers of the template expression, not global functions | in the template data-x="{{vnEnc(x)}}", in the script decodeURIComponent | Text data in attributes: vnEnc |
A text in a stand-in (data-vn-editor-only) can be edited in the editor | in the editor the stand-in is an ordinary element | create it without body text or allow for it | Marker data-vn-editor-only |
Forms#
| Symptom | Cause | Solution | Details |
|---|---|---|---|
| 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 missing | form.vn-sform-form with data-mailer, set up SMTP in the program | Example: contact form in a theme, SMTP settings in the program |
Several recipients in data-recipient do not work | mailer.php accepts exactly one address per form | forwarding in the mailbox or several forms | Recipients |
| “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 it | Recipients |
A custom HTML form via native-form-handler.php sends to any address | without recipients.php (export with a version before 1.3.100) there is no recipient list | from version 1.3.100 export again and upload: then only addresses on the list and the sender address | native-form-handler.php |
| Required fields can be bypassed | “required” is checked only by the browser | additionally honeypot and IP limit; do not rely on required as a security feature | Required fields |
| The security question can be bypassed | the server checks it only if the answer or token is sent along | additionally honeypot and IP limit | Math security question |
| File upload fails | browser limit 3 MB, server limit 8 MB; upload_max_filesize or post_max_size too small | check the server values; with the Form Renderer maxFileSizeMB | File uploads |
| The Form Renderer shows nothing when the page is opened by double-click | render.js loads the form JSON via fetch | open the page from a server or from the preview | How it works together |
| A rule makes a field always visible | a condition group without conditions counts as fulfilled | remove empty groups | Rules |
| Google Font or hCaptcha load without consent | data-customfont and hcaptcha embed third-party services, the cookie consent does not block them | leave customFont empty; mention them in the privacy policy | The Form Renderer block, hCaptcha (Form Renderer only) |
config.php shows the SMTP password | the file contains it in plain text | deliver only through PHP, use a separate mailbox for sending | config.php (assets/vn-shared) |
Media, privacy and publishing#
| Symptom | Cause | Solution | Details |
|---|---|---|---|
| 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 immediately | intended; for backgrounds without consent use your own video file | Playback on the page, Event vn-cc-consent |
| A custom provider iframe or a script loads immediately despite cookie consent | only known providers (Google Maps, YouTube, Vimeo from 1.3.100, Google Analytics/Tag Manager, Facebook) are blocked automatically | set data-vn-consent-category="functional|statistics|marketing" | Automatic blocking, Privacy |
| The background video takes the YouTube address although a file is chosen | the template always sets data-bg-video from videoUrl | do not enter both | The “Video background” block (vn-bgvid) |
| The block creates its own third-party connections (CDN, web fonts) | everything third-party must be shipped with the block | files in the package, no CDN | Shipped libraries, Privacy |
| The VN Translator translates a word anyway | translate="no" is not respected | class notranslate | Marking exceptions |
| PHP in the block does not run | the page is named .html; the program does not rename it, it only reports | set the page to .php | Pages 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 files | the program deletes nothing on the server | remove files you no longer need yourself | Publishing via FTP |
| In the preview no mail goes out | mails go as .eml files to a local mail catcher | test in the real export and on the server | Preview and export |
Extensions#
| Symptom | Cause | Solution | Details |
|---|---|---|---|
| An update appears as a second tool | the id was changed | never change the id | manifest.json |
| After a change the old code still runs | the program keeps imported modules until restart; only tool.js gets the modification time as ?v= | increment ?v= on imported files, raise version, restart the program | Lifecycle |
ctx.project… is undefined | older program version | check entries before using them | The interface ctx |
| “Invalid file in the export contribution” | path not under assets/<own id>/…, too long or file too large | keep to the paths and limits (30 files, 400000 characters) | ctx.project.exportContribution |
A password with $ arrives wrongly in PHP | before 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 objects | ctx.getPages() returns working objects, not copies | read only, make changes via ctx.project/ctx.blocks | The interface ctx, Security rules |
The extension's data/ directory can be retrieved | the program writes no .htaccess for contributions | the PHP code creates the protection itself | PHP server parts |
| The gallery shows no preview image of the extension | the preview is only found in the package | thumbnail.jpg in the package | Build, test, deliver |
| A file stays on the server after the contribution is removed | the program deletes nothing on the server | remove it yourself | ctx.project.exportContribution |