VN-Designer Developer Documentation
01

Overview and first block

What a block is, how a block folder is structured, a first block of your own in ten minutes (folder, package, import, test), the most important terms and an overview of all chapters.

What is a block?#

A website in VN-Designer consists of blocks that stand one below the other on a page: menu, header area, text block, gallery, form, footer. Every block arises from a building block (Baustein): a reusable description made of three parts.

PartFilePurpose
Markup and input fieldstemplate.htmlHTML of the block, plus the fields that the properties panel shows
Stylestyle.lessLESS (or CSS) with the values of the fields as variables
Previewthumb.pngImage for the selection (optional)

A user inserts a building block, changes texts and images directly on the canvas and sets colors, spacing and switches in the properties panel. On export this becomes plain HTML and CSS, without a runtime library.

text
Paket (.vndext)  →  Import  →  Baustein (Vorlage + LESS + Felder)
                                      │ einfügen
                                      ▼
                       Block auf der Seite (gespeicherte Werte)
                                      │ zeichnen: {{…}} und Direktiven auswerten, LESS übersetzen
                         ┌────────────┴────────────┐
                         ▼                         ▼
                  Editor (bearbeitbar)     Export (HTML + style.css)

Terms#

TermMeaning
BlockOne instance on a page, with its own values and its own text changes
Building block (component, "Baustein")The reusable template from which blocks arise (template.html, style.less, thumb.png)
PackageA ZIP file .vndext with one or more building blocks, params.json and shared files
ThemeA package with many matching building blocks (menu to footer) and shared theme CSS
ExtensionA tool .vndtool for the program itself (checks, assistants, server files). It can bring building blocks along, but it is something different from a package
Properties (fields, parameters)The input fields in the properties panel; every field has a name and a value
AliasThe technical name of a building block (alias in params.json); it determines the CSS class of the instances
RootThe first element of template.html; it carries the instance class
InstanceA single block on a page; two blocks of the same building block are two instances with classes of their own

Structure of a block folder#

This is how the folder of a package with one building block looks:

text
meine-bloecke/
  params.json                  Name, Alias und Liste der Bausteine
  components/
    hinweiskarte/
      template.html            Pflicht: Markup und <vn-parameters>
      style.less               optional: Stil (LESS oder CSS)
      thumb.png                optional: Vorschau in der Auswahl
    _images/                   optional: gemeinsame Bilder, Verweis ../_images/<datei>
  plugins/theme/css/style.css  optional: Theme-CSS, einmal pro Projekt geladen

template.html#

Markup of a block: one root element, inside it the block <vn-parameters>, then content with placeholders and directives. See The template.

style.less#

Style of the block. Every field is available as the LESS variable @name. See Block styles.

thumb.png#

Preview image of the building block for the selection and the library. If it is missing, the selection shows a placeholder icon. See Packages.

params.json#

Describes the package: name, alias and components with path, _group (category) and _title (display name). See Packages.

components/_images#

Shared image folder. References in template and LESS read ../_images/<file>; the import places the files in the project. See Packages.

First block of your own in 10 minutes#

The example builds a notice card with spacing, an accent color and a switch for the additional text. You need VN-Designer with an open project and a text editor that saves files as UTF-8 without BOM.

1. Create the folder and files#

Create this structure (folder names are free, the paths in params.json must match):

text
meine-bloecke/
  params.json
  components/
    hinweiskarte/
      template.html
      style.less

params.json

json
{
  "name": "Meine Blöcke",
  "alias": "meine-bloecke",
  "components": [
    { "path": "components/hinweiskarte", "_group": "Hinweise", "_title": "Hinweiskarte" }
  ]
}

components/hinweiskarte/template.html

html
<section class="mb-karte">
  <vn-parameters>
    <header>Größe</header>
    <input type="range" title="Abstand oben und unten" name="abstand" min="0" max="8" step="1" value="3">
    <header>Anzeigen</header>
    <input type="checkbox" title="Zusatztext" name="showText" checked>
    <header>Farben</header>
    <input type="color" title="Hintergrund der Karte" name="kartenFarbe" value="#eef2ff">
    <input type="color" title="Akzentfarbe" name="akzent" value="#4f46e5">
  </vn-parameters>
  <div class="container">
    <div class="mb-karte-box">
      <h2>Willkommen</h2>
      <p vn-if="showText">Dieser Block ist in zehn Minuten entstanden. Texte ändern Sie direkt im Editor.</p>
      <a class="btn btn-primary" href="#">Mehr erfahren</a>
    </div>
  </div>
</section>

components/hinweiskarte/style.less

less
padding-top: (@abstand * 1rem);
padding-bottom: (@abstand * 1rem);

.mb-karte-box {
  background: @kartenFarbe;
  border-left: 6px solid @akzent;
  border-radius: 0.75rem;
  padding: 2rem;
}
.mb-karte-box h2 { color: @akzent; }
.mb-karte-box .btn-primary {
  background-color: @akzent !important;
  border-color: @akzent !important;
  color: #fff !important;
}

