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.
| Part | File | Purpose |
|---|---|---|
| Markup and input fields | template.html | HTML of the block, plus the fields that the properties panel shows |
| Style | style.less | LESS (or CSS) with the values of the fields as variables |
| Preview | thumb.png | Image 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.
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#
| Term | Meaning |
|---|---|
| Block | One 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) |
| Package | A ZIP file .vndext with one or more building blocks, params.json and shared files |
| Theme | A package with many matching building blocks (menu to footer) and shared theme CSS |
| Extension | A 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 |
| Alias | The technical name of a building block (alias in params.json); it determines the CSS class of the instances |
| Root | The first element of template.html; it carries the instance class |
| Instance | A 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:
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 geladentemplate.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):
meine-bloecke/
params.json
components/
hinweiskarte/
template.html
style.lessparams.json
{
"name": "Meine Blöcke",
"alias": "meine-bloecke",
"components": [
{ "path": "components/hinweiskarte", "_group": "Hinweise", "_title": "Hinweiskarte" }
]
}components/hinweiskarte/template.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
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:
cd meine-bloecke
& "$env:SystemRoot\System32\tar.exe" -a -c -f ..\meine-bloecke.zip params.json components
Rename-Item ..\meine-bloecke.zip meine-bloecke.vndextWith Python (platform independent, this is also how the program's theme scripts pack):
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#
- Open a project (the import places images in the project folder).
- Click + Add block and choose the tab File (.vndext). Choose the file or drag it in.
- 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.htmlandstyle.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
</> Codein 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
.vndextfile or with ★ as a user block.
Common stumbling blocks#
All these points are documented in detail in the chapters. Here is the short version:
| Symptom | Cause | Chapter |
|---|---|---|
| Import reports "not valid JSON" or "template.html not found" | BOM in params.json; backslashes in the ZIP | above, Packages |
| Block without any CSS, label "⚠ CSS error" | Error in the LESS: unknown variable (@bg-… without a background widget), umlaut in a field name, BOM | LESS |
{{…}} yields empty text everywhere, vn-if hides nothing | a field name is invalid in JavaScript (hyphen, digit at the start, reserved word) | Names |
An element stays despite vn-if | vn-if removes only on exactly false; an empty text or a typo in the name leaves it in place | vn-if |
{{beschriftung}} appears literally in the button | In <a class="btn"> placeholders are not evaluated | Placeholders in buttons |
n + 1 yields 41 | Values of sliders are text | range |
| Block looks different in the editor than in the export | !important against Bootstrap/theme CSS; layers exist only in the editor | Precedence |
| Rule in the theme CSS has no effect in the editor | #canvas, body, html, :root inside @scope; correct: :scope | The #canvas trap |
| Background image missing after the import | Default file:///… pointing to the author's computer; correct: ../_images/… | image |
Chapter overview#
| Chapter | Content |
|---|---|
| Overview and first block | this chapter |
| The template | root 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 markers | vn-if, vn-class, vn-style, vn-overlay, vn-video and more; older notations |
| Block styles | style.less: variables, scope, precedence of editor and export, traps |
| Directly editable content | text, images, icons, buttons, menus, links, CMS, popup |
| Scripts in blocks and themes | JavaScript in the block, editor detection, cookie consent, bundled libraries |
| Forms | static form vn-sform, PHP sending, spam protection, VN Form Editor |
| Backgrounds, media and tool blocks | background and video, lightbox, gallery, PDF viewer, search, blog, animations, translator |
| Packages and themes | .vndext, params.json, import, theme CSS, themes folder |
| Builder and user blocks | blocks from rows, columns and elements, user blocks |
| Extensions | tool extensions .vndtool, manifest.json, program interface ctx |
| Export and publishing | what the export writes, preview, FTP upload, privacy rules |
| Pitfalls and checklist | checklists before publishing, table of all pitfalls with cause and solution |
| Quick reference | tables of all input types, directives, placeholders, package files, ctx functions and libraries |