VN-Designer Entwickler-Dokumentation
10

Pakete und Themes (.vndext)

Aufbau einer Paketdatei (.vndext) mit Bausteinen und Theme-Dateien, params.json, seitenweite Blöcke, Import-Regeln, Theme-CSS und ein vollständiges Mini-Theme als Beispiel.

Überblick#

Ein Paket ist eine ZIP-Datei mit der Endung .vndext. Es enthält einen oder mehrere Bausteine (Komponenten) und optional gemeinsame Dateien eines Themes (CSS, Bilder, Schriften). Der Import prüft nur den Inhalt: eine .zip-Datei mit params.json funktioniert genauso wie eine .vndext-Datei.

  • Einzelbaustein: components hat genau einen Eintrag. Der Baustein wird direkt importiert.
  • Theme-Paket: components hat mehr als einen Eintrag. Der Import zeigt eine Auswahl mit den Vorschaubildern aller Bausteine; gewählte Bausteine kommen in die Bibliothek des Projekts oder direkt auf die Seite.

Wege, ein Paket ins Programm zu bringen:

WegOrt im ProgrammErgebnis
Datei wählen oder hineinziehenBlock hinzufügen › Reiter „Datei (.vndext)“Standard: nur in die Bibliothek aufnehmen; mit dem Schalter „Direkt in Projekt einfügen“ gleich auf die Seite
Themes-OrdnerBlock hinzufügen › Reiter „Themes“Alle .vndext/.zip-Dateien des gewählten Ordners erscheinen als Katalog; dazu die mitgelieferten Start-Themes
Online-GalerieBlock hinzufügen › Reiter „VN Block Galerie“Das Paket wird unverändert geladen und läuft durch denselben Import
Erweiterungctx.blocks.importPackage, ctx.blocks.importToLibrarysiehe Erweiterungen

Aufbau des ZIP#

So ist das Paket vn-kinetic-theme.vndext (16 Bausteine) aufgebaut; Dateien ohne Bedeutung für den Import sind markiert.

text
params.json                          Pflicht: Name, Alias, Liste der Bausteine
thumbnail.jpg                        Vorschau für die Online-Galerie (nur dort gelesen)
CREDITS.txt, cover.png, splash.html  ohne Bedeutung für den Import
plugins/plugin.json                  ohne Bedeutung für den Import
plugins/theme/css/style.css          Theme-CSS (wird einmal pro Projekt geladen)
components/
  _images/hero1.jpg …                Bilder, auf die Bausteine verweisen
  menu1/
    template.html                    Pflicht: Markup + <vn-parameters>
    style.less                       optional: Stil des Bausteins (LESS oder CSS)
    thumb.png                        optional: Vorschau in der Auswahl
  hero1/ … footer1/

params.json#

Die Datei beschreibt das Paket. Das Programm liest nur die folgenden Felder; weitere Felder (version, minAppVersion, description, plugins, logo, ampCompatible, _isSecondary) bleiben unbeachtet.

Syntax

json
{
  "name": "Mini Theme",
  "title": "Mini Theme",
  "alias": "mini-theme",
  "components": [
    { "path": "components/menu1", "_group": "Menü", "_title": "Menü (einfach)" }
  ]
}

Felder

FeldTypStandardBedeutung
nameTextaliasAnzeigename des Pakets. Bei einem Einzelbaustein ist er der Name des Blocks; bei einem Theme-Paket steht er vor dem Namen jedes Bausteins („Mini Theme – Footer“) und als Name der Themes-Gruppe in der Bibliothek
aliasTextblock-<Zeit>Kennung des Pakets. Daraus entstehen Alias und CSS-Klasse jedes Blocks, siehe Bezeichner
titleTextaliasBestimmt die Kennung des Theme-CSS (vn-theme-css-<title>), siehe Theme-CSS
componentsListe–Pflicht. Jeder Eintrag ist ein Objekt mit path (Ordner im ZIP, Pflicht). Fehlt components oder ist die Liste leer, lehnt der Import das Paket ab
components[].pathText–Ordner des Bausteins, z. B. components/menu1. Dort müssen template.html und optional style.less (oder style.css) und thumb.png liegen
components[]._titleTextOrdnernameAnzeigename des Bausteins in Auswahl, Bibliothek und Katalog („Hero mit Hintergrundbild“)
components[]._groupText–Gruppe in der Theme-Auswahl („Menü“, „Header“, „Footer“); ohne _title entsteht daraus „Header 7“ aus _group und der Zahl am Ordnernamen
components[]._onceText–Nur Anzeige: Wer hier einen Wert setzt, bekommt in Auswahl und Katalog den Zusatz „· site-weit“. Das tatsächliche Verhalten steuert das Attribut once im Baustein, siehe Seitenweite Blöcke
themeObjekt–Optional: settings (Liste von Theme-Variablen) und customLESS (Pfad zu einer LESS-Datei im Paket), siehe Theme-Eigenschaften
appScriptWert–Ein Paket mit appScript und ohne components wird abgelehnt. Mit components werden diese ganz normal importiert, das Skript bleibt ungenutzt