What happens here: The lines without a selector (padding-top …) apply to the root <section>; @abstand, @kartenFarbe and @akzent are the fields from <vn-parameters>; vn-if="showText" removes the paragraph when the switch is off.

2. Pack it as a package#

A package is a ZIP file with the extension .vndext. The paths inside the ZIP must be written with forward slashes (components/hinweiskarte/template.html).

Windows 10/11 (built-in tar), in a PowerShell:

text
cd meine-bloecke
& "$env:SystemRoot\System32\tar.exe" -a -c -f ..\meine-bloecke.zip params.json components
Rename-Item ..\meine-bloecke.zip meine-bloecke.vndext

With Python (platform independent, this is also how the program's theme scripts pack):

python
import os, zipfile
src = 'meine-bloecke'
with zipfile.ZipFile('meine-bloecke.vndext', 'w', zipfile.ZIP_DEFLATED) as z:
    for root, _, files in os.walk(src):
        for name in files:
            full = os.path.join(root, name)
            z.write(full, os.path.relpath(full, src).replace(os.sep, '/'))

3. Import#

  1. Open a project (the import places images in the project folder).
  2. Click + Add block and choose the tab File (.vndext). Choose the file or drag it in.
  3. By default the building block "Hinweiskarte" lands only in the library (tab "Library", switch below the drop area: "Add to the library only") and can be placed on the page from there. Turn the switch on (it is then called "Insert directly into project") and the building block goes onto the page right away.

A package with several building blocks shows a selection with the preview images.

4. Test#

  • Properties panel: The block has the groups "Größe", "Anzeigen" and "Farben". Move the slider, switch the additional text off and change the colors: the block is redrawn on every change.
  • Edit directly: Click in "Willkommen" and type. Click the button: the button dialog opens. Both happen automatically, without the template doing anything for it.
  • Errors in the LESS: If the block shows the red label "⚠ CSS error", the message is in the tooltip.
  • Live preview: With F5 the program shows the finished page as in the export, with buttons for tablet (820 px) and phone (390 px). Check media queries there.
  • Export: The "Export" button writes the folder with index.html and style.css. The result has no editor traces.

5. Keep working#

  • Change the files in the folder, pack again and import again. The library replaces nothing: every import creates another entry.
  • A block that is already on a page keeps its stored template: the program never changes existing projects through a package update. Insert the building block again for testing.
  • Faster: Open the block with the button </> Code in the properties panel, change template or LESS and confirm with ✓ Apply. This changes only this block. Afterwards carry the changes over into your files.
  • Get used to putting a package into a themes folder (tab "Themes", choose themes folder): there it appears as a catalog every time you open the dialog.
  • A block you have built in the editor you save with ⤓ directly as a .vndext file or with ★ as a user block.

Common stumbling blocks#

All these points are documented in detail in the chapters. Here is the short version:

SymptomCauseChapter
Import reports "not valid JSON" or "template.html not found"BOM in params.json; backslashes in the ZIPabove, Packages
Block without any CSS, label "⚠ CSS error"Error in the LESS: unknown variable (@bg-… without a background widget), umlaut in a field name, BOMLESS
{{…}} yields empty text everywhere, vn-if hides nothinga field name is invalid in JavaScript (hyphen, digit at the start, reserved word)Names
An element stays despite vn-ifvn-if removes only on exactly false; an empty text or a typo in the name leaves it in placevn-if
{{beschriftung}} appears literally in the buttonIn <a class="btn"> placeholders are not evaluatedPlaceholders in buttons
n + 1 yields 41Values of sliders are textrange
Block looks different in the editor than in the export!important against Bootstrap/theme CSS; layers exist only in the editorPrecedence
Rule in the theme CSS has no effect in the editor#canvas, body, html, :root inside @scope; correct: :scopeThe #canvas trap
Background image missing after the importDefault file:///… pointing to the author's computer; correct: ../_images/…image

Chapter overview#

ChapterContent
Overview and first blockthis chapter
The templateroot element, root attributes, placeholders, images and links, Bootstrap, editor and export
Input fields<vn-parameters>: all input types, background widget, condition, default values, example
Directives and markersvn-if, vn-class, vn-style, vn-overlay, vn-video and more; older notations
Block stylesstyle.less: variables, scope, precedence of editor and export, traps
Directly editable contenttext, images, icons, buttons, menus, links, CMS, popup
Scripts in blocks and themesJavaScript in the block, editor detection, cookie consent, bundled libraries
Formsstatic form vn-sform, PHP sending, spam protection, VN Form Editor
Backgrounds, media and tool blocksbackground and video, lightbox, gallery, PDF viewer, search, blog, animations, translator
Packages and themes.vndext, params.json, import, theme CSS, themes folder
Builder and user blocksblocks from rows, columns and elements, user blocks
Extensionstool extensions .vndtool, manifest.json, program interface ctx
Export and publishingwhat the export writes, preview, FTP upload, privacy rules
Pitfalls and checklistchecklists before publishing, table of all pitfalls with cause and solution
Quick referencetables of all input types, directives, placeholders, package files, ctx functions and libraries