VN-Designer Entwickler-Dokumentation
11

Baukasten und Benutzerblöcke

Wie der Block-Baukasten aus Zeilen, Spalten und Elementen Vorlage und LESS erzeugt, welches Datenmodell gespeichert wird, wie Benutzerblöcke und .vndext-Dateien aus eigenen Blöcken entstehen und wie das zum Code-Editor steht.

Überblick#

Der Baukasten (Reiter „Baukasten“ in „Block hinzufügen“) setzt einen Block aus Zeilen, Spalten und Elementen zusammen. Er ist kein eigener Rendermechanismus: aus einem kleinen Baum erzeugt das Programm bei jeder Änderung eine ganz normale Vorlage (<vn-parameters> plus Markup) und ein LESS. Der Block läuft danach durch dieselbe Pipeline wie jeder importierte Baustein (Felder, Standardwerte, Markierung der Texte, Buttons, Symbole und Bilder).

Drei verwandte Wege, einen eigenen Block zu bekommen:

WegErgebnisBleibt umbaubar
BaukastenBlock mit Aufbau-Baum (schemaEntry.builder), alias vn-baukastenja, mit den „+“-Knöpfen im Block und dem Bereich „Aufbau“ im Eigenschaften-Panel
Freie FlächeBlock mit Element-Baum (schemaEntry.freeSurface), alias vn-freija, per Maus auf der Fläche
Eigener CodeBlock custom-html / custom-php mit rohem Codenur über den Code-Editor

Das gespeicherte Datenmodell#

Ein Baukasten-Block ist im Projekt (projekt.vnd) ein normaler Block. Zusätzlich trägt sein schemaEntry zwei Felder:

FeldInhalt
builderDer Baum: { "v": 1, "next": 17, "rows": [ … ] }. next ist der Zähler für neue Kennungen. Eine Zeile (r…) hat id, d (Vorgaben) und cols; eine Spalte (c…) hat id, d und items; ein Element (e…) hat id, type und d
bkGroupsReihenfolge der Eigenschaften-Gruppen: ["block", "r1", "c2", "e3", …]

d enthält nur die Vorgaben für neu erzeugte Knoten. Alle Einstellungen stehen wie bei jedem Block in block.values, unter dem Schlüssel <Kennung>_<Eigenschaft>, z. B. e3_width, c2_span, r1_perRow. Die übrigen Felder von schemaEntry (templateHtml, lessText, fields, defaults, wrapperClass, buttonDefaults, iconDefaults) sind das fertig erzeugte Ergebnis.

Beispiel (Layout „Karten — beliebig viele“, aus einem gespeicherten Projekt, gekürzt)

json
{
  "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" }
}

Was beim Umbauen passiert#

Jede Strukturänderung (Zeile, Spalte oder Element hinzufügen, verschieben, kopieren, löschen) läuft über dieselbe Funktion: Sie ändert den Baum, erzeugt Vorlage, LESS und Felder neu und überträgt dann den Zustand:

  • Werte: Für jeden Schlüssel der neuen Feldliste gilt der bisherige Wert, sonst der Standard. Werte, deren Name mit _ beginnt (vom Programm vergebene wie die Text-Regler), bleiben immer erhalten. Werte gelöschter Knoten fallen weg.
  • Kopien: Ein kopierter Knoten bekommt neue Kennungen und die Werte des Originals.
  • Bearbeitungen: Texte tragen feste Kennungen (data-vn-text-id="t<Zahl der Kennung × 100 + k>"), Bilder hängen an ihrem Feld (e3_src). Buttons und Symbole nummerieren die Standardwerkzeuge fortlaufend; das Programm rechnet ihre Bearbeitungen (buttonOverrides, iconOverrides) deshalb je Element um. Alt-Texte, Titel, Größen und Links der Bilder hängen am Feldnamen.

Grenzen: höchstens 6 Spalten nebeneinander in einer normalen Zeile, höchstens 24 in einer Raster-Zeile (siehe unten); Liste höchstens 12 Einträge; Bilder-Slider höchstens 20 Folien. Die Beschreibung des Layouts „Bilder-Slider“ nennt „bis 12“; der Code lässt 20 zu.

Der Block#

