Builder and user blocks
How the block builder turns rows, columns and elements into a template and LESS, which data model is stored, how user blocks and .vndext files are made from your own blocks, and how this relates to the code editor.
Overview#
The builder (tab “Builder” in “Add block”) assembles a block from rows, columns and elements. It is not a separate rendering mechanism: on every change the program generates an ordinary template (<vn-parameters> plus markup) and a LESS file from a small tree. The block then runs through the same pipeline as any imported block (fields, default values, marking of texts, buttons, icons and images).
Three related ways to get a block of your own:
| Way | Result | Stays editable |
|---|---|---|
| Builder | Block with a structure tree (schemaEntry.builder), alias vn-baukasten | yes, with the “+” buttons in the block and the “Structure” section in the Properties panel |
| Free surface | Block with an element tree (schemaEntry.freeSurface), alias vn-frei | yes, with the mouse on the surface |
| Custom code | Block custom-html / custom-php with raw code | only through the code editor |
The stored data model#
A builder block is an ordinary block in the project (projekt.vnd). In addition, its schemaEntry carries two fields:
| Field | Content |
|---|---|
builder | The tree: { "v": 1, "next": 17, "rows": [ … ] }. next is the counter for new identifiers. A row (r…) has id, d (defaults) and cols; a column (c…) has id, d and items; an element (e…) has id, type and d |
bkGroups | Order of the property groups: ["block", "r1", "c2", "e3", …] |
d contains only the defaults for newly created nodes. All settings are stored in block.values, as with every block, under the key <identifier>_<property>, e.g. e3_width, c2_span, r1_perRow. The remaining fields of schemaEntry (templateHtml, lessText, fields, defaults, wrapperClass, buttonDefaults, iconDefaults) are the finished generated result.
Example (layout “Cards — any number”, from a saved project, shortened)
{
"alias": "vn-baukasten",
"schemaEntry": {
"label": "Baukasten",
"builder": {
"v": 1, "next": 17,
"rows": [
{ "id": "r1", "d": { "gap": 4, "valign": "stretch", "perRow": 3, "mb": 4 },
"cols": [
{ "id": "c2", "d": { "span": 4, "hasBg": true, "shadow": true, "pad": 2, "radius": 14 },
"items": [
{ "id": "e3", "type": "image", "d": { "ratio": "3 / 2", "radius": 8 } },
{ "id": "e4", "type": "heading", "d": { "size": 1.35 } },
{ "id": "e5", "type": "text", "d": { "size": 0.95 } },
{ "id": "e6", "type": "button", "d": {} }
] }
] }
]
},
"bkGroups": ["block", "r1", "c2", "e3", "e4", "e5", "e6"]
},
"values": { "width": "container", "paddingTop": "4", "bg": { "type": "color", "value": "#f3f4f6", "parallax": false }, "r1_perRow": "3", "r1_gap": "4" }
}What happens when you rebuild#
Every structural change (adding, moving, copying or deleting a row, column or element) goes through the same function: it changes the tree, regenerates the template, LESS and fields, and then carries the state over:
- Values: For every key of the new field list, the previous value applies, otherwise the default. Values whose name begins with
_(assigned by the program, such as the text sliders) are always kept. Values of deleted nodes are dropped. - Copies: A copied node gets new identifiers and the values of the original.
- Edits: Texts carry fixed identifiers (
data-vn-text-id="t<number of the identifier × 100 + k>"), images are tied to their field (e3_src). Buttons and icons number the standard tools consecutively; the program therefore converts their edits (buttonOverrides,iconOverrides) per element. Alt texts, titles, sizes and links of the images are tied to the field name.
Limits: at most 6 columns side by side in a normal row, at most 24 in a grid row (see below); list at most 12 entries; image slider at most 20 slides. The description of the “Image slider” layout says “up to 12”; the code allows 20.
The block#
Every builder block first has the “Block” group with these properties:
| Key | Type | Default | Meaning |
|---|---|---|---|
width | Choice | container | Content width: container (1140 px), narrow (760 px), full (full width) |
minHeight | Range 0–100, step 5 | 0 | Height as a percentage of the screen height; 0 = as tall as the content. A value above 0 sets a fixed height (vh) with the overflow cut off, so a background does not grow while you type |
vAlign | Choice | center | Vertical position of the content (only with minHeight > 0) |
paddingTop, paddingBottom | Range 0–14, step 0.5 | 4 | Spacing top/bottom in rem |
textColor | Color | #4b5563 | Text color of the block |
headColor | Color | #111827 | Color of the headings |
bg | Background | Color #ffffff | see Background |
bgPoster | Image | empty | Preview image while the video loads (only with a video background) |
overlay, overlayColor, overlayOpacity | Switch, color, range 0–1 | off, #000000, 0.5 | Darkening over the background image or video |
The basic structure of the generated markup:
<section class="vn-bk" data-bg-video="{{bg.type == 'video' && bg.value.url}}">
<vn-parameters> … </vn-parameters>
<div class="mbr-fallback-image" vn-if="bg.type == 'video'" style="background-image:url('{{bgPoster}}')"></div>
<div class="vn-overlay" vn-if="overlay && bg.type !== 'color'" opacity="{{overlayOpacity}}" bg-color="{{overlayColor}}"></div>
<div class="vn-bk-inner">
<div class="vn-bk-row vn-bk-r1" vn-class="{'vn-bk-rev': r1_reverse}">
<div class="vn-bk-col vn-bk-c2"> <div class="vn-bk-el vn-bk-e3 vn-bk-t-image"> … </div> </div>
</div>
</div>
</section>The block is a container (container-type: inline-size); the line breaks for narrow widths depend on the width of the block (@container), not on the window: up to a block width of 700 px, all columns are stacked.
Background: image, color or video#
bg is a background field with three options: image, color, video. The value is an object: { "type": "color", "value": "#ffffff", "parallax": false }, for an image "value": { "url": "…" }, for a video "value": { "url": "<file or YouTube/Vimeo address>" }. The LESS knows the values as @bg-type, @bg-value and @bg-parallax. Parallax (background-attachment: fixed) exists only for the image. For the video, the address is in the data-bg-video attribute of the block; the finished page loads the script vendor/vn-bgvideo/ for it. The content of the block remains freely buildable.
Rows#
Properties of every row (group “Row n”):
| Key | Type | Default | Meaning |
|---|---|---|---|
perRow | Range 0–6 | 0 | Columns per row. 0: the width of each column (span) is set individually. Greater than 0: grid, all columns equally wide, any number of them, they wrap by themselves |
gap | Range 0–12 | 3 | Spacing between columns (unit 0.5 rem) |
valign | Choice | flex-start | flex-start, center, flex-end, stretch (equal height) |
reverse | Switch | off | Reversed order on the phone |
mb | Range 0–12 | 0 | Spacing below (unit 0.5 rem) |
Grid “Cards — any number”#
With perRow > 0 the row is a grid. The “+ Column” button then adds a copy of the last column including its content and settings; the width per column (span) no longer matters. With perRow > 2, a block 701–1000 px wide shows two cards per row; from 700 px downward, each card stands alone.
Columns#
| Key | Type | Default | Meaning |
|---|---|---|---|
span | Range 1–12 | 12 | Width out of 12 (only in rows with perRow = 0). When you add or copy a column, the program distributes the 12 parts evenly |
align | Choice | left | Text alignment in the column |
valign | Choice | flex-start | Content vertically: top, middle, bottom |
gap | Range 0–12 | 2 | Spacing of the elements (unit 0.5 rem) |
pad | Range 0–12 | 0 | Inner padding (unit 0.5 rem) |
hasBg | Switch | off | Own background (card) |
bg | Color | #ffffff | Background color of the card |
radius | Range 0–40 | 12 | Corner radius in px |
shadow | Switch | off | Shadow |
Elements#
There are ten kinds of elements. Every property is named <identifier>_<key> in the value object. All elements also have the root class vn-bk-el vn-bk-<identifier> vn-bk-t-<kind>.
Image (image)#
Markup: <img src="{{e3_src}}" alt="">. The image is clickable and can be scaled with handles.
| Key | Type | Default | Meaning |
|---|---|---|---|
src | Image | Placeholder image | File |
width | Range 10–100 | 100 | Width in % |
ratio | Choice | 4 / 3 | auto, 1 / 1, 4 / 3, 3 / 2, 16 / 9, 21 / 9, 3 / 4, 2 / 3 |
fit | Choice | cover | cover (fill) or contain (show completely) |
radius | Range 0–60 | 8 | Corner radius in px |
round | Switch | off | Circle (1:1) |
shadow | Switch | off | Shadow |
align | Choice | inherit | inherit, left, center, right |
Heading (heading)#
Markup: <h2 class="vn-bk-tx" data-vn-text-id="t…">. The user sets the level (h1–h6) in the text.
| Key | Type | Default | Meaning |
|---|---|---|---|
size | Range 1–6 (0.1) | 2.2 | Size in rem |
weight | Choice | 700 | 400, 500, 600, 700, 800 |
align | Choice | inherit | as above |
useColor, color | Switch, color | off, #111827 | own color, otherwise headColor of the block |
lh | Range 1–2 (0.05) | 1.2 | Line height |
ls | Range −3–12 (0.5) | 0 | Letter spacing (hundredths of an em) |
upper | Switch | off | UPPERCASE |
Text (text)#
Markup: <p class="vn-bk-tx" data-vn-text-id="t…">. Properties: size (0.7–2.5; default 1), align, useColor/color (#4b5563), lh (1–2.4; default 1.65).
Button (button)#
Markup: <a class="btn btn-primary" href="#">Mehr erfahren</a>; the user sets the target, text, color and icon in the Button dialog. Properties: align, size (sm, md, lg; default md), full (full width).
Icon (icon)#
Markup: <i class="bi bi-star-fill" data-vn-icon></i>. Properties: size (1–10 rem, default 2.5), color (#2563eb), circle (round background), bg (#e0e9ff), align.
List (list)#
A ul with up to 12 entries; each entry carries vn-if="<identifier>_count >= k". Properties: count (1–12, default 4), bullet (check, dot, arrow, star, dash, none), bulletColor, size, useColor/color, gap (0–6).
Image slider (slider)#
A Bootstrap carousel with up to 20 slides, each slide with one image (<identifier>_src1 … _src20) and two texts (heading and text) with the identifiers t<number × 100 + 2k − 1> and t<number × 100 + 2k>. Properties: count (hidden, 1–20, default 3), ratio (without auto; default 16 / 9), fit, radius (12), arrows, dots, captions, auto (seconds until the next slide, 0 = off; default 5), fade (cross-fade instead of sliding). You can add, remove and move the slides in the panel; image and texts move together.
Spacer (spacer)#
An empty area, h (0.5–12 rem, default 2).
Divider (divider)#
An hr. Properties: color (#d1d5db), thick (1–8 px), width (10–100 %), style (solid, dashed, dotted), align (left, center, right; default center).
Video (video)#
An iframe that appears only when an address is entered: src="{{vnEmbed(<identifier>_url)}}". vnEmbed converts YouTube and Vimeo addresses into the embed address. Properties: url, ratio (16 / 9, 4 / 3, 1 / 1, 21 / 9), width (20–100), radius, align.
Map (map)#
An iframe with https://www.google.com/maps?q=<address>&output=embed. Properties: addr (address), height (200–700 px, default 360), radius.
Layouts in the Builder tab#
The tab offers nine templates; each is a ready-made tree:
| Identifier | Name | Structure |
|---|---|---|
leer | Empty | one row, one column |
bild-links | Image left, text right | two columns: image; kicker text, heading, text, button |
bild-rechts | Text left, image right | as above, row with reverse (on the phone the image is on top) |
zentriert | Centered text | one column, width: narrow |
zwei-spalten | Two text columns | two columns, each with heading and text |
karten-raster | Cards — any number | grid perRow: 3 with cards (image, heading, text, button) |
symbole-raster | Benefits with icon — any number | grid with icon, heading, text |
bilder-slider | Image slider — any number of slides | one slider with three slides |
hero | Header with background image | large heading, text, button; darkening on, width: narrow |
User blocks#
A user block is a customized block that is stored under its own name in the program profile and can be inserted in any project (tab “User blocks”).
Saving with ★#
The ★ button (in the block's bar and in the Properties panel) asks for a name and category and stores the whole block: schemaEntry including the structure tree, values and all customizations (texts, buttons, icons, images, alt texts, animations). The new name also becomes the display name (schemaEntry.label) of the block. In the profile, the following are created under user-blocks/:
| File | Content |
|---|---|
<id>.json | { id, name, label, category, created, dataJson, theme, files }; the identifier has the form ub-<time><random> |
<id>.jpg | Preview, taken from the block's section on the work area (at most 480 px wide) |
<id>-files/assets/… | Copies of the files the block refers to |
In the text of dataJson, the placeholder @@VNPROJ@@ replaces the path of the project. Every reference of the form @@VNPROJ@@/assets/<path> counts as a file (images, but also other files under assets/), as do the scripts of a Bootstrap 4 theme (theme.files). When inserting into a project, the program copies the files there (existing ones are left untouched) and inserts the path of the target project. After that it is a block like any other and also keeps a builder structure.
Limits: name at most 80 characters, block data at most 60 MB.
Categories#
The category is free text (at most 40 characters, no control characters). The program suggests this list and adds the categories already in use: Header, Footer, Menu, Text, Images & gallery, Cards, Form, Contact, Pricing, Other. The program guesses a preset from the name (“hero” → Header, “footer” → Footer, “galerie” → Images & gallery …). The “User blocks” tab groups by category and offers a filter; with the label button 🏷 you change the category afterwards, with ✎ the name, and with 🗑 you delete the block (blocks already inserted stay in their projects).
Export as .vndext#
Two ways turn a block into a shareable package file with one block:
| Way | Where | Content of the template |
|---|---|---|
| ⤓ “Save as .vndext file” | Properties panel of the block, directly from the work area | baked in: texts, buttons, icons, images, alt texts and links are in the template; the set values of simple fields (number, text, color, switch, choice) are stored as default values in <vn-parameters>. Composite values such as bg stay at the block's default |
| ⇩ “Export as .vndext file” | Card of a user block | the stored template unchanged; customizations that exist only in values and the overrides are lost |
The package contains:
params.json { "name": "<Name>", "alias": "<Alias des Blocks>", "components": [ { "path": "components/component1" } ] }
components/component1/template.html
components/component1/style.less
components/component1/thumb.png (nur wenn eine Vorschau aufgenommen werden konnte)
components/_images/<pfad> Bilder und Dateien aus assets/ des ProjektsReferences to @@VNPROJ@@/assets/ become ../_images/. The alias is that of the block (for a builder block, vn-baukasten). When you insert the file into another project, the builder structure is gone: the template is a normal block; a builder structure is not written to the file (only ★ preserves it). A free surface also becomes a normal block on export.
Relationship to the code editor#
The “</> Code” button in the Properties panel opens the HTML and LESS of the block. It shows the visible, baked-in state: texts, buttons, icons and images with all customizations are directly in the HTML. This also applies to blocks from the “Custom code” tab (custom-html, custom-php).
- Builder and free surface are locked: their code cannot be edited (message on click; likewise in the right-click menu and in the AI chat). You rebuild them with “+” and the Properties panel.
- When applying (✓), the program checks the HTML (lint) and reports syntax errors with the line number (“The HTML contains n syntax error(s)”; the check knows
{{…}}, PHP blocks and<?php … ?>); the browser would silently rebuild faulty HTML. It also compares the classes before and after applying and warns if classes were lost. You can confirm both with “Apply anyway”. - A pasted whole page (
<html>,<head>,<body>) is placed in a wrapper in the block so that its classes do not disappear. Foreign framework junk from pasted AI chat texts is removed. A leading language tag (“css:”) in the LESS is dropped. - PHP in the HTML is stored protected as
<script type="text/x-vn-php">and converted back into raw PHP code on export. The page must then be named.php; the program offers to change the file name. If the PHP script carries the attributedata-position="top", the code goes to the start of the file on export (e.g. forsession_start()). - Placeholders: In
custom-html/custom-php, the program does not evaluate{{…}}(the opening braces are protected before rendering); in all other blocks it does. - After applying, the overrides (texts, buttons, icons, images) are cleared because they are now in the template; fields and default values are derived anew from
<vn-parameters>, existing values are kept. - The LESS is test-compiled before applying. On a LESS error, the dialog stays open and names the error; the HTML has then already been applied, the CSS has not.
Free surface#
The free surface works like the builder, only with free positioning: schemaEntry.freeSurface = { v: 1, next, s: { … }, items: [ { id, type, g: { x, y, w, h, z }, d } ] }. g is the geometry in percent of the surface width and height (h 0 = automatic, z = layer). At most 60 elements. All other settings are stored in block.values under <identifier>_<name>. On the phone, the surface stacks the elements one below the other (breakpoint adjustable) or scales along.