Ü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.
| Teil | Datei | Aufgabe |
|---|---|---|
| Markup und Eingabefelder | template.html | HTML des Blocks, dazu die Felder, die das Eigenschaften-Panel zeigt |
| Stil | style.less | LESS (oder CSS) mit den Werten der Felder als Variablen |
| Vorschau | thumb.png | Bild 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.
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#
| Begriff | Bedeutung |
|---|---|
| Block | Eine 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) |
| Paket | Eine ZIP-Datei .vndext mit einem oder mehreren Bausteinen, params.json und gemeinsamen Dateien |
| Theme | Ein Paket mit vielen zueinander passenden Bausteinen (Menü bis Fußzeile) und gemeinsamem Theme-CSS |
| Erweiterung | Ein 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 |
| Alias | Der technische Name eines Bausteins (alias in params.json); er bestimmt die CSS-Klasse der Instanzen |
| Wurzel | Das erste Element von template.html; es trägt die Instanzklasse |
| Instanz | Ein 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:
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 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):
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;
}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:
cd meine-bloecke
& "$env:SystemRoot\System32\tar.exe" -a -c -f ..\meine-bloecke.zip params.json components
Rename-Item ..\meine-bloecke.zip meine-bloecke.vndextMit Python (plattformunabhängig, so packen auch die Theme-Skripte des Programms):
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#
- Öffnen Sie ein Projekt (der Import legt Bilder im Projektordner ab).
- Klicken Sie auf + Block hinzufügen und wählen Sie den Reiter Datei (.vndext). Wählen Sie die Datei oder ziehen Sie sie hinein.
- 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.htmlundstyle.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
</> Codeim 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:
| Symptom | Ursache | Kapitel |
|---|---|---|
| Import meldet „kein gültiges JSON“ oder „template.html nicht gefunden“ | BOM in params.json; Backslashes im ZIP | oben, Pakete |
| Block ohne jedes CSS, Etikett „⚠ CSS-Fehler“ | Fehler im LESS: unbekannte Variable (@bg-… ohne Hintergrund-Widget), Umlaut im Feldnamen, BOM | LESS |
{{…}} ergibt überall leeren Text, vn-if blendet nichts aus | ein Feldname ist in JavaScript ungültig (Bindestrich, Ziffer am Anfang, reserviertes Wort) | Namen |
Ein Element bleibt trotz vn-if stehen | vn-if entfernt nur bei genau false; ein leerer Text oder ein Tippfehler im Namen lässt es stehen | vn-if |
{{beschriftung}} steht wörtlich im Knopf | In <a class="btn"> werden Platzhalter nicht ausgewertet | Platzhalter in Knöpfen |
n + 1 ergibt 41 | Werte von Schiebern sind Text | range |
| Block sieht im Editor anders aus als im Export | !important gegen Bootstrap/Theme-CSS; Layer nur im Editor | Rangfolge |
| Regel im Theme-CSS wirkt im Editor nicht | #canvas, body, html, :root im @scope; richtig: :scope | Die Falle #canvas |
| Hintergrundbild fehlt nach dem Import | Vorgabe file:///… auf den Rechner des Autors; richtig: ../_images/… | image |
Kapitelübersicht#
| Kapitel | Inhalt |
|---|---|
| Überblick und erster Block | dieses Kapitel |
| Das Template | Wurzelelement, Wurzelattribute, Platzhalter, Bilder und Links, Bootstrap, Editor und Export |
| Eingabefelder | <vn-parameters>: alle Eingabetypen, Hintergrund-Widget, condition, Vorgabewerte, Beispiel |
| Direktiven und Markierungen | vn-if, vn-class, vn-style, vn-overlay, vn-video und weitere; ältere Schreibweisen |
| Stil des Blocks | style.less: Variablen, Bereich, Rangfolge von Editor und Export, Fallen |
| Direkt bearbeitbare Inhalte | Text, Bilder, Symbole, Buttons, Menüs, Links, CMS, Popup |
| Skripte in Blöcken und Themes | JavaScript im Block, Editor-Erkennung, Cookie-Consent, mitgelieferte Bibliotheken |
| Formulare | statisches Formular vn-sform, PHP-Versand, Spam-Schutz, VN Form Editor |
| Hintergründe, Medien und Werkzeug-Bausteine | Hintergrund und Video, Lightbox, Galerie, PDF-Betrachter, Suche, Blog, Animationen, Übersetzer |
| Pakete und Themes | .vndext, params.json, Import, Theme-CSS, Themes-Ordner |
| Baukasten und Benutzerblöcke | Blöcke aus Zeilen, Spalten und Elementen, Benutzerblöcke |
| Erweiterungen | Werkzeug-Erweiterungen .vndtool, manifest.json, Programm-Schnittstelle ctx |
| Exportieren und Veröffentlichen | was der Export schreibt, Vorschau, FTP-Upload, Datenschutz-Regeln |
| Fallstricke und Checkliste | Checklisten vor dem Veröffentlichen, Tabelle aller Fallen mit Ursache und Lösung |
| Schnellreferenz | Tabellen aller Eingabetypen, Direktiven, Platzhalter, Paketdateien, ctx-Funktionen und Bibliotheken |