Jeder Baukasten-Block hat zuerst die Gruppe „Block“ mit diesen Eigenschaften:

SchlüsselArtStandardBedeutung
widthAuswahlcontainerInhaltsbreite: container (1140 px), narrow (760 px), full (volle Breite)
minHeightBereich 0–100, Schritt 50Höhe in Prozent der Bildschirmhöhe; 0 = wie der Inhalt. Größer als 0 setzt eine feste Höhe (vh) mit abgeschnittenem Überstand, damit ein Hintergrund beim Schreiben nicht mitwächst
vAlignAuswahlcenterSenkrechte Lage des Inhalts (nur bei minHeight > 0)
paddingTop, paddingBottomBereich 0–14, Schritt 0,54Abstand oben/unten in rem
textColorFarbe#4b5563Textfarbe des Blocks
headColorFarbe#111827Farbe der Überschriften
bgHintergrundFarbe #ffffffsiehe Hintergrund
bgPosterBildleerVorschaubild, solange das Video lädt (nur bei Video-Hintergrund)
overlay, overlayColor, overlayOpacitySchalter, Farbe, Bereich 0–1aus, #000000, 0,5Abdunklung über dem Hintergrundbild oder -video

Das Grundgerüst des erzeugten Markups:

html
<section class="vn-bk" data-bg-video="{{bg.type == 'video' &amp;&amp; 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 &amp;&amp; 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>

Der Block ist ein Container (container-type: inline-size); die Umbrüche für schmale Breite richten sich nach der Breite des Blocks (@container), nicht nach dem Fenster: bis 700 px Blockbreite stehen alle Spalten untereinander.

Hintergrund Bild, Farbe oder Video#

bg ist ein Hintergrund-Feld mit drei Möglichkeiten: Bild, Farbe, Video. Der Wert ist ein Objekt: { "type": "color", "value": "#ffffff", "parallax": false }, bei einem Bild "value": { "url": "…" }, bei einem Video "value": { "url": "<Datei oder YouTube/Vimeo-Adresse>" }. Das LESS kennt die Werte als @bg-type, @bg-value und @bg-parallax. Parallax (background-attachment: fixed) gibt es nur beim Bild. Beim Video steckt die Adresse im Attribut data-bg-video des Blocks; die fertige Seite lädt dafür das Skript vendor/vn-bgvideo/. Der Inhalt des Blocks bleibt frei baubar.

Zeilen#

Eigenschaften jeder Zeile (Gruppe „Zeile n“):

SchlüsselArtStandardBedeutung
perRowBereich 0–60Spalten pro Zeile. 0: die Breite jeder Spalte (span) wird einzeln eingestellt. Größer als 0: Raster, alle Spalten gleich breit, beliebig viele, sie brechen von selbst um
gapBereich 0–123Abstand der Spalten (Einheit 0,5 rem)
valignAuswahlflex-startflex-start, center, flex-end, stretch (gleich hoch)
reverseSchalterausAuf dem Handy umgekehrte Reihenfolge
mbBereich 0–120Abstand nach unten (Einheit 0,5 rem)

Raster „Karten beliebig viele“#

Mit perRow > 0 ist die Zeile ein Raster. Die Schaltfläche „+ Spalte“ fügt dann eine Kopie der letzten Spalte samt Inhalt und Einstellungen hinzu; die Breite je Spalte (span) spielt keine Rolle mehr. Bei perRow > 2 zeigt ein Block mit 701–1000 px Breite zwei Karten pro Zeile; ab 700 px abwärts steht jede Karte allein.

Spalten#

SchlüsselArtStandardBedeutung
spanBereich 1–1212Breite von 12 (nur in Zeilen mit perRow = 0). Beim Hinzufügen oder Kopieren einer Spalte verteilt das Programm die 12 Teile gleichmäßig
alignAuswahlleftTextausrichtung in der Spalte
valignAuswahlflex-startInhalt senkrecht: oben, Mitte, unten
gapBereich 0–122Abstand der Elemente (Einheit 0,5 rem)
padBereich 0–120Innenabstand (Einheit 0,5 rem)
hasBgSchalterausEigener Hintergrund (Karte)
bgFarbe#ffffffHintergrundfarbe der Karte
radiusBereich 0–4012Rundung in px
shadowSchalterausSchatten