template.html#

Das Markup des Bausteins. Das erste Element ist die Wurzel des Blocks (meist section). Es enthält einen Block <vn-parameters> mit den Eingabefeldern des Eigenschaften-Panels, danach das eigentliche Markup mit {{platzhaltern}} und Direktiven wie vn-if, vn-class, vn-style. Alles dazu steht im Kapitel Eingabefelder; hier nur das Verhalten beim Import:

  • Alle Verweise der Form …/_images/<datei> (auch ../_images/… oder ein längerer Pfad davor) werden in echte Projektdateien übersetzt, siehe Bilder und Dateinamen.
  • Der Block <vn-parameters> wird beim Rendern entfernt und nie exportiert.
  • Eigene <script>-Blöcke bleiben im Markup. Sie laufen auf der fertigen Seite. Im Editor führt das Programm sie standardmäßig ebenfalls aus (Site-Einstellung „Skripte der Blöcke im Editor ausführen“, an), aber mit Stellvertretern für Zeitgeber, load-Ereignisse und location; jeder neue Zeichenlauf beendet die Zeitgeber des vorigen. Schreiben Sie Skripte so, dass sie mit el.closest('#canvas') erkennen, ob sie im Editor laufen, und dort nichts verschieben oder verstecken.

style.less oder style.css#

Der Stil des Bausteins. Das Programm sucht zuerst style.less, dann style.css. Es kompiliert ihn bei jeder Änderung eines Eigenschaften-Werts neu; jeder Parametername steht darin als LESS-Variable zur Verfügung (@paddingTop, @bg-type, @bg-value …). Der Stil gilt nur für diese Block-Instanz: das Programm setzt die Instanzklasse davor.

thumb.png#

Das Vorschaubild des Bausteins für Auswahl und Bibliothek. Das Programm liest nur diesen Namen (thumb.png, PNG). Ab 30 KB wird es auf höchstens 480 px Breite verkleinert und als WebP im Projekt abgelegt. Fehlt die Datei, zeigt die Auswahl ein Platzhalter-Symbol.

components/_images#

Gemeinsamer Bilderordner des Pakets. Verweise in template.html, style.less und im Theme-CSS lauten ../_images/<datei>. Erlaubt sind Dateien mit den Endungen jpg, jpeg, png, gif, svg und webp.

plugins/ und fonts/#

Alle .css-Dateien unter plugins/ sowie fonts/style.css zählen zum Theme-CSS, siehe Theme-CSS. JavaScript-Dateien unter plugins/ kopiert das Programm nur dann ins Projekt, wenn das Paket ein Bootstrap-4-Theme ist (Bootstrap-Modus).

Keine Skriptdatei je Baustein#

Der Import liest je Baustein nur template.html, style.less/style.css und thumb.png. Eine eigene Skriptdatei neben dem Baustein (script.js) wird nicht gelesen. JavaScript gehört als <script> in template.html; benutzen Sie keine festen IDs und Merker als JavaScript-Eigenschaft am Element, denn derselbe Baustein kann mehrfach auf einer Seite stehen.

thumbnail.jpg und die Galerie-Vorschau#

Die Online-Galerie nimmt als Vorschau des Pakets die erste passende Datei in der Rangfolge thumbnail, thumb, preview, screenshot, card, block, cover (Endung .jpg/.jpeg/.png, höchstens 2 MB, Dateien mit „splash“ im Namen zählen nicht). Der Vergleich beruht auf dem Dateinamen ohne Ordner: thumbnail.jpg gewinnt gegen die thumb.png der Bausteine. Das Programm selbst liest thumbnail.jpg nie.

Bezeichner: Alias, Label, Gruppe#

