VN-Designer Entwickler-Dokumentation
01

Überblick und erster Block

Was ein Block ist, wie ein Block-Ordner aufgebaut ist, ein erster eigener Block in zehn Minuten (Ordner, Paket, Import, Test), die wichtigsten Begriffe und die Übersicht aller Kapitel.

Was ist ein Block?#

Eine Website im VN-Designer besteht aus Blöcken, die untereinander auf einer Seite stehen: Menü, Kopfbereich, Textblock, Galerie, Formular, Fußzeile. Jeder Block entsteht aus einem Baustein: einer wiederverwendbaren Beschreibung aus drei Teilen.

TeilDateiAufgabe
Markup und Eingabefeldertemplate.htmlHTML des Blocks, dazu die Felder, die das Eigenschaften-Panel zeigt
Stilstyle.lessLESS (oder CSS) mit den Werten der Felder als Variablen
Vorschauthumb.pngBild für die Auswahl (optional)

Ein Nutzer fügt einen Baustein ein, ändert Texte und Bilder direkt auf der Arbeitsfläche und stellt Farben, Abstände und Schalter im Eigenschaften-Panel ein. Beim Export entsteht daraus reines HTML und CSS, ohne Laufzeitbibliothek.

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)

Begriffe#

BegriffBedeutung
BlockEine Instanz auf einer Seite, mit eigenen Werten und eigenen Textänderungen
Baustein (Komponente)Die wiederverwendbare Vorlage, aus der Blöcke entstehen (template.html, style.less, thumb.png)
PaketEine ZIP-Datei .vndext mit einem oder mehreren Bausteinen, params.json und gemeinsamen Dateien
ThemeEin Paket mit vielen zueinander passenden Bausteinen (Menü bis Fußzeile) und gemeinsamem Theme-CSS
ErweiterungEin Werkzeug .vndtool für das Programm selbst (Prüfungen, Assistenten, Server-Dateien). Sie kann Bausteine mitbringen, ist aber etwas anderes als ein Paket
Eigenschaften (Felder, Parameter)Die Eingabefelder im Eigenschaften-Panel; jedes Feld hat einen Namen und einen Wert
AliasDer technische Name eines Bausteins (alias in params.json); er bestimmt die CSS-Klasse der Instanzen
WurzelDas erste Element von template.html; es trägt die Instanzklasse
InstanzEin einzelner Block auf einer Seite; zwei Blöcke desselben Bausteins sind zwei Instanzen mit eigenen Klassen

Aufbau eines Block-Ordners#

So sieht der Ordner eines Pakets mit einem Baustein aus:

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 eines Blocks: ein Wurzelelement, darin der Block <vn-parameters>, dann Inhalt mit Platzhaltern und Direktiven. Siehe Das Template.

style.less#

Stil des Blocks. Jedes Feld steht als LESS-Variable @name zur Verfügung. Siehe Stil des Blocks.

thumb.png#

Vorschaubild des Bausteins für die Auswahl und die Bibliothek. Fehlt es, zeigt die Auswahl ein Platzhaltersymbol. Siehe Pakete.

params.json#

Beschreibt das Paket: name, alias und components mit path, _group (Kategorie) und _title (Anzeigename). Siehe Pakete.

components/_images#

Gemeinsamer Bilderordner. Verweise in Template und LESS lauten ../_images/<datei>; der Import legt die Dateien im Projekt ab. Siehe Pakete.

Erster eigener Block in 10 Minuten#

Das Beispiel baut eine Hinweiskarte mit Abstand, Akzentfarbe und einem Schalter für den Zusatztext. Sie brauchen den VN-Designer mit einem geöffneten Projekt und einen Texteditor, der Dateien als UTF-8 ohne BOM speichert.

1. Ordner und Dateien anlegen#

Legen Sie diese Struktur an (Ordnernamen frei wählbar, die Pfade in params.json müssen dazu passen):

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;
}

Was hier passiert: Die Zeilen ohne Selektor (padding-top …) gelten für die Wurzel <section>; @abstand, @kartenFarbe und @akzent sind die Felder aus <vn-parameters>; vn-if="showText" entfernt den Absatz, wenn der Schalter aus ist.

2. Als Paket packen#

Ein Paket ist eine ZIP-Datei mit der Endung .vndext. Die Pfade im ZIP müssen mit Schrägstrich geschrieben sein (components/hinweiskarte/template.html).

Windows 10/11 (eingebautes tar), in einer 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

Mit Python (plattformunabhängig, so packen auch die Theme-Skripte des Programms):

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. Importieren#

  1. Öffnen Sie ein Projekt (der Import legt Bilder im Projektordner ab).
  2. Klicken Sie auf + Block hinzufügen und wählen Sie den Reiter Datei (.vndext). Wählen Sie die Datei oder ziehen Sie sie hinein.
  3. Der Baustein „Hinweiskarte“ landet standardmäßig nur in der Bibliothek (Reiter „Bibliothek“, Schalter unter der Ablagefläche: „Nur in die Bibliothek aufnehmen“) und kann von dort auf die Seite gesetzt werden. Schalten Sie den Schalter ein (er heißt dann „Direkt in Projekt einfügen“), kommt der Baustein sofort auf die Seite.

Ein Paket mit mehreren Bausteinen zeigt eine Auswahl mit den Vorschaubildern.