Elemente#

Es gibt zehn Elementarten. Jede Eigenschaft heißt im Wert-Objekt <Kennung>_<Schlüssel>. Alle Elemente haben außerdem die Wurzelklasse vn-bk-el vn-bk-<Kennung> vn-bk-t-<Art>.

Bild (image)#

Markup: <img src="{{e3_src}}" alt="">. Das Bild ist klickbar und lässt sich mit Griffen skalieren.

SchlüsselArtStandardBedeutung
srcBildPlatzhalterbildDatei
widthBereich 10–100100Breite in %
ratioAuswahl4 / 3auto, 1 / 1, 4 / 3, 3 / 2, 16 / 9, 21 / 9, 3 / 4, 2 / 3
fitAuswahlcovercover (füllen) oder contain (ganz zeigen)
radiusBereich 0–608Rundung in px
roundSchalterausKreis (1:1)
shadowSchalterausSchatten
alignAuswahlinheritinherit, left, center, right

Überschrift (heading)#

Markup: <h2 class="vn-bk-tx" data-vn-text-id="t…">. Die Ebene (h1–h6) stellt der Nutzer im Text ein.

SchlüsselArtStandardBedeutung
sizeBereich 1–6 (0,1)2,2Größe in rem
weightAuswahl700400, 500, 600, 700, 800
alignAuswahlinheritwie oben
useColor, colorSchalter, Farbeaus, #111827eigene Farbe, sonst headColor des Blocks
lhBereich 1–2 (0,05)1,2Zeilenhöhe
lsBereich −3–12 (0,5)0Buchstabenabstand (Hundertstel em)
upperSchalterausGROSSBUCHSTABEN

Text (text)#