Aus den Angaben in params.json leitet der Import diese Namen ab (Beispiel alias: mini-theme, Baustein components/hero1, Block-Kennung bmw3s2mqdbf95):

NameEinzelbausteinTheme-PaketBeispiel
Alias des Bausteinsalias<alias>-<Ordnername>mini-theme-hero1
Label (Anzeigename)name<name> – <_title>„Mini Theme – Hero mit Hintergrundbild“
Wurzelklassevn-imp-<alias>vn-imp-<alias>-<Ordnername>vn-imp-mini-theme-hero1
Instanzklasse im fertigen HTML<Wurzelklasse>-<Block-Kennung>ebensovn-imp-mini-theme-hero1-bmw3s2mqdbf95
Anker-ID der Wurzelblk-<Block-Kennung> (oder die vom Nutzer gesetzte Anker-ID)ebensoblk-bmw3s2mqdbf95

Die Wurzelklasse wird aus dem Alias gebildet (nur a-z0-9, alles andere wird zu -). Jede Block-Instanz bekommt ihre eigene Instanzklasse; deshalb stören sich zwei gleiche Bausteine auf einer Seite nicht. {{vn-id}} im Markup steht für die Anker-ID der Instanz.

Die Gruppe (_group) dient in der Theme-Auswahl, im Themes-Katalog und in der Galerie-Suche als Kategorie. Ein Baustein, der erst in der Bibliothek liegt, kennt _group nicht mehr (sie wird nicht mit dem Baustein gespeichert); seine Kategorie ist dort sein Name ohne angehängte Zahl („Hero 3“ → „Hero“).

Seitenweite Blöcke: global und once#

Menü und Fußzeile gehören auf jede Seite. Ein Baustein wird seitenweit („global“), wenn sein Wurzelelement das Attribut global trägt.

Syntax

html
<section class="mini mini-menu" global once="menu"> … </section>
<section class="mini mini-footer" global once="footers"> … </section>

Attribute

AttributWertBedeutung
global–Macht den Block seitenweit: er liegt nicht in einer Seite, sondern in der Liste der globalen Blöcke und erscheint auf jeder exportierten Seite
onceText, z. B. menu, footersName der Gruppe. Von jeder Gruppe gibt es höchstens einen Block im Projekt: ein neu eingefügter ersetzt den alten (Meldung „bisherigen globalen Block ersetzt“). Ohne once heißt die Gruppe global

Die Lage im Export bestimmt der Gruppenname: enthält er menu, nav oder header (Groß-/Kleinschreibung egal), steht der Block vor dem Seiteninhalt, alle anderen Gruppen danach. Im Beispiel oben steht das Menü also oben, die Fußzeile unten. Ihr CSS landet nur einmal in style.css.

Der Import Schritt für Schritt#

importVndextComponent() in src/vndext-import.js behandelt je Baustein diese Schritte in genau dieser Reihenfolge:

  1. template.html und style.less (oder style.css) lesen.
  2. Bootstrap-4-Attribute auf Bootstrap 5 umschreiben.
  3. Bekannte Demo-Spuren fremder Paketquellen entfernen (siehe unten).
  4. Eine vorangestellte Sprachmarke im Stil („css:“) entfernen.
  5. Alte Direktivnamen auf vn- umschreiben.
  6. ../_images/… in Projektdateien übersetzen (Vorlage und Stil).
  7. Theme-CSS laden, sofern das Paket welches enthält (einmal pro Theme).
  8. Theme-Variablen (params.theme.settings) als siteVars übernehmen.
  9. Vorschaubild lesen und verkleinern.
  10. Aliasnamen und Wurzelklasse bilden; seitenweiten Block erkennen (global/once).
  11. Bild-Vorgaben mit file:///-Pfad ins Projekt kopieren, wenn die Datei auf diesem Rechner existiert.
  12. Felder und Standardwerte aus <vn-parameters> bauen.
  13. Bild-Felder, Fließtexte, Buttons, Symbole und freie Bilder markieren, damit sie im Editor anklickbar werden.

Das Ergebnis ist ein Eintrag mit templateHtml, lessText, fields, defaults, wrapperClass, siteVars, thumb, isGlobal, globalGroup und einer render-Funktion. Er wird mit dem Projekt gespeichert; beim Öffnen baut das Programm nur die render-Funktion neu auf und führt die Markierungsschritte erneut aus (sie sind wiederholbar, vorhandene Kennungen bleiben).

Bereinigung von Altpaketen#