4. Testen#

  • Eigenschaften-Panel: Der Block hat die Gruppen „Größe“, „Anzeigen“ und „Farben“. Bewegen Sie den Schieber, schalten Sie den Zusatztext aus und ändern Sie die Farben: der Block zeichnet sich bei jeder Änderung neu.
  • Direkt bearbeiten: Klicken Sie in „Willkommen“ und tippen Sie. Klicken Sie auf den Knopf: der Knopf-Dialog öffnet sich. Beides ist automatisch, ohne dass das Template etwas dafür tut.
  • Fehler im LESS: Zeigt der Block das rote Etikett „⚠ CSS-Fehler“, steht die Meldung im Tooltip.
  • Live-Vorschau: Mit F5 zeigt das Programm die fertige Seite wie im Export, mit Schaltern für Tablet (820 px) und Handy (390 px). Medienabfragen prüfen Sie dort.
  • Export: Menü „Exportieren“ schreibt den Ordner mit index.html und style.css. Das Ergebnis hat keine Editor-Spuren.

5. Weiterarbeiten#

  • Ändern Sie die Dateien im Ordner, packen Sie neu und importieren Sie erneut. Die Bibliothek ersetzt dabei nichts: jeder Import legt einen weiteren Eintrag an.
  • Ein Block, der schon auf einer Seite steht, behält seine gespeicherte Vorlage: das Programm verändert vorhandene Projekte nie durch ein Paket-Update. Fügen Sie den Baustein zum Testen neu ein.
  • Schneller: Öffnen Sie den Block mit dem Knopf </> Code im Eigenschaften-Panel, ändern Sie Vorlage oder LESS und bestätigen Sie mit ✓ Übernehmen. Das ändert nur diesen Block. Übertragen Sie Änderungen anschließend in Ihre Dateien.
  • Gewöhnen Sie sich an, ein Paket in einen Themes-Ordner zu legen (Reiter „Themes“, Themes-Ordner wählen): Dort erscheint es bei jedem Öffnen des Dialogs als Katalog.
  • Einen Block, den Sie im Editor gebaut haben, speichern Sie mit ⤓ direkt als .vndext-Datei oder mit ★ als Benutzer-Block.

Häufige Stolpersteine#

Alle diese Punkte sind in den Kapiteln ausführlich belegt. Hier die Kurzfassung:

SymptomUrsacheKapitel
Import meldet „kein gültiges JSON“ oder „template.html nicht gefunden“BOM in params.json; Backslashes im ZIPoben, Pakete
Block ohne jedes CSS, Etikett „⚠ CSS-Fehler“Fehler im LESS: unbekannte Variable (@bg-… ohne Hintergrund-Widget), Umlaut im Feldnamen, BOMLESS
{{…}} ergibt überall leeren Text, vn-if blendet nichts ausein Feldname ist in JavaScript ungültig (Bindestrich, Ziffer am Anfang, reserviertes Wort)Namen
Ein Element bleibt trotz vn-if stehenvn-if entfernt nur bei genau false; ein leerer Text oder ein Tippfehler im Namen lässt es stehenvn-if
{{beschriftung}} steht wörtlich im KnopfIn <a class="btn"> werden Platzhalter nicht ausgewertetPlatzhalter in Knöpfen
n + 1 ergibt 41Werte von Schiebern sind Textrange
Block sieht im Editor anders aus als im Export!important gegen Bootstrap/Theme-CSS; Layer nur im EditorRangfolge
Regel im Theme-CSS wirkt im Editor nicht#canvas, body, html, :root im @scope; richtig: :scopeDie Falle #canvas
Hintergrundbild fehlt nach dem ImportVorgabe file:///… auf den Rechner des Autors; richtig: ../_images/…image

Kapitelübersicht#

KapitelInhalt
Überblick und erster Blockdieses Kapitel
Das TemplateWurzelelement, Wurzelattribute, Platzhalter, Bilder und Links, Bootstrap, Editor und Export
Eingabefelder<vn-parameters>: alle Eingabetypen, Hintergrund-Widget, condition, Vorgabewerte, Beispiel
Direktiven und Markierungenvn-if, vn-class, vn-style, vn-overlay, vn-video und weitere; ältere Schreibweisen
Stil des Blocksstyle.less: Variablen, Bereich, Rangfolge von Editor und Export, Fallen
Direkt bearbeitbare InhalteText, Bilder, Symbole, Buttons, Menüs, Links, CMS, Popup
Skripte in Blöcken und ThemesJavaScript im Block, Editor-Erkennung, Cookie-Consent, mitgelieferte Bibliotheken
Formularestatisches Formular vn-sform, PHP-Versand, Spam-Schutz, VN Form Editor
Hintergründe, Medien und Werkzeug-BausteineHintergrund und Video, Lightbox, Galerie, PDF-Betrachter, Suche, Blog, Animationen, Übersetzer
Pakete und Themes.vndext, params.json, Import, Theme-CSS, Themes-Ordner
Baukasten und BenutzerblöckeBlöcke aus Zeilen, Spalten und Elementen, Benutzerblöcke
ErweiterungenWerkzeug-Erweiterungen .vndtool, manifest.json, Programm-Schnittstelle ctx
Exportieren und Veröffentlichenwas der Export schreibt, Vorschau, FTP-Upload, Datenschutz-Regeln
Fallstricke und ChecklisteChecklisten vor dem Veröffentlichen, Tabelle aller Fallen mit Ursache und Lösung
SchnellreferenzTabellen aller Eingabetypen, Direktiven, Platzhalter, Paketdateien, ctx-Funktionen und Bibliotheken