Markup: <p class="vn-bk-tx" data-vn-text-id="t…">. Eigenschaften: size (0,7–2,5; Standard 1), align, useColor/color (#4b5563), lh (1–2,4; Standard 1,65).

Button (button)#

Markup: <a class="btn btn-primary" href="#">Mehr erfahren</a>; Ziel, Text, Farbe und Symbol stellt der Nutzer im Button-Dialog ein. Eigenschaften: align, size (sm, md, lg; Standard md), full (volle Breite).

Symbol (icon)#

Markup: <i class="bi bi-star-fill" data-vn-icon></i>. Eigenschaften: size (1–10 rem, Standard 2,5), color (#2563eb), circle (runder Hintergrund), bg (#e0e9ff), align.

Liste (list)#

Ein ul mit bis zu 12 Einträgen; jeder Eintrag trägt vn-if="<Kennung>_count >= k". Eigenschaften: count (1–12, Standard 4), bullet (check, dot, arrow, star, dash, none), bulletColor, size, useColor/color, gap (0–6).

Bilder-Slider (slider)#

Ein Bootstrap-Karussell mit bis zu 20 Folien, je Folie ein Bild (<Kennung>_src1 … _src20) und zwei Texte (Überschrift und Text) mit den Kennungen t<Zahl × 100 + 2k − 1> und t<Zahl × 100 + 2k>. Eigenschaften: count (versteckt, 1–20, Standard 3), ratio (ohne auto; Standard 16 / 9), fit, radius (12), arrows, dots, captions, auto (Sekunden bis zur nächsten Folie, 0 = aus; Standard 5), fade (Überblenden statt Schieben). Die Folien lassen sich im Panel hinzufügen, entfernen und verschieben; Bild und Texte wandern gemeinsam.

Abstand (spacer)#

Eine leere Fläche, h (0,5–12 rem, Standard 2).

Trennlinie (divider)#

Ein hr. Eigenschaften: color (#d1d5db), thick (1–8 px), width (10–100 %), style (solid, dashed, dotted), align (left, center, right; Standard center).

Video (video)#

Ein iframe, das nur erscheint, wenn eine Adresse eingetragen ist: src="{{vnEmbed(<Kennung>_url)}}". vnEmbed wandelt YouTube- und Vimeo-Adressen in die Einbett-Adresse. Eigenschaften: url, ratio (16 / 9, 4 / 3, 1 / 1, 21 / 9), width (20–100), radius, align.

Karte (map)#

Ein iframe mit https://www.google.com/maps?q=<Adresse>&output=embed. Eigenschaften: addr (Adresse), height (200–700 px, Standard 360), radius.

Layouts im Baukasten-Reiter#

Der Reiter bietet neun Vorlagen; jede ist ein fertiger Baum:

KennungNameAufbau
leerLeereine Zeile, eine Spalte
bild-linksBild links, Text rechtszwei Spalten: Bild; Kicker-Text, Überschrift, Text, Button
bild-rechtsText links, Bild rechtswie oben, Zeile mit reverse (auf dem Handy steht das Bild oben)
zentriertZentrierter Texteine Spalte, width: narrow
zwei-spaltenZwei Textspaltenzwei Spalten, je Überschrift und Text
karten-rasterKarten — beliebig vieleRaster perRow: 3 mit Karten (Bild, Überschrift, Text, Button)
symbole-rasterVorteile mit Symbol — beliebig vieleRaster mit Symbol, Überschrift, Text
bilder-sliderBilder-Slider — beliebig viele Folienein Slider mit drei Folien
heroKopfbereich mit Hintergrundbildgroße Überschrift, Text, Button; Abdunklung an, width: narrow

Benutzerblöcke#

Ein Benutzerblock ist ein angepasster Block, der unter eigenem Namen im Programm-Profil liegt und in jedem Projekt einfügbar ist (Reiter „Benutzer-Blöcke“).

Speichern mit ★#

Der Knopf ★ (in der Leiste des Blocks und im Eigenschaften-Panel) fragt Name und Kategorie ab und legt den ganzen Block ab: schemaEntry samt Aufbau-Baum, values und alle Anpassungen (Texte, Buttons, Symbole, Bilder, Alt-Texte, Animationen). Der neue Name wird zugleich der Anzeigename (schemaEntry.label) des Blocks. Im Profil entstehen unter user-blocks/:

DateiInhalt
<id>.json{ id, name, label, category, created, dataJson, theme, files }; die Kennung hat die Form ub-<Zeit><Zufall>
<id>.jpgVorschau, aufgenommen vom Ausschnitt des Blocks auf der Arbeitsfläche (höchstens 480 px breit)
<id>-files/assets/…Kopien der Dateien, auf die der Block verweist

Im Text von dataJson ersetzt der Platzhalter @@VNPROJ@@ den Pfad des Projekts. Als Datei gilt jeder Verweis der Form @@VNPROJ@@/assets/<pfad> (Bilder, aber auch andere Dateien unter assets/) sowie die Skripte eines Bootstrap-4-Themes (theme.files). Beim Einfügen in ein Projekt kopiert das Programm die Dateien dorthin (vorhandene bleiben unberührt) und setzt den Pfad des Zielprojekts ein. Danach ist es ein Block wie jeder andere und behält auch einen Baukasten-Aufbau.

Grenzen: Name höchstens 80 Zeichen, Blockdaten höchstens 60 MB.

Kategorien#

Die Kategorie ist ein freier Text (höchstens 40 Zeichen, ohne Steuerzeichen). Das Programm schlägt diese Liste vor und ergänzt sie um schon benutzte Kategorien: Header, Footer, Menü, Text, Bilder & Galerie, Karten, Formular, Kontakt, Preise, Sonstiges. Eine Vorbelegung rät das Programm aus dem Namen („hero“ → Header, „footer“ → Footer, „galerie“ → Bilder & Galerie …). Der Reiter „Benutzer-Blöcke“ gruppiert nach Kategorie und bietet einen Filter; mit dem Etikett-Knopf 🏷 ändert man die Kategorie nachträglich, mit ✎ den Namen, mit 🗑 löscht man den Block (bereits eingefügte Blöcke bleiben in ihren Projekten).

Export als .vndext#

Zwei Wege machen aus einem Block eine weitergebbare Paketdatei mit einem Baustein:

WegWoInhalt der Vorlage
⤓ „Als .vndext-Datei speichern“Eigenschaften-Panel des Blocks, direkt von der Arbeitsflächeeingebacken: Texte, Buttons, Symbole, Bilder, Alt-Texte und Links stehen in der Vorlage; die eingestellten Werte einfacher Felder (Zahl, Text, Farbe, Schalter, Auswahl) stehen als Standardwerte in <vn-parameters>. Zusammengesetzte Werte wie bg bleiben beim Standard des Bausteins
⇩ „Als .vndext-Datei exportieren“Karte eines Benutzerblocksdie gespeicherte Vorlage unverändert; Anpassungen, die nur in values und den Overrides stehen, gehen verloren

Das Paket enthält:

text
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 Projekts

Verweise auf @@VNPROJ@@/assets/ werden zu ../_images/. Der Alias ist der des Blocks (bei einem Baukasten vn-baukasten). Beim Einfügen der Datei in ein anderes Projekt ist der Baukasten-Aufbau verschwunden: die Vorlage ist ein normaler Block; ein Baukasten-Aufbau wird nicht in die Datei geschrieben (nur ★ bewahrt ihn). Eine Freie Fläche wird beim Export ebenfalls zu einem normalen Block.

Verhältnis zum Code-Editor#

Der Knopf „</> Code“ im Eigenschaften-Panel öffnet HTML und LESS des Blocks. Er zeigt den sichtbaren, eingebackenen Zustand: Texte, Buttons, Symbole und Bilder mit allen Anpassungen stehen direkt im HTML. Das gilt auch für Blöcke aus dem Reiter „Eigener Code“ (custom-html, custom-php).

  • Baukasten und Freie Fläche sind gesperrt: ihr Code darf nicht bearbeitet werden (Meldung beim Klick; ebenso im Rechtsklick-Menü und im KI-Chat). Man baut sie über „+“ und das Eigenschaften-Panel um.
  • Beim Übernehmen (✓) prüft das Programm das HTML (Lint) und meldet Syntaxfehler mit Zeilennummer („Im HTML gibt es n Syntaxfehler“; Prüfung kennt {{…}}, PHP-Blöcke und <?php … ?>); der Browser würde fehlerhaftes HTML stillschweigend umbauen. Außerdem vergleicht es die Klassen vor und nach dem Übernehmen und warnt, wenn Klassen verloren gingen. Beides lässt sich mit „Trotzdem übernehmen“ bestätigen.
  • Eine eingefügte ganze Seite (<html>, <head>, <body>) wird in einen Umschlag im Block gesetzt, damit ihre Klassen nicht verschwinden. Fremder Framework-Müll aus eingefügten KI-Chat-Texten wird entfernt. Eine vorangestellte Sprachmarke („css:“) im LESS fällt weg.
  • PHP im HTML wird geschützt als <script type="text/x-vn-php"> abgelegt und im Export zurück in rohen PHP-Code verwandelt. Die Seite muss dann .php heißen; das Programm bietet an, den Dateinamen umzustellen. Trägt das PHP-Skript das Attribut data-position="top", kommt der Code im Export an den Dateianfang (z. B. für session_start()).
  • Platzhalter: In custom-html/custom-php wertet das Programm {{…}} nicht aus (die öffnenden Klammern werden vor dem Rendern geschützt); in allen anderen Blöcken schon.
  • Nach dem Übernehmen sind die Overrides (Texte, Buttons, Symbole, Bilder) geleert, weil sie jetzt in der Vorlage stehen; Felder und Standardwerte werden aus <vn-parameters> neu abgeleitet, vorhandene Werte bleiben.
  • Das LESS wird vor dem Übernehmen testweise kompiliert. Bei einem LESS-Fehler bleibt der Dialog offen und nennt den Fehler; das HTML ist dann schon übernommen, das CSS nicht.

Freie Fläche#

Die Freie Fläche funktioniert wie der Baukasten, nur mit freier Lage: schemaEntry.freeSurface = { v: 1, next, s: { … }, items: [ { id, type, g: { x, y, w, h, z }, d } ] }. g ist die Geometrie in Prozent der Flächenbreite und -höhe (h 0 = automatisch, z = Ebene). Höchstens 60 Elemente. Alle übrigen Einstellungen stehen in block.values unter <Kennung>_<Name>. Am Handy stapelt die Fläche die Elemente untereinander (Umbruchpunkt einstellbar) oder skaliert mit.