Pakete aus älteren Quellen bringen Eigenheiten mit, die der Import selbst bereinigt. Neue Pakete sollten sie von vornherein vermeiden.

Fund im PaketBehandlung
data-toggle, data-target, data-dismiss, data-ride, data-slide, data-slide-to, data-parentZusätzlich wird das Bootstrap-5-Attribut data-bs-… mit demselben Wert gesetzt (ein vorhandenes data-bs-… bleibt)
Demo-Links und Namen des Ursprungsprogramms (Social-Links, Kurzadressen, Alt-Texte, Fließtexte)Links werden zu #, Alt-Texte leer, Namen im Text durch einen Phantasienamen ersetzt
Prüfung „läuft im Builder?“ im SkriptAuf die einfache iframe-Prüfung vereinfacht
mbr-parameters, mbr-if, mbr-class, mbr-style, mbr-buttons, mbr-menu, mbr-video, mbr-icon, mbr-articleWerden in vn-… umbenannt (mbr-icon wird zu data-vn-icon)
mbr-theme-style="display-N" bei Themes mit displayNSize-VariablenWird zu vn-theme-style, damit die Klasse auf das Theme-CSS trifft und nicht auf die größeren Display-Klassen von Bootstrap
value="file:///…" in Bild-FeldernSiehe Bilder und Dateinamen
<mbr-parameters> in Vorlage und StilUmbenannt in <vn-parameters>

Bilder und Dateinamen#

  • Ziel: Bilder aus _images landen als echte Dateien in assets/images/ des Projekts, Schriften in assets/fonts/, Theme-CSS in assets/theme/. Ein Eintrag der Vorlage wird zu einer file://-Adresse dieser Datei.
  • Namen bleiben erhalten. Ist der Name frei, entsteht eine Datei mit dem Originalnamen. Gibt es bereits eine Datei mit gleichem Inhalt (egal unter welchem Namen), wird sie wiederverwendet. Ist der Name mit anderem Inhalt belegt, hängt das Programm -2, -3 … an. Es gibt dabei keine Rückfrage, auch nicht bei vielen Dateien eines Themes.
  • Größe: höchstens 15 MB je Datei; leere Dateien werden abgelehnt.
  • Fremde Pfade: Eine Bild-Vorgabe mit value="file:///C:/…" zeigt auf den Rechner des Autors. Das Programm übernimmt sie nur, wenn sie auf den Projektordner zeigt; sonst versucht es, die Datei auf diesem Rechner ins Projekt zu kopieren (nur Bildformate), und lässt das Feld andernfalls leer. Verwenden Sie in Paketen deshalb immer ../_images/….

Bootstrap-Attribute und Bootstrap-Modus#

