Erweiterungen (.vndtool)
Paketaufbau und manifest.json einer Werkzeug-Erweiterung, Lebenszyklus, Werkzeugfenster, die komplette Programm-Schnittstelle ctx, PHP-Server-Teile, Bauen, Galerie-Upload, Sicherheitsregeln und eine vollständige Hallo-Erweiterung.
Überblick#
Eine Erweiterung ist ein zusätzliches Werkzeug, das nicht zum Programm gehört. Sie steht als Datei *.vndtool (eine ZIP-Datei) zur Verfügung und erscheint nach der Installation als Kachel im Werkzeug-Fenster (Menü Werkzeuge › VN-Werkzeuge öffnen). Sie läuft in allen Editionen und lässt sich wieder entfernen. Eine Erweiterung kann
- ein eigenes Fenster mit beliebiger Oberfläche öffnen (
ctx.openToolWindow), - das Projekt lesen und in einem festen Umfang ändern (
ctx.project,ctx.blocks), - eigene Bausteine mitbringen und einfügen (
ctx.blocks.importPackage), - beim Export Dateien und Code in die fertige Website legen, auch PHP-Server-Teile (
ctx.project.exportContribution), - Zugangsdaten sicher im Programm-Profil ablegen (
ctx.project.secrets), - die im Programm eingetragenen KI-Zugänge nutzen (
ctx.project.ai).
Installation und Ablageort: „+ Erweiterung installieren…“ im Werkzeug-Fenster (oder Datei auf das Fenster ziehen, oder Installation aus der Werkzeug-Galerie). Das Programm entpackt das Paket in <Programm-Profil>/extensions/<id>/ (unter Windows %APPDATA%), nicht ins Projekt. Beim Weitergeben eines Projekts werden Erweiterungen nicht mitgegeben; ein Programm-Update lässt sie unberührt.
Paketaufbau#
manifest.json Pflicht, steht im ZIP ganz vorn
tool.js Pflicht (oder die Datei, die manifest.json unter "main" nennt): ES-Modul
payload.js optional: PHP-/Dateiinhalte für den Export als JavaScript-Modul (erzeugt von make-payload.py)
dom.js optional: Hilfsfunktionen für die Oberfläche (h(), clear(), debounce(), sleep())
style.css optional: Stil des Werkzeugfensters
*.vndext optional: mitgelieferte Bausteine (Paketformat siehe Kapitel Pakete)
thumbnail.jpg Vorschau für die Galerie (nur dort gelesen; muss IM Paket liegen)
icon.svg, ... beliebige Beigaben (Bilder, weitere .js-Module, Texte)Beispiel vn-ical.vndtool (wörtlich aus dem ZIP): manifest.json, dom.js, ical-block.vndext, payload.js, style.css, thumbnail.jpg, tool.js. Das Paket der Beispiel-Erweiterung ist noch kleiner: manifest.json, icon.svg, tool.js.
manifest.json#
Syntax
{
"id": "hallo-erweiterung",
"name": "Hallo-Erweiterung",
"name_en": "Hello extension",
"name_fr": "Extension Bonjour",
"version": "1.0.0",
"icon": "HI",
"description": "Zeigt die Seiten des Projekts, merkt sich einen Gruß und legt ihn beim Export als Datei ab.",
"description_en": "Shows the pages of the project, remembers a greeting and writes it to a file on export.",
"description_fr": "Affiche les pages du projet, mémorise un message d'accueil et l'écrit dans un fichier lors de l'export.",
"author": "Beispiel GmbH",
"main": "tool.js"
}Felder
| Feld | Typ | Standard | Bedeutung |
|---|---|---|---|
id | Text | – | Pflicht. 2–48 Zeichen, a-z, 0-9, -, _, beginnt mit Buchstabe oder Ziffer. Ist der Ordnername im Profil und die Kennung für Einstellungen, Geheimnisse und Export-Beitrag. Darf sich nie ändern: sonst wird ein Update als zweites Werkzeug installiert. IDs eingebauter Werkzeuge sind gesperrt (die Installation wird abgelehnt, die Dateien werden wieder entfernt) |
name | Text | – | Pflicht. Name der Kachel (deutsch) |
name_en, name_fr, name_<sprache> | Text | – | Name in anderer Programmsprache. Es gilt die Fassung der Programmsprache, sonst die englische, sonst die deutsche. Nur Felder der Form name_xx mit zwei bis drei Buchstaben, höchstens 400 Zeichen |
description, description_<sprache> | Text | leer | Beschreibung auf der Kachel; gleiche Sprachregel |
version | Text | leer | Wird auf der Kachel angezeigt und für den Update-Vergleich mit der Galerie benutzt. Bei jeder Änderung erhöhen |
icon | Text | Kürzel aus dem Namen | Kurzes Zeichen im blauen Symbol der Kachel, höchstens 4 Zeichen (auch Emoji). Ohne Angabe bildet das Programm ein Kürzel aus den ersten Buchstaben der ersten Wörter („VN SEO“ → „SE“) |
author | Text | leer | Autor |
main | Text | tool.js | Programmdatei. Muss im Paket liegen und innerhalb des Ordners bleiben |
tool.js#
Ein ES-Modul. export default liefert ein Objekt mit run(ctx) oder direkt eine Funktion. run läuft bei jedem Klick auf die Kachel.
Syntax
export default {
run(ctx, opts) {
// Oberfläche bauen, ctx.openToolWindow(titel, element, { large }) aufrufen
},
};Weitere Dateien lassen sich normal importieren (import { h } from './dom.js?v=4'). Fehlt export default oder ist es weder Objekt mit run noch Funktion, bleibt die Kachel mit „⚠ Konnte nicht geladen werden“ und der Meldung stehen.
payload.js und dom.js#
Das sind Namenskonventionen der vorhandenen Erweiterungen, keine Pflichtdateien: payload.js exportiert PAYLOAD, ein Objekt { "api.php": "<?php …", "lib.php": "…" } mit den Dateien des Server-Teils (siehe PHP-Server-Teile). dom.js enthält den Helfer h('div.klasse#id', { attr, onclick, html }, kinder…), clear(el), debounce(fn, ms) und sleep(ms); er ist in allen Erweiterungen identisch (Vorlage: extensions-src/vn-ical/dom.js).
Lebenszyklus#
- Start: Das Programm liest
ext:list(alle Ordner unterextensions/mit gültigermanifest.json, dereniddem Ordnernamen entspricht) und lädt jedesmainperimport()mit der Adresse…/tool.js?v=<Änderungszeit der Datei>. Gelingt das, wird das Werkzeug mit Name, Beschreibung, Version und Symbol im Register eingetragen; sonst als defekt (rote Meldung, entfernbar). - Klick auf die Kachel:
run(ctx, opts)wird aufgerufen.ctxist für jede Erweiterung eine eigene Sicht: zusätzlichctx.extensionund ein auf die eigeneidbegrenztesctx.project. - Fenster:
ctx.openToolWindowschließt ein schon offenes Werkzeugfenster und die Kachel-Übersicht und zeigt das neue Fenster (siehe unten). - Installation, Update, Entfernen: Beim Installieren wird erst in einen Zwischenordner entpackt, dann ersetzt es eine vorhandene Fassung; ein defektes Paket zerstört nie eine laufende Erweiterung. Das Entfernen (Papierkorb auf der Kachel) löscht den Ordner. Nach einem Update meldet das Programm „Bitte VN-Designer neu starten, damit alle Teile der neuen Version geladen werden“.
Werkzeugfenster#
ctx.openToolWindow#
Öffnet das verschiebbare Fenster der Erweiterung unten rechts (am Kopf ziehen, mit ✕ schließen). Es gibt immer nur ein Werkzeugfenster; ein neuer Aufruf ersetzt das alte.
Syntax
ctx.openToolWindow(titel, element, { large: true })| Parameter | Typ | Bedeutung |
|---|---|---|
titel | Text | Titel im Kopf des Fensters |
element | DOM-Element | Inhalt. Das Programm hängt es in das Fenster; Sie bauen es selbst |
large | Wahrheitswert | Größeres, frei skalierbares Fenster (bis 1000 × 820 px, mittig oben), ohne eigenes Innenpolster; für Werkzeuge mit mehrspaltiger Oberfläche |
Beispiel
const box = document.createElement('div');
box.textContent = 'Hallo ' + (ctx.projectDir || '(kein Projekt)');
ctx.openToolWindow('Mein Werkzeug', box);ctx.closeToolWindow#
ctx.closeToolWindow() schließt das Fenster. Rückgabe: nichts.
ctx.askConfirm#
Bestätigungsdialog im Stil des Programms. await ctx.askConfirm(text) liefert true (Ja) oder false. Benutzen Sie ihn für unumkehrbare Aktionen statt window.confirm.
Die Schnittstelle ctx#
ctx hat folgende Einträge. Fehlt ein Eintrag (ältere Programmversion), prüfen Sie ihn vor dem Benutzen (if (!ctx.project || !ctx.project.exportContribution) …) und melden Sie das freundlich.
| Eintrag | Bedeutung |
|---|---|
ctx.projectDir | Ordner des geöffneten Projekts (Text) oder null |
ctx.getPages() | Die Seiten des Projekts mit allen Blöcken, auch mit ungespeicherten Änderungen. Das sind die Arbeitsobjekte des Editors, keine Kopien: nur lesen. Eine Seite hat u. a. id, name, slug, blocks, publish; ein Block id, alias, schemaEntry, values |
ctx.getGlobalBlocks() | Die seitenweiten Blöcke (Menü, Fußzeile), gleiche Form wie Blöcke einer Seite, ebenfalls nur lesen |
ctx.switchToPage(id) | Wechselt im Editor zur Seite mit dieser id |
ctx.askConfirm(text) | siehe oben |
ctx.openToolWindow, ctx.closeToolWindow | siehe oben |
ctx.extension | { id, version, baseUrl } der eigenen Erweiterung; baseUrl ist die Adresse des Erweiterungs-Ordners mit Schrägstrich am Ende |
ctx.project | Projekt-Schnittstelle, siehe unten (Kopien zum Lesen, Erlaubnisliste zum Ändern) |
ctx.blocks | Block-Schnittstelle, siehe unten |
Zusätzlich steht window.vnDesigner zur Verfügung (Programm-Brücke zum Hauptprozess). Von den Erweiterungen des Programms benutzt werden: saveAsset(projectDir, unterordner, dateiname, arrayBuffer, { keepName }) (Datei unter assets/<unterordner>/ im Projekt ablegen, liefert { filename, path, relativePath, fileUrl }; erlaubt sind Bild-, Schrift-, css- und js-Dateien bis 15 MB), listAssetImages(projectDir) (Bilder unter assets/images/), openExternal(url) (nur http/https im Standardbrowser), loadSmtpConfig(projectDir) (die im Programm eingetragenen SMTP-Zugangsdaten), netCheckUrl({ url, method, timeoutMs }) (prüft eine Adresse ohne interne Ziele), downloadGoogleFont(…) und vnpdfSave(…). Diese Funktionen gehören zum Programm und können sich ändern; Erweiterungen, die Sie weitergeben, bleiben möglichst bei ctx.
ctx.project.getInfo#
Eine Kopie der Projektdaten.
Syntax und Rückgabe
const info = ctx.project.getInfo();
// {
// projectDir, title, activePageId,
// site: { siteUrl, lang, metaDescription, favicon, seo, translateActive, cookieConsentActive, localFonts },
// pages: [ { id, name, slug, seoTitle, metaDescription, ogImage, lang, publish, seo, headExtra, bodyExtra, blockCount } ]
// }seo ist null, solange das SEO-Werkzeug nichts eingestellt hat. localFonts ist die Zahl der eigenen Schriften.
ctx.project.buildFiles#
Baut die fertigen Seiten im Speicher, genau wie der Export sie schreiben würde, ohne etwas zu speichern (nur abgehakte Seiten).
const r = await ctx.project.buildFiles();
// { files: [ { filename: 'index.html', pageId, html } ], extraFiles: [ { filename: 'sitemap.xml', text } ], css: '…fertiges style.css…' }extraFiles enthält sitemap.xml, robots.txt und llms.txt, soweit das SEO-Werkzeug sie einschaltet. Der Beitrag der Erweiterungen (Dateien, head, bodyEnd) ist in buildFiles() nicht enthalten.
ctx.project.updatePage#
ctx.project.updatePage(id, patch) ändert Felder einer Seite und liefert true (Seite gefunden) oder false. Erlaubt sind nur diese Felder, jeweils Text mit dieser Höchstlänge: seoTitle (300), metaDescription (600), ogImage (500), lang (20), headExtra (400000), bodyExtra (400000); dazu seo (Objekt, wird normalisiert; null entfernt es). Die Änderung gilt sofort im Projekt; der Nutzer speichert danach wie gewohnt.
ctx.project.updatePage(info.pages[0].id, { seoTitle: 'Startseite | Mein Betrieb', metaDescription: 'Kurzbeschreibung …' });ctx.project.updateSite#
ctx.project.updateSite(patch) ändert die Website-Einstellungen: siteUrl (300 Zeichen), metaDescription (600), lang (20) und seo (Objekt oder null). Rückgabe true.
ctx.project.getGlobalHtml und setGlobalHtml#
getGlobalHtml() liefert { headExtra, bodyStart, bodyExtra }, die „Globalen HTML-Einfügungen“ (Zahnrad in der Leiste). setGlobalHtml(patch) ändert eines oder mehrere dieser Felder (Text, je höchstens 400000 Zeichen) in einem Rückgängig-Schritt und liefert true. Das Feld für Code vor dem Dokumenttyp (doctypeExtra) ist nicht erreichbar.
ctx.project.listImages und setImageAlt#
await ctx.project.listImages() liefert alle Bilder der Seiten und der seitenweiten Blöcke mit ihrem wirksamen Alt-Text:
// [ { blockId, blockLabel, pageId, pageName, global, metaId: 'k:photo', src: 'file:///…/foto.jpg', alt: '' } ]ctx.project.setImageAlt(blockId, metaId, alt) setzt den Alt-Text (höchstens 300 Zeichen) und liefert true.
ctx.project.assetSizes#
await ctx.project.assetSizes(['assets/images/foto.jpg']) liefert die Dateigrößen unterhalb von assets/ und publish/: { "assets/images/foto.jpg": { "size": 8228 }, "assets/nix.png": null }. Höchstens 2000 Pfade; andere Pfade ergeben null.
ctx.project.addPage#
Legt eine neue Seite mit einem Block „Eigener HTML-Code“ an.
const r = ctx.project.addPage({ name: 'Impressum', slug: 'impressum.html', html: '<section><h1>Impressum</h1></section>', label: 'Impressum' });
// { ok: true, pageId } | { ok: false, exists: true, pageId } | { ok: false, error: 'Ungültiger Dateiname' }slug muss ^[a-z0-9_-]{1,60}\.(html|php)$ erfüllen; html höchstens 400000 Zeichen. Eine bestehende Seite wird nie überschrieben (dann exists: true). Die Seite wird nicht geöffnet.
ctx.project.newEmptyPage#
Legt eine leere Seite an und wechselt zu ihr: ctx.project.newEmptyPage({ name, slug }) liefert { ok, pageId, slug }. Der Dateiname wird bei Bedarf eindeutig gemacht (-2, -3 …). Danach landen mit ctx.blocks.addFromCatalog eingefügte Blöcke auf dieser Seite.
ctx.project.findInBlocks#
await ctx.project.findInBlocks(muster) sucht ein Muster (Text eines regulären Ausdrucks, ohne Beachtung der Groß-/Kleinschreibung, höchstens 400 Zeichen) im fertigen HTML und CSS aller Blöcke:
// [ { pageId, pageName, global, blockId, blockLabel, where: ['HTML', 'CSS'], sample } ]ctx.project.selectBlock und showPage#
ctx.project.selectBlock(pageId, blockId) wechselt zur Seite, wählt den Block und scrollt ihn in die Mitte. await ctx.project.showPage(pageId) zeigt eine Seite und wartet, bis die Arbeitsfläche alle ihre Blöcke gezeichnet hat; Voraussetzung für Messungen an der fertigen Darstellung. ctx.project.canvas() liefert das Element der Arbeitsfläche (nur lesen, z. B. getComputedStyle); jeder Block steht dort in .canvas-block[data-block-id].
ctx.project.colorUsage und replaceColors#
ctx.project.colorUsage() liefert alle einstellbaren Farben:
// [ { color: '#e6f4f1', art: 'bg', ort: 'Hintergrund', pageId, pageName, global, blockId, blockLabel } ]
// art: 'field' | 'bg' | 'text' | 'icon' | 'site'Erfasst werden Farbfelder und Hintergründe der Blöcke, color: in formatiertem Text, Symbolfarben, das Eigene CSS und der Nach-oben-Knopf. Farben, die fest im Theme-CSS stehen, fehlen.
ctx.project.replaceColors({ '#e6f4f1': '#ffeecc' }, { blockIds, site }) ersetzt in einem Zug (ohne Kettenwirkung A→B→C) und in einem Rückgängig-Schritt. blockIds beschränkt auf diese Blöcke; site: true schließt das Eigene CSS und den Nach-oben-Knopf ein. Anker (href="#abc"), Selektoren, Zeichenketten und url(#…) bleiben unberührt. Rückgabe { changed, blocks } (im Test: { "changed": 2, "blocks": 2 }).
ctx.project.settings#
Eigene Einstellungen der Erweiterung, im Projekt gespeichert (siteSettings.extensions[<id>].settings).
const s = ctx.project.settings.get(); // Kopie oder null
ctx.project.settings.set({ gruss: 'Hallo' }); // ersetzt alles; set(null) löschtDie Werte müssen JSON-fähig sein. Der Nutzer muss das Projekt noch speichern.
ctx.project.exportContribution#
Was die Erweiterung beim Export beisteuert.
Syntax
ctx.project.exportContribution.set({
head: '<link rel="stylesheet" href="assets/hallo-erweiterung/stil.css">',
bodyEnd: '<script src="assets/hallo-erweiterung/skript.js"></script>',
files: [ { path: 'assets/hallo-erweiterung/gruss.txt', text: 'Hallo\n' } ],
});
ctx.project.exportContribution.get(); // Kopie oder null
ctx.project.exportContribution.set(null); // Beitrag entfernenFelder und Grenzen
| Feld | Bedeutung |
|---|---|
head | Code am Ende von <head> auf jeder Seite (hinter dem Stylesheet, vor dem Code der Globalen Einfügungen); höchstens 20000 Zeichen |
bodyEnd | Code am Ende von <body> (hinter den Skripten des Programms, vor dem Code der Globalen Einfügungen); vom Cookie-Hinweis nicht gesperrt; höchstens 20000 Zeichen |
files | Textdateien { path, text }. Der Pfad muss assets/<eigene id>/… lauten (Zeichen A-Za-z0-9._/-, höchstens 120 nach der Kennung, kein ..). Höchstens 30 Dateien (weitere werden stillschweigend abgeschnitten), je Datei höchstens 400000 Zeichen |
Ein Verstoß gegen Pfad oder Dateigröße wirft eine Ausnahme („Ungültige Datei im Export-Beitrag“). Der Beitrag wird in der Projektdatei gespeichert und nur ausgegeben, solange die Erweiterung installiert und geladen ist. Setzen Sie ihn auf null oder entfernen Sie die Erweiterung, entfernt der nächste Export die früher geschriebenen Dateien und leere Ordner (im Test bestätigt). Auf dem Server bereits liegende Dateien löscht das Programm nicht.
In files[].text ersetzt der Export die Platzhalter {{secret:NAME}} und {{secret-php:NAME}} durch Geheimnisse, siehe nächster Eintrag. In head und bodyEnd gibt es keine Ersetzung.
ctx.project.secrets#
Geheimnisse (z. B. Passwort-Prüfwerte) liegen im Programm-Profil, nicht im Projekt, verschlüsselt, wenn Windows das anbietet.
await ctx.project.secrets.set('hash', pruefwert); // { ok: true }; set(name, null) oder '' löscht
const namen = await ctx.project.secrets.names(); // ['hash', 'salt']name: 1–40 Zeichen aus A-Za-z0-9_; wert: Text, höchstens 500 Zeichen. Geheimnisse sind nie zurücklesbar; nur names() verrät, welche es gibt. Der Export setzt sie in Dateien des Beitrags ein:
| Platzhalter | Ersetzung |
|---|---|
{{secret:NAME}} | der Wert unverändert |
{{secret-php:NAME}} | der Wert mit maskiertem Rückwärtsschrägstrich, Anführungszeichen und Dollarzeichen (\\, \", \$), für einen PHP-String in doppelten Anführungszeichen |
Ein fehlendes Geheimnis ergibt einen leeren Text.
Beispiel (aus vn-ical, gekürzt): Das Passwort der Verwaltung verlässt das Programm nie im Klartext. Das Werkzeug berechnet Salz und PBKDF2-Prüfwert und legt beide als Geheimnisse ab; die Datei admin-config.php im Beitrag enthält nur die Platzhalter.
const bits = await crypto.subtle.deriveBits({ name: 'PBKDF2', salt: new TextEncoder().encode(salz), iterations: 100000, hash: 'SHA-256' }, key, 256);
await ctx.project.secrets.set('salt', salz);
await ctx.project.secrets.set('hash', hex(bits));
ctx.project.exportContribution.set({ files: [
{ path: 'assets/vn-ical/admin-config.php',
text: '<?php\n$admin_pbkdf2_salt = "{{secret-php:salt}}";\n$admin_pbkdf2_hash = "{{secret-php:hash}}";\n' },
] });ctx.project.ai#
Nutzt die im Programm eingetragenen KI-Zugänge (Einstellungen › KI). Der Text verlässt den Rechner Richtung Anbieter. Zeigen Sie das dem Nutzer.
| Eintrag | Bedeutung |
|---|---|
await ai.providers() | Die eingerichteten Anbieter: [ { id, label } ] (leer, wenn keiner eingetragen ist) |
await ai.ask({ providerId, systemPrompt, userPrompt, model, onDelta, signal, onThink }) | Stellt eine Frage; liefert den Antworttext. model überschreibt das Modell nur für diese Anfrage. onDelta(stück, gesamt) meldet die Antwort fortlaufend (Streaming; eine an der Längenbegrenzung abgeschnittene Antwort wird dann nicht als Fehler geworfen, prüfen Sie selbst). signal ist ein AbortSignal, das die Anfrage wirklich abbricht. onThink(zeichen) meldet die Denkphase lokaler KI-Modelle (das Nachdenken wird für Werkzeuge ausgeschaltet) |
ai.openSettings() | Öffnet den Dialog der KI-Schlüssel |
ai.streaming, ai.thinking | true: ask kennt onDelta, signal und onThink (Feature-Test) |
ai.speech, await ai.speechProvider() | Spracheingabe: speechProvider() liefert { id, label } des Anbieters (Groq zuerst, dann ChatGPT) oder null |
await ai.transcribe({ audio, language, prompt, signal }) | Aufnahme (Blob, z. B. audio/webm) → erkannter Text. Ohne Groq- oder ChatGPT-Zugang wirft es eine Ausnahme |
const anbieter = await ctx.project.ai.providers();
if (!anbieter.length) { ctx.project.ai.openSettings(); return; }
const text = await ctx.project.ai.ask({ providerId: anbieter[0].id, systemPrompt: 'Antworte kurz.', userPrompt: 'Schlage einen Seitentitel vor.' });ctx.blocks.importPackage#
Importiert ein Baustein-Paket (.vndext mit einer Komponente, als ArrayBuffer) und fügt es auf der aktuellen Seite ein. Das Programm meldet Fehler selbst.
const res = await fetch(ctx.extension.baseUrl + 'ical-block.vndext');
const ok = await ctx.blocks.importPackage(await res.arrayBuffer(), { position: 'end' }); // true | falseopts.position: 'end' (ans Ende der Seite), 'start', 'after' (hinter den gewählten Block), eine Zahl (Stelle, 0 = ganz oben); ohne Angabe hinter den gewählten Block. Ein Paket mit mehreren Komponenten wird nicht unterstützt (dafür importToLibrary). Ein seitenweiter Baustein (global) ersetzt den vorhandenen seiner Gruppe.
ctx.blocks.importToLibrary#
Legt ein Paket in die Bibliothek des Projekts, nicht auf die Seite. Theme-Pakete kommen mit allen Bausteinen hinein; ein gleicher Alias ersetzt den vorhandenen Eintrag.
const r = await ctx.blocks.importToLibrary(buffer); // { ok: true, count: 3 } | { ok: false, message }Es wird nichts angezeigt; die Erweiterung zeigt das Ergebnis selbst.
ctx.blocks.findByAlias und setValues#
ctx.blocks.findByAlias(alias) findet die Blöcke dieses Bausteins auf der aktuellen Seite: [ { id, selected, values } ] (values ist eine Kopie, selected ist wahr beim gewählten Block). Der Alias ist der des Pakets (bei einem Einzelbaustein params.alias, bei einem Theme-Paket <alias>-<Ordner>). await ctx.blocks.setValues(blockId, patch) setzt Werte des Eigenschaften-Panels (patch = { schluessel: wert }), zeichnet den Block neu und legt einen Rückgängig-Schritt an; Rückgabe true/false.
const liste = ctx.blocks.findByAlias('vn-ical');
if (liste.length) await ctx.blocks.setValues((liste.find((b) => b.selected) || liste[0]).id, { accent: '#15803d' });ctx.blocks.describe, selected, pageBlocks#
ctx.blocks.describe(blockId) und ctx.blocks.selected() (gewählter Block oder null) beschreiben die Eigenschaften eines Blocks, wie das Panel sie kennt; ctx.blocks.pageBlocks() listet die Blöcke der aktuellen Seite.
ctx.blocks.describe(id);
// { blockId, label, alias, isGlobal, groups: ['Größe', …],
// fields: [ { key, label, type, group, options?, min?, max?, step?, condition? } ],
// values: { paddingTop: '8', showImage: true, bg: { type: 'color', value: '#e6f4f1', parallax: false } } }
ctx.blocks.pageBlocks(); // [ { blockId, label, alias } ]type ist text, textarea, checkbox, color, range, select (options: [[Wert, Beschriftung], …]), image oder background. Zu große Werte (über 2000 Zeichen) fehlen in values.
ctx.blocks.catalog und addFromCatalog#
await ctx.blocks.catalog() listet alle einfügbaren Bausteine (Themes-Ordner mit dem Start-Theme und die Bibliothek): [ { key, source: 'theme'|'library', theme, title, group, once } ] (once = 'menu'/'footers' bei seitenweiten Bausteinen, sonst leer). await ctx.blocks.addFromCatalog(key, opts) fügt einen davon ein (opts.position wie bei importPackage) und liefert die Kennung des Blocks oder null.
ctx.blocks.texts#
Die bearbeitbaren Texte der aktuellen Seite (samt Menü und Fußzeile) lesen und schreiben.
const alle = ctx.blocks.texts.list();
// [ { blockId, blockLabel, blockAlias, textId: 't0', tag: 'a', html: 'Mein Betrieb', text: 'Mein Betrieb', isLink: true } ]
const n = await ctx.blocks.texts.set([ { blockId: alle[0].blockId, textId: alle[0].textId, text: 'Neu & besser' } ]); // 1list() liefert die Texte in Dokumentreihenfolge, nur von Blöcken, die gerade auf der Arbeitsfläche stehen. set(einträge) setzt je Eintrag html (wird wie beim Tippen bereinigt: Inline-Formatierung und Links) oder text (reiner Text, Zeichen maskiert, Zeilenumbrüche werden <br>), zeichnet die Blöcke neu, legt einen Rückgängig-Schritt an und liefert die Zahl der geänderten Texte.
ctx.blocks.images#
ctx.blocks.images.list() liefert die Bildplätze der Blöcke auf der Seite: [ { blockId, blockLabel, slot, kind: 'field'|'background'|'free', label, url, alt, w, h } ]. slot ist k:<Feld> (Bildfeld im Panel), b:<Feld> (Hintergrundbild) oder f:<Kennung> (freies Bild im Baustein); w/h die angezeigte Größe in px. await ctx.blocks.images.set([ { blockId, slot, url, alt } ]) setzt Bilder (url ist die fileUrl einer im Projekt gespeicherten Datei, alt optional, höchstens 300 Zeichen) in einem Rückgängig-Schritt und liefert die Zahl der gesetzten Bilder.
Weitere Einträge von ctx.blocks#
| Eintrag | Bedeutung |
|---|---|
addBlock(result, opts) | Fügt ein fertiges Importergebnis ({ status: 'ok', alias, schemaEntry, message }) ein. Es setzt einen vom Programm erzeugten schemaEntry voraus; Erweiterungen nehmen importPackage |
findGalleries(), updateGallery(blockId, result) | Gehören zum eingebauten Werkzeug VN Galerie (Galerie-Bausteine finden und ihre Bilder ersetzen); nicht für eigene Bausteine gedacht |
anim.targetAt(el), anim.selectedTargets(), anim.set(blockId, einträge), anim.play(blockId, cfgs), anim.mark(blockId, ids) | Gehören zum eingebauten Werkzeug VN Animation (Animationen für Texte und Bilder); interne Schnittstelle, kann sich ändern |
PHP-Server-Teile#
Eine Erweiterung kann auf der fertigen Website serverseitige Funktionen bereitstellen (Terminkalender, Gästebuch, Statistik …). Das Muster, das alle vorhandenen Erweiterungen benutzen:
- Die PHP-Dateien liegen im Quellordner der Erweiterung unter
payload/. Ein Skript (make-payload.py) liest sie und schreibtpayload.js: ein Modul, dasPAYLOADals Objekt{ "api.php": "…", "lib.php": "…" }exportiert. Dateien unterdata/unduploads/sowieconfig.phpbleiben draußen, weil sie erst auf dem Server entstehen. tool.jsimportiertPAYLOADund baut daraus den Export-Beitrag: jede Datei als{ path: 'assets/<id>/<name>', text }, dazu die erzeugteconfig.phpmit den Einstellungen des Nutzers und einadmin-config.phpmit Geheimnis-Platzhaltern.- Beim Export schreibt das Programm die Dateien in
publish/assets/<id>/. Der Nutzer lädtpublish/wie jede Website hoch.
Beispiel (aus vn-ical, gekürzt)
import { PAYLOAD } from './payload.js?v=5';
const ID = 'vn-ical';
function buildContribution(s) {
const base = 'assets/' + ID + '/';
const files = Object.keys(PAYLOAD).map((name) => ({ path: base + name, text: PAYLOAD[name] }));
files.push({ path: base + 'config.php', text: buildConfigPhp(s) });
files.push({ path: base + 'admin-config.php', text: buildAdminConfig(s) });
return { files };
}
ctx.project.exportContribution.set(s.enabled ? buildContribution(s) : null);Regeln für Server-Teile:
- Grenzen: höchstens 30 Dateien je Erweiterung, je Datei 400000 Zeichen. Ist der Server-Teil größer, fassen Sie Dateien zusammen. Der Beitrag steht in der Projektdatei (
siteSettings.extensions[<id>].contribution) und macht sie entsprechend größer. - Ordner
data/schützen: Das Programm schreibt keine.htaccessfür Beiträge. Der PHP-Code legt sie selbst an (vn-ical:Require all deniedsamt Ersatz für ältere Apache-Versionen, beim ersten Zugriff inlib.php). Pfade in Meldungen nie ausgeben. - Konfiguration beim Export erzeugen: Einstellungen des Nutzers gehören nicht in feste Dateien.
tool.jsbautconfig.phpjedes Mal neu aus den Einstellungen (als Nowdoc mit JSON, damit nichts maskiert werden muss) und setzt Geheimnisse über Platzhalter ein. - E-Mail-Versand: Das Programm schreibt die im Programm eingetragenen SMTP-Zugangsdaten beim Export nach
assets/vn-shared/config.php(nur wenn SMTP eingerichtet ist); PHP-Teile lesen sie mitdirname(__DIR__) . '/vn-shared/config.php'(Variablen$smtp_host,$smtp_port,$smtp_encryption,$smtp_username,$smtp_password,$smtp_from_email,$smtp_from_name,$hmac_secret). Siehe Veröffentlichen. - PHP 7.3 und neuer, auch 8.x. Prüfen Sie jede Datei mit
php -lund testen Sie mitphp -S 127.0.0.1:<Port>gegen den exportierten Ordner. - Datenbank und Besucherdaten nie im Beitrag ausliefern; Passwörter nur als PBKDF2-Prüfwert; Eingaben prüfen, Ausgaben maskieren, CSRF-Schutz, Sitzungs-Cookie
HttpOnly/SameSite, Begrenzung der Anmeldeversuche; keineval, keininnerHTMLmit Rohdaten. - Datenschutz: Keine Skripte, Schriften oder Bilder von Fremdservern in
head/bodyEndoder in der Oberfläche der Seite laden.
Bausteine in einer Erweiterung#
Eine Erweiterung liefert Bausteine als .vndext-Dateien im Paket mit (block/ im Quellordner, per make-payload.py zu <name>-block.vndext gepackt). Das Werkzeug fügt sie mit importPackage ein, später ändert es sie mit findByAlias und setValues. Der Alias in params.json des Bausteins ist die Kennung dafür (vn-ical). Der Baustein enthält nur die Oberfläche und das Skript der Seite; die Daten holt er über die Dateien im Beitrag. Texte, die später in die Seite eingehen, nehmen Sie als Eigenschaft des Bausteins (nie roh in ein data-…="{{x}}"; benutzen Sie {{vnEnc(x)}}).
Bauen, prüfen, ausliefern#
Paket bauen
python extensions-src/build-ext.py extensions-src/mein-werkzeug dist-ext/mein-werkzeug.vndtoolbuild-ext.py verlangt in manifest.json id und name, legt die Datei manifest.json ganz nach vorn ins ZIP und packt alle übrigen Dateien des Ordners. Eine Datei .vndignore (ein Name je Zeile, # für Kommentare) nennt Dateien und Ordner, die nicht ins Paket sollen (Quellordner payload/, block/, tests/, make-payload.py). Liegt ein Skript wie make-payload.py davor, führen Sie es vor dem Packen aus.
Prüfen
- Paket im Werkzeug-Fenster installieren, Kachel anklicken. Ein Fehler in
tool.jslässt die Kachel mit ⚠ und der Meldung stehen; so können Kunden sie entfernen. - Jede Funktion einzeln durchspielen, auch Fehlerfälle (kein Projekt offen, ältere Programmversion).
- Exportieren und das Ergebnis in
publish/im Browser bzw. mit PHP prüfen; die Datei und denbodyEnd-Code der Erweiterung suchen. - Beitrag auf
nullstellen und erneut exportieren: die Dateien müssen verschwinden.
Das Programm prüft beim Installieren: manifest.json muss vorhanden sein und gültiges JSON mit gültiger id und einem name enthalten, die Programmdatei muss im Paket liegen. Pfade im Paket, die aus dem Ordner herausführen (.., absolute Pfade, Laufwerksangaben), werden übersprungen. Entpackt höchstens 40 MB.
Galerie (zwei Server, gleiche Pakete)
| Galerie | Format und Regeln |
|---|---|
Werkzeug-Galerie (gallery-server-tools, Reiter „Werkzeuge“) | .vndtool hochladen (echtes ZIP mit gültiger manifest.json und Programmdatei, höchstens 100 MB). Name, Version, Beschreibung (DE/EN) und Autor liest der Manager aus der manifest.json; die Kennung ist die id. Vorschau: ein hochgeladenes Bild (PNG/JPG/GIF/WebP bis 2 MB) oder thumbnail.jpg im Paket. Neue Werkzeuge sind zuerst Entwurf; erst „Sichtbar“ schaltet sie frei. Kostenpflichtige Werkzeuge haben Preis, Kauf-Link und Produktkennung im Shop; ohne gültigen Kaufcode liefert der Server das Paket nicht |
Block-Galerie (gallery-server) | Nimmt .vndext und .vndtool. Eine Erweiterung braucht manifest.json (id, name, optional version, description, author) und tool.js; Vorschau wie bei Bausteinen (thumbnail, thumb, preview … als .jpg/.png im Paket) |
Sicherheitsregeln#
Erweiterungen sind Programmcode mit den Rechten des Programms. Das Programm bietet deshalb keinen offenen Marktplatz an; Pakete aus der Galerie werden nach einer Rückfrage installiert.
Für Autoren:
- Keine Fremdbibliotheken, keine CDN-Adressen, keine Webschriften: alles selbst mitliefern.
- Eingaben prüfen und bereinigen; kein
eval, keininnerHTMLmit Rohdaten (Text pertextContentoder über einen Helfer wieh()). - Zugangsdaten nur über
ctx.project.secrets, nie im Projekt, nie insettings, nie in einer Datei, die der Nutzer weitergibt. - Beitrag nur unter
assets/<eigene id>/…; das Programm lässt keine anderen Pfade zu. - Mit
ctx.project.aiverlässt Text den Rechner: dem Nutzer vorher sagen. - Das Programm reicht Erweiterungen nur eine Erlaubnisliste von Funktionen; die Objekte von
ctx.getPages()sind aber lebendige Arbeitsobjekte. Ändern Sie sie nie direkt.
Das Programm selbst begrenzt: ID-Format, Zip-Slip-Schutz beim Entpacken, Zwischenordner mit Austausch, 40 MB, Pfadprüfung im Beitrag, Geheimnisse nie zurücklesbar, Namen und Länge der Geheimnisse und der Einstellungen.
Beispiel: die Hallo-Erweiterung#
Eine vollständige Erweiterung mit drei Dateien. Sie zeigt die Seiten des Projekts, merkt sich einen Gruß in den Projekt-Einstellungen und gibt ihn beim Export als Datei assets/hallo-erweiterung/gruss.txt und als Kommentar am Ende von <body> aus. Sie wurde in einer Programm-Instanz installiert und durchgespielt: Seiten zeigen, Merken, Export-Beitrag setzen, Exportieren (Datei und Kommentar standen in publish/), Beitrag entfernen, erneut Exportieren (Datei und Ordner waren verschwunden).
manifest.json
{
"id": "hallo-erweiterung",
"name": "Hallo-Erweiterung",
"name_en": "Hello extension",
"name_fr": "Extension Bonjour",
"version": "1.0.0",
"icon": "HI",
"description": "Zeigt die Seiten des Projekts, merkt sich einen Gruß und legt ihn beim Export als Datei ab.",
"description_en": "Shows the pages of the project, remembers a greeting and writes it to a file on export.",
"description_fr": "Affiche les pages du projet, mémorise un message d'accueil et l'écrit dans un fichier lors de l'export.",
"author": "Beispiel GmbH",
"main": "tool.js"
}tool.js
// tool.js — Hallo-Erweiterung: Projekt lesen, Einstellung merken, Export-Beitrag setzen.
const ID = 'hallo-erweiterung';
/** el('div.klasse', { onclick: fn }, 'Text', kind …) — kleiner Helfer statt innerHTML */
function el(spec, attrs, ...kids) {
const [tag, ...cls] = spec.split('.');
const n = document.createElement(tag);
if (cls.length) n.className = cls.join(' ');
Object.keys(attrs || {}).forEach((k) => {
if (k.startsWith('on')) n.addEventListener(k.slice(2), attrs[k]);
else n.setAttribute(k, attrs[k]);
});
kids.forEach((x) => n.append(x));
return n;
}
export default {
run(ctx) {
const api = ctx.project;
const win = (inhalt) => ctx.openToolWindow('Hallo-Erweiterung', inhalt);
// Ältere Programmversionen kennen ctx.project nicht: freundlich melden statt abstürzen
if (!api || !api.exportContribution) { win(el('p', {}, 'Dafür braucht es eine neuere Version von VN-Designer (ab 1.1.55).')); return; }
if (!ctx.projectDir) { win(el('p', {}, 'Bitte zuerst ein Projekt öffnen.')); return; }
const saved = api.settings.get() || {};
const input = el('input', { type: 'text', value: saved.gruss || 'Hallo Welt' });
const out = el('pre.hallo-out', {});
const say = (text) => { out.textContent = text; };
win(el('div.hallo-root', {},
el('link', { rel: 'stylesheet', href: ctx.extension.baseUrl + 'style.css' }),
el('label', {}, 'Gruß ', input),
el('button', { onclick: () => { api.settings.set({ gruss: input.value }); say('Gespeichert (Projekt speichern nicht vergessen).'); } }, 'Merken'),
el('button', { onclick: () => {
const info = api.getInfo();
say(info.title + ': ' + info.pages.map((p) => p.name + ' (' + p.slug + ')').join(', '));
} }, 'Seiten zeigen'),
el('button', { onclick: () => {
const text = String(input.value).replace(/[<>&-]/g, ' ').slice(0, 200);
api.exportContribution.set({
bodyEnd: '',
files: [{ path: 'assets/' + ID + '/gruss.txt', text: text + '\n' }],
});
say('Export-Beitrag gesetzt. Er gilt beim nächsten Export.');
} }, 'Beim Export mitgeben'),
el('button', { onclick: () => { api.exportContribution.set(null); say('Beitrag entfernt.'); } }, 'Beitrag entfernen'),
out,
));
},
};style.css
.hallo-root { display: grid; gap: 0.6rem; font-size: 0.85rem; }
.hallo-root input { width: 100%; box-sizing: border-box; }
.hallo-root button { cursor: pointer; }
.hallo-out { margin: 0; white-space: pre-wrap; min-height: 2.4em; }Bauen und installieren
python extensions-src/build-ext.py extensions-src/hallo-erweiterung dist-ext/hallo-erweiterung.vndtoolDanach „+ Erweiterung installieren…“, die Kachel „Hallo-Erweiterung“ anklicken. Nach „Beim Export mitgeben“ und einem Export steht im Ergebnis am Ende von body:
</body>