Das Programm liefert Bootstrap 5.0.1 (vendor/bootstrap.min.css, vendor/bootstrap.bundle.min.js) und die Bootstrap Icons. Pakete für Bootstrap 5 brauchen nichts weiter. Ein Paket mit eigenem plugins/bootstrap/css/bootstrap.min.css, dessen Kopfzeile „Bootstrap v4.x.x“ nennt, gilt als Bootstrap-4-Theme: Beim ersten Import kopiert das Programm die Skripte des Themes (plugins/*/*.js, ohne .map und ohne *.full.js) nach assets/theme-js/ und merkt sich den Eintrag unter siteSettings.themeAssets. Der Nutzer kann dann das Projekt auf „Bootstrap des Themes“ umstellen. Im Export lädt jede Seite dann jQuery (vendor/jquery.min.js), Popper, das Bootstrap-JS des Themes, das Smooth-Scroll-Skript, die Skripte der Plugins, die ihre Bausteine anfordern, und zuletzt das Theme-Skript. Welche Plugins ein Baustein braucht, schreibt das Attribut plugins="DropDown, TouchSwipe" am Wurzelelement.

Fehlt ein Plugin-Ordner im Paket, lädt das Programm es nicht. Pakete für Bootstrap 5 tragen data-bs-version="5.1" am Wurzelelement; das Programm meldet, wenn ein solcher Baustein in ein Bootstrap-4-Projekt kommt.

Theme-CSS#

Das Theme-CSS ist das gemeinsame CSS eines Theme-Pakets (Grundtypografie, Buttons, Hilfsklassen). Es steht nicht in den einzelnen Bausteinen, sondern wird einmal pro Projekt geladen.

Welche Dateien geladen werden#

Beim Import des ersten Bausteins eines Pakets sucht das Programm diese Dateien im ZIP und fügt sie in dieser Reihenfolge zu einer Datei zusammen:

  1. plugins/bootstrap/css/bootstrap.min.css
  2. plugins/theme/css/style.css
  3. fonts/style.css
  4. alle weiteren plugins/**/*.css, alphabetisch (ausgenommen bootstrap-grid* und bootstrap-reboot*)
  5. die aus params.theme.customLESS übersetzte LESS-Datei (falls angegeben)

Nur wenn mindestens eine dieser Quellen existiert, entsteht ein Theme-CSS. Ein einzelner Baustein ohne diese Dateien (der übliche Fall) löst kein Theme-CSS aus. Ein Paket mit eigenem Bootstrap bringt das Bootstrap-CSS also mit; Pakete für das mitgelieferte Bootstrap 5 liefern in plugins/theme/css/style.css nur ihre eigenen Regeln.

Im Editor: Layer und Scope#

Im Editor steht das Theme-CSS in einem <style id="vn-theme-css-<name>"> im Dokumentkopf:

css
@layer theme-base {
@scope (#canvas) {
  /* Theme-CSS */
}
}

Die Reihenfolge der Layer lautet app-ui, bootstrap-base, theme-base, vn-blocks; spätere Layer gewinnen. Das CSS der Bausteine liegt in vn-blocks und schlägt das Theme-CSS deshalb bei gewöhnlichen Angaben auch bei geringerer Spezifität. Bei !important dreht sich das um: Dort gewinnt der frühere Layer, also das Theme-CSS gegen eine !important-Angabe im Block (im Export dagegen entscheiden Spezifität und Reihenfolge, siehe Rangfolge). @scope (#canvas) begrenzt das Theme auf die Arbeitsfläche, damit es die Oberfläche des Programms nicht verändert. Schreiben Sie Theme-CSS ganz normal ohne @scope und ohne @layer.

Im Export#

Die Seiten laden eine einzige Datei style.css. Ihr Aufbau: zuerst das Theme-CSS ungescopt (im Export gibt es kein #canvas), danach das CSS aller Blöcke, dann die Schriften-Regeln, die festen Hilfsregeln des Programms (Menü, Handy-Menü, Links) und zuletzt das Eigene CSS des Nutzers. Theme-CSS und Block-CSS stehen im Export in derselben Ebene; bei gleicher Spezifität gewinnt, was später steht.

Nur einmal pro Projekt#

Die Kennung des Theme-CSS ist vn-theme-css- plus title (ersatzweise alias), alles in Kleinbuchstaben und jedes Zeichen außer a-z und 0-9 als - („Mini Theme“ → vn-theme-css-mini-theme). Ist ein Stil dieser Kennung im Projekt schon vorhanden, lädt das Programm nichts neu:

  • Zwei verschiedene Pakete mit gleichem title teilen sich ein Theme-CSS: das zuerst geladene gewinnt.
  • Ein Update eines Pakets ersetzt das Theme-CSS eines bestehenden Projekts nicht (im Test: neue Regeln im CSS des Pakets, erneuter Import, das Projekt zeigt weiter das alte CSS). Der neue Baustein kommt, das alte Theme-CSS bleibt. Eine Erneuerung ist nicht vorgesehen; in einem neuen Projekt gilt das neue Theme-CSS. Rechnen Sie bei Updates deshalb damit, dass Bausteine mit dem alten Theme-CSS laufen müssen.

Schriften und Bilder im Theme-CSS#

In jeder CSS-Datei des Pakets werden url(…)-Verweise relativ zum Ort der Datei im ZIP aufgelöst. Dateien mit den Endungen woff2, woff, ttf, otf, eot kommen nach assets/fonts/, Bilder (jpg, jpeg, png, gif, svg, webp) nach assets/images/; die Verweise im CSS werden zu file://-Adressen (im Export zu assets/…). data:-, http:- und //-Adressen bleiben unverändert.

Theme-Eigenschaften (params.theme)#

Ein Theme kann seine Variablen an einer Stelle festlegen, damit alle Bausteine sie in LESS benutzen. Das passiert in params.theme.settings:

Syntax

json
{
  "theme": {
    "settings": [
      { "var": "primaryColor", "type": "color", "default": "#0f766e", "title": "Hauptfarbe" },
      { "set": [
        { "var": "successColor", "default": "#28a745" },
        { "var": "dangerColor", "default": "#dc3545" }
      ] }
    ],
    "customLESS": "plugins/theme/css/custom.less"
  }
}

Felder

FeldBedeutung
settings[].varName der Variable; sie steht in jedem style.less des Pakets als @primaryColor zur Verfügung. Einträge ohne var (Überschriften) werden übersprungen
settings[].defaultStartwert
settings[].typecolor, range, checkbox (auch switch → Wahrheitswert), sonst Text. Fehlt type, schließt das Programm aus dem Wert: Wahrheitswert → checkbox, Zahl → range, #hex → color, sonst Text
settings[].setListe gleichartiger Einträge ohne eigenes Gruppenfeld (z. B. Farbvarianten)
customLESSPfad zu einer LESS-Datei im ZIP; sie wird mit den Variablen übersetzt und ihr CSS ans Theme-CSS gehängt

Ohne diese Angaben bricht jedes style.less ab, das eine Theme-Variable benutzt (variable @primaryColor is undefined). Für einzeln importierte Bausteine hält das Programm einen neutralen Satz bekannter Namen bereit (primaryColor, secondaryColor, successColor, infoColor, warningColor, dangerColor, mainFont, display1Font/display1Size … display7Size, isRoundedButtons u. a.); die echten Werte des Pakets gehen vor. Die Variablen werden mit dem Baustein gespeichert (siteVars).

Speicherung und Selbstheilung#

Das fertige Theme-CSS liegt als Datei assets/theme/vn-theme-css-<name>.css im Projekt; der Verweis steht in siteSettings.themeCssFiles (Kennung → Pfad). Beim Öffnen eines Projekts lädt das Programm diese Dateien wieder in den Editor und nimmt sie in den Export auf.

Findet es beim Öffnen Dateien in assets/theme/, auf die kein Verweis zeigt (Reste älterer Importe ohne anschließendes Speichern), merkt es sie nur als „wiedergefunden“. Diese Reste werden weder im Editor angewendet noch exportiert noch gespeichert; sonst kollidierten die Buttonfarben mehrerer längst nicht mehr benutzter Themes. Ein Theme wird erst wieder aktiv, wenn es neu importiert wird.

Themes-Ordner und Katalog#

Ein Themes-Ordner ist ein beliebiger Ordner mit .vndext- oder .zip-Dateien. Das Programm liest von jeder Datei nur params.json und die thumb.png der Bausteine (Cache nach Dateiname, Größe und Änderungszeit); der eigentliche Import läuft erst, wenn ein Baustein gewählt wird.

  • Mitgeliefert ist das Start-Theme „VN Studio“ (assets/starter-themes/). Gibt es zu einer Datei Name.vndext eine Zwillingsdatei Name.en.vndext, zeigt das Programm in nicht deutscher Oberfläche die englische.
  • Pakete mit Fehlern (kein ZIP, keine params.json, keine Bausteine) fehlen im Katalog; die Statuszeile nennt die Zahl der übersprungenen Dateien („kein gültiges Paket“).
  • Aus der Galerie lädt der Knopf „In Themes-Ordner“ ein Paket mit seinem Galerie-Namen als .vndext in den Ordner. Dateinamen werden dabei auf Buchstaben, Zahlen und .-_ () gekürzt (höchstens 80 Zeichen).

Paket-Werkzeug#

Die Erweiterung VN Paket-Werkzeug (vn-paketwerkzeug) verarbeitet viele Pakete auf einmal. Sie liest die Dateien nur, ändert das Programm nicht und zeigt je Paket: Baustein, Theme-Paket, Werkzeug oder defekt. Befunde (je „Hinweis“ oder „Fehler“):

  • Bild-Vorgaben oder url(file:///…), die auf den Rechner des Autors zeigen
  • Bootstrap-4-Merkmale (data-toggle, ml-/mr-, text-left …)
  • jQuery im Skript (läuft nur im Bootstrap-Modus „aus dem Theme“)
  • PHP im Baustein (die Seite muss .php heißen)
  • eigene Skript-Blöcke und Verweise auf externe Adressen (brauchen Internet beim Besucher)
  • Plugin-Dateien (werden nur im Bootstrap-Modus „aus dem Theme“ genutzt)
  • fehlendes Vorschaubild thumb.png

Aktionen: bereinigte .vndext-Dateien in einen Ordner schreiben (die Originale bleiben unberührt; entfernt werden lokale Bildpfade, url(file:///…) und Fremdkennzeichnungen) oder alle ausgewählten Pakete in einem Zug in die Bibliothek des offenen Projekts legen (Theme-Pakete mit allen Bausteinen, ein gleicher Alias ersetzt den bisherigen Eintrag; benötigt das Programmfeld ctx.blocks.importToLibrary). Siehe auch Erweiterungen.

Beispiel: ein minimales Theme-Paket#

Das Paket besteht aus Menü, Hero und Fußzeile, einem gemeinsamen CSS und einem Bild. Es wurde im Programm importiert und exportiert; Menü und Fußzeile standen im Export oben bzw. unten, das Bild wurde zu assets/images/foto.jpg und das Theme-CSS stand vor dem Block-CSS.

Dateien

text
mini-theme.vndext
  params.json
  thumbnail.jpg
  plugins/theme/css/style.css
  components/_images/foto.jpg
  components/menu1/{template.html, style.less, thumb.png}
  components/hero1/{template.html, style.less, thumb.png}
  components/footer1/{template.html, style.less, thumb.png}

params.json

json
{
  "name": "Mini Theme",
  "title": "Mini Theme",
  "alias": "mini-theme",
  "components": [
    { "path": "components/menu1", "_group": "Menü", "_title": "Menü (einfach)" },
    { "path": "components/hero1", "_group": "Header", "_title": "Hero mit Hintergrundbild" },
    { "path": "components/footer1", "_group": "Footer", "_title": "Footer" }
  ]
}

plugins/theme/css/style.css

css
.mini { font-family: "Segoe UI", Arial, sans-serif; color: #1f2937; }
.mini h1, .mini h2 { margin: 0 0 .5em; line-height: 1.15; }
.mini .btn-mini { display: inline-block; padding: .6rem 1.4rem; border-radius: 999px; background: #0f766e; color: #fff; text-decoration: none; }

components/menu1/template.html (seitenweit, Gruppe menu)

html
<section class="mini mini-menu" global once="menu">
  <vn-parameters>
    <header>Farben</header>
    <input type="color" title="Hintergrund" name="barBg" value="#ffffff">
    <input type="checkbox" title="Beim Scrollen oben festhalten" name="sticky" checked>
  </vn-parameters>
  <nav class="navbar navbar-expand-lg" vn-class="{'navbar-fixed-top': sticky}">
    <div class="container">
      <a class="navbar-brand" href="index.html">Mein Betrieb</a>
      <ul class="navbar-nav ms-auto flex-row gap-3">
        <li class="nav-item"><a class="nav-link" href="index.html">Start</a></li>
        <li class="nav-item"><a class="nav-link" href="kontakt.html">Kontakt</a></li>
      </ul>
    </div>
  </nav>
</section>

components/menu1/style.less

less
.navbar {
  background: @barBg;
  box-shadow: 0 1px 0 rgba(0, 0, 0, 0.08);
}

components/hero1/template.html (Hintergrund-Widget, Bildfeld mit Vorgabe aus dem Paket)

html
<section class="mini mini-hero">
  <vn-parameters>
    <header>Größe</header>
    <input type="range" inline title="Abstand oben" name="paddingTop" min="2" max="16" step="1" value="8">
    <input type="range" inline title="Abstand unten" name="paddingBottom" min="2" max="16" step="1" value="8">

    <header>Anzeigen</header>
    <input type="checkbox" title="Bild neben dem Text" name="showImage" checked>
    <select title="Ausrichtung" name="align">
      <option value="left" selected>Links</option>
      <option value="center">Zentriert</option>
    </select>

    <header>Farben</header>
    <fieldset type="background" name="bg">
      <input type="image" title="Bild" value="">
      <input type="color" title="Farbe" value="#e6f4f1" selected>
    </fieldset>
    <input type="color" title="Textfarbe" name="textColor" value="#1f2937">
    <input type="image" title="Foto" name="photo" value="../_images/foto.jpg">
  </vn-parameters>
  <div class="container">
    <div class="row align-items-center">
      <div class="col-lg-7">
        <h1>Willkommen in unserem Betrieb</h1>
        <p>Hier steht ein kurzer Text. Klicken Sie hinein, um ihn zu ändern.</p>
        <a class="btn-mini" href="kontakt.html">Kontakt aufnehmen</a>
      </div>
      <div class="col-lg-5" vn-if="showImage">
        <img src="{{photo}}" alt="" class="img-fluid">
      </div>
    </div>
  </div>
</section>

components/hero1/style.less

less
padding-top: (@paddingTop * 1rem);
padding-bottom: (@paddingBottom * 1rem);
color: @textColor;
text-align: ~"@{align}";
& when (@bg-type = 'color') { background-color: @bg-value; }
& when (@bg-type = 'image') { background-image: url(@bg-value); background-size: cover; background-position: center; }

components/footer1/template.html (seitenweit, Gruppe footers)

html
<section class="mini mini-footer" global once="footers">
  <vn-parameters>
    <header>Farben</header>
    <input type="color" title="Hintergrund" name="bg" value="#134e4a">
  </vn-parameters>
  <div class="container py-4">
    <p class="mb-0">© Mein Betrieb · <a href="impressum.html">Impressum</a></p>
  </div>
</section>

components/footer1/style.less

less
background: @bg;
color: #ffffff;
a { color: #ffffff; }

Paket bauen (Python, nur die Standardbibliothek und Pillow für die Bilder)

python
import io, json, zipfile
from PIL import Image

def bild(w, h, farbe, fmt):
    b = io.BytesIO(); Image.new('RGB', (w, h), farbe).save(b, fmt); return b.getvalue()

komponenten = [('menu1', 'Menü', 'Menü (einfach)'),
               ('hero1', 'Header', 'Hero mit Hintergrundbild'),
               ('footer1', 'Footer', 'Footer')]
params = {'name': 'Mini Theme', 'title': 'Mini Theme', 'alias': 'mini-theme',
          'components': [{'path': 'components/' + n, '_group': g, '_title': t} for n, g, t in komponenten]}

with zipfile.ZipFile('mini-theme.vndext', 'w', zipfile.ZIP_DEFLATED) as z:
    z.writestr('params.json', json.dumps(params, ensure_ascii=False, indent=2))
    z.write('src/plugins/theme/css/style.css', 'plugins/theme/css/style.css')
    z.writestr('components/_images/foto.jpg', bild(800, 600, (15, 118, 110), 'JPEG'))
    for n, g, t in komponenten:
        z.write('src/components/%s/template.html' % n, 'components/%s/template.html' % n)
        z.write('src/components/%s/style.less' % n, 'components/%s/style.less' % n)
        z.writestr('components/%s/thumb.png' % n, bild(320, 180, (15, 118, 110), 'PNG'))
    z.writestr('thumbnail.jpg', bild(640, 360, (15, 118, 110), 'JPEG'))

Ergebnis im Export (gekürzt): Menü zuerst, Hero, Fußzeile zuletzt; jede Instanz mit eigener Klasse; Theme-CSS vor dem Block-CSS.

html
<section class="mini mini-menu vn-imp-mini-theme-menu1-bmw3s2mqu4wym" global="" once="menu" id="blk-bmw3s2mqu4wym">…</section>
<section class="mini mini-hero vn-imp-mini-theme-hero1-bmw3s2mqdbf95" id="blk-bmw3s2mqdbf95">
  … <img src="assets/images/foto.jpg" alt="" class="img-fluid"> …
</section>
<section class="mini mini-footer vn-imp-mini-theme-footer1-bmw3s2mqy6gzj" global="" once="footers" id="blk-bmw3s2mqy6gzj">…</section>
css
/* style.css (Anfang) */
/* plugins/theme/css/style.css */
.mini { font-family: "Segoe UI", Arial, sans-serif; color: #1f2937; }
…
.vn-imp-mini-theme-hero1-bmw3s2mqdbf95 { padding-top: 8rem; padding-bottom: 8rem; color: #1f2937; text-align: left; background-color: #e6f4f1; }

Prüfliste vor dem Weitergeben#

  • Paket in einem neuen Projekt importieren (Bibliothek) und jeden Baustein einfügen. Schauen Sie sich die Eigenschaften-Gruppen an: jede header-Zeile erscheint als Gruppe.
  • Exportieren und die Seite im Browser öffnen; Menü und Fußzeile prüfen.
  • Keine file:///-Pfade, keine festen IDs, keine Verweise auf fremde Server (Schriften, Skripte, Bilder).
  • Pro Baustein ein thumb.png (Breite etwa 480 px) und im Paket ein thumbnail.jpg, wenn es in die Online-Galerie soll.
  • Bilder und Schriften als Dateien im Paket; Videos nicht.
  • Beschreibung der Beispiel-Texte ohne echte Namen und Adressen (example.com).