Documentation développeur VN-Designer
12

Extensions (.vndtool)

Structure du paquet et manifest.json d'une extension-outil, cycle de vie, fenêtre d'outil, l'interface complète ctx du programme, parties serveur PHP, construction, envoi à la galerie, règles de sécurité et une extension Bonjour complète.

Vue d'ensemble#

Une extension est un outil supplémentaire qui ne fait pas partie du programme. Elle se présente sous la forme d'un fichier *.vndtool (un fichier ZIP) et apparaît après l'installation comme une tuile dans la fenêtre des outils (menu Outils › Ouvrir les outils VN). Elle fonctionne dans toutes les éditions et peut être supprimée à tout moment. Une extension peut

  • ouvrir sa propre fenêtre avec une interface au choix (ctx.openToolWindow),
  • lire le projet et le modifier dans un périmètre fixe (ctx.project, ctx.blocks),
  • apporter ses propres blocs et les insérer (ctx.blocks.importPackage),
  • placer des fichiers et du code dans le site fini lors de l'export, y compris des parties serveur PHP (ctx.project.exportContribution),
  • stocker des identifiants de manière sûre dans le profil du programme (ctx.project.secrets),
  • utiliser les accès IA enregistrés dans le programme (ctx.project.ai).

Installation et emplacement : « + Installer une extension… » dans la fenêtre des outils (ou glisser le fichier sur la fenêtre, ou installation depuis la galerie d'outils). Le programme décompresse le paquet dans <profil du programme>/extensions/<id>/ (sous Windows %APPDATA%), pas dans le projet. Lorsqu'un projet est transmis, les extensions ne le sont pas ; une mise à jour du programme ne les touche pas.

Structure du paquet#

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

Exemple vn-ical.vndtool (tel quel depuis le ZIP) : manifest.json, dom.js, ical-block.vndext, payload.js, style.css, thumbnail.jpg, tool.js. Le paquet de l'extension d'exemple est encore plus petit : manifest.json, icon.svg, tool.js.

manifest.json#

Syntaxe

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

Champs

ChampTypeDéfautSignification
idtexte–Obligatoire. 2 à 48 caractères, a-z, 0-9, -, _, commence par une lettre ou un chiffre. C'est le nom du dossier dans le profil et l'identifiant des réglages, des secrets et de la contribution à l'export. Ne doit jamais changer : sinon une mise à jour est installée comme un second outil. Les ID des outils intégrés sont réservés (l'installation est refusée, les fichiers sont de nouveau supprimés)
nametexte–Obligatoire. Nom de la tuile (en allemand)
name_en, name_fr, name_<sprache>texte–Nom dans une autre langue du programme. C'est la version de la langue du programme qui s'applique, sinon l'anglaise, sinon l'allemande. Seuls les champs de la forme name_xx avec deux à trois lettres sont pris en compte, 400 caractères au maximum
description, description_<sprache>textevideDescription affichée sur la tuile ; même règle de langue
versiontextevideAffichée sur la tuile et utilisée pour la comparaison de mise à jour avec la galerie. À augmenter à chaque modification
icontextesigle tiré du nomCourt signe dans le symbole bleu de la tuile, 4 caractères au maximum (émoji possible). Sans indication, le programme forme un sigle à partir des premières lettres des premiers mots (« VN SEO » → « SE »)
authortextevideAuteur
maintextetool.jsFichier du programme. Doit se trouver dans le paquet et rester à l'intérieur du dossier

tool.js#

Un module ES. export default fournit un objet avec run(ctx) ou directement une fonction. run s'exécute à chaque clic sur la tuile.

Syntaxe

js
export default {
  run(ctx, opts) {
    // Oberfläche bauen, ctx.openToolWindow(titel, element, { large }) aufrufen
  },
};

D'autres fichiers peuvent être importés normalement (import { h } from './dom.js?v=4'). Si export default est absent, ou s'il n'est ni un objet avec run ni une fonction, la tuile reste affichée avec « ⚠ Impossible de charger » et le message d'erreur.

payload.js et dom.js#

Ce sont des conventions de nommage des extensions existantes, pas des fichiers obligatoires : payload.js exporte PAYLOAD, un objet { "api.php": "<?php …", "lib.php": "…" } contenant les fichiers de la partie serveur (voir Parties serveur PHP). dom.js contient l'assistant h('div.klasse#id', { attr, onclick, html }, kinder…), clear(el), debounce(fn, ms) et sleep(ms) ; il est identique dans toutes les extensions (modèle : extensions-src/vn-ical/dom.js).

Cycle de vie#

  1. Démarrage : le programme lit ext:list (tous les dossiers sous extensions/ avec un manifest.json valide dont l'id correspond au nom du dossier) et charge chaque main par import() avec l'adresse …/tool.js?v=<date de modification du fichier>. Si cela réussit, l'outil est inscrit au registre avec son nom, sa description, sa version et son symbole ; sinon il est marqué comme défectueux (message rouge, suppression possible).
  2. Clic sur la tuile : run(ctx, opts) est appelé. ctx est une vue propre à chaque extension : en plus, ctx.extension et un ctx.project limité à son propre id.
  3. Fenêtre : ctx.openToolWindow ferme une fenêtre d'outil déjà ouverte ainsi que l'aperçu des tuiles, puis affiche la nouvelle fenêtre (voir ci-dessous).
  4. Installation, mise à jour, suppression : à l'installation, le paquet est d'abord décompressé dans un dossier intermédiaire, puis remplace une version existante ; un paquet défectueux ne détruit jamais une extension en cours d'utilisation. La suppression (corbeille sur la tuile) efface le dossier. Après une mise à jour, le programme affiche « Veuillez redémarrer VN-Designer afin que toutes les parties de la nouvelle version soient chargées ».

Fenêtre d'outil#

ctx.openToolWindow#

Ouvre la fenêtre déplaçable de l'extension en bas à droite (à tirer par l'en-tête, à fermer avec ✕). Il n'existe jamais qu'une seule fenêtre d'outil ; un nouvel appel remplace l'ancienne.

Syntaxe

js
ctx.openToolWindow(titel, element, { large: true })
ParamètreTypeSignification
titeltexteTitre dans l'en-tête de la fenêtre
elementélément DOMContenu. Le programme l'accroche dans la fenêtre ; vous le construisez vous-même
largebooléenFenêtre plus grande, librement redimensionnable (jusqu'à 1000 × 820 px, centrée en haut), sans marge intérieure propre ; pour les outils à interface multicolonne

Exemple

js
const box = document.createElement('div');
box.textContent = 'Hallo ' + (ctx.projectDir || '(kein Projekt)');
ctx.openToolWindow('Mein Werkzeug', box);

ctx.closeToolWindow#

ctx.closeToolWindow() ferme la fenêtre. Valeur de retour : aucune.

ctx.askConfirm#

Boîte de dialogue de confirmation au style du programme. await ctx.askConfirm(text) renvoie true (oui) ou false. Utilisez-la pour les actions irréversibles à la place de window.confirm.

L'interface ctx#

ctx comporte les entrées suivantes. Si une entrée manque (version plus ancienne du programme), vérifiez-la avant de l'utiliser (if (!ctx.project || !ctx.project.exportContribution) …) et signalez-le poliment.

EntréeSignification
ctx.projectDirDossier du projet ouvert (texte) ou null
ctx.getPages()Les pages du projet avec tous leurs blocs, y compris les modifications non enregistrées. Ce sont les objets de travail de l'éditeur, pas des copies : lecture seule. Une page possède entre autres id, name, slug, blocks, publish ; un bloc possède id, alias, schemaEntry, values
ctx.getGlobalBlocks()Les blocs communs à toutes les pages (menu, pied de page), de même forme que les blocs d'une page, également en lecture seule
ctx.switchToPage(id)Passe dans l'éditeur à la page portant cet id
ctx.askConfirm(text)voir ci-dessus
ctx.openToolWindow, ctx.closeToolWindowvoir ci-dessus
ctx.extension{ id, version, baseUrl } de sa propre extension ; baseUrl est l'adresse du dossier de l'extension, avec une barre oblique à la fin
ctx.projectInterface du projet, voir ci-dessous (copies en lecture, liste d'autorisation pour modifier)
ctx.blocksInterface des blocs, voir ci-dessous

window.vnDesigner est également disponible (passerelle du programme vers le processus principal). Parmi les extensions du programme, voici ce qui est utilisé : saveAsset(projectDir, unterordner, dateiname, arrayBuffer, { keepName }) (enregistre un fichier sous assets/<unterordner>/ dans le projet, renvoie { filename, path, relativePath, fileUrl } ; sont autorisés les fichiers image, de police, css et js jusqu'à 15 Mo), listAssetImages(projectDir) (images sous assets/images/), openExternal(url) (uniquement http/https dans le navigateur par défaut), loadSmtpConfig(projectDir) (les identifiants SMTP enregistrés dans le programme), netCheckUrl({ url, method, timeoutMs }) (vérifie une adresse sans cibles internes), downloadGoogleFont(…) et vnpdfSave(…). Ces fonctions appartiennent au programme et peuvent changer ; les extensions que vous diffusez s'en tiennent autant que possible à ctx.

ctx.project.getInfo#

Une copie des données du projet.

Syntaxe et valeur de retour

js
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 vaut null tant que l'outil SEO n'a rien réglé. localFonts est le nombre de polices propres.

ctx.project.buildFiles#

Construit les pages finies en mémoire, exactement comme l'export les écrirait, sans rien enregistrer (uniquement les pages cochées).

js
const r = await ctx.project.buildFiles();
// { files: [ { filename: 'index.html', pageId, html } ], extraFiles: [ { filename: 'sitemap.xml', text } ], css: '…fertiges style.css…' }

extraFiles contient sitemap.xml, robots.txt et llms.txt, dans la mesure où l'outil SEO les active. La contribution des extensions (fichiers, head, bodyEnd) n'est pas incluse dans buildFiles().

ctx.project.updatePage#

ctx.project.updatePage(id, patch) modifie des champs d'une page et renvoie true (page trouvée) ou false. Seuls ces champs sont autorisés, chacun sous forme de texte avec cette longueur maximale : seoTitle (300), metaDescription (600), ogImage (500), lang (20), headExtra (400000), bodyExtra (400000) ; en outre seo (objet, normalisé ; null le supprime). La modification s'applique immédiatement dans le projet ; l'utilisateur enregistre ensuite comme d'habitude.

js
ctx.project.updatePage(info.pages[0].id, { seoTitle: 'Startseite | Mein Betrieb', metaDescription: 'Kurzbeschreibung …' });

ctx.project.updateSite#

ctx.project.updateSite(patch) modifie les réglages du site : siteUrl (300 caractères), metaDescription (600), lang (20) et seo (objet ou null). Valeur de retour true.

ctx.project.getGlobalHtml et setGlobalHtml#

getGlobalHtml() renvoie { headExtra, bodyStart, bodyExtra }, les « Insertions HTML globales » (roue dentée dans la barre). setGlobalHtml(patch) modifie un ou plusieurs de ces champs (texte, 400000 caractères au maximum chacun) en une seule étape d'annulation et renvoie true. Le champ du code placé avant le type de document (doctypeExtra) n'est pas accessible.

ctx.project.listImages et setImageAlt#

await ctx.project.listImages() renvoie toutes les images des pages et des blocs communs avec leur texte alternatif effectif :

js
// [ { blockId, blockLabel, pageId, pageName, global, metaId: 'k:photo', src: 'file:///…/foto.jpg', alt: '' } ]

ctx.project.setImageAlt(blockId, metaId, alt) définit le texte alternatif (300 caractères au maximum) et renvoie true.

ctx.project.assetSizes#

await ctx.project.assetSizes(['assets/images/foto.jpg']) renvoie les tailles de fichier sous assets/ et publish/ : { "assets/images/foto.jpg": { "size": 8228 }, "assets/nix.png": null }. 2000 chemins au maximum ; les autres chemins donnent null.

ctx.project.addPage#

Crée une nouvelle page avec un bloc « Code HTML personnalisé ».

js
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 doit satisfaire ^[a-z0-9_-]{1,60}\.(html|php)$ ; html 400000 caractères au maximum. Une page existante n'est jamais écrasée (on obtient alors exists: true). La page n'est pas ouverte.

ctx.project.newEmptyPage#

Crée une page vide et y passe : ctx.project.newEmptyPage({ name, slug }) renvoie { ok, pageId, slug }. Le nom de fichier est rendu unique si nécessaire (-2, -3 …). Ensuite, les blocs insérés avec ctx.blocks.addFromCatalog arrivent sur cette page.

ctx.project.findInBlocks#

await ctx.project.findInBlocks(muster) recherche un motif (texte d'une expression régulière, sans tenir compte de la casse, 400 caractères au maximum) dans le HTML et le CSS finis de tous les blocs :

js
// [ { pageId, pageName, global, blockId, blockLabel, where: ['HTML', 'CSS'], sample } ]

ctx.project.selectBlock et showPage#

ctx.project.selectBlock(pageId, blockId) passe à la page, sélectionne le bloc et le fait défiler jusqu'au centre. await ctx.project.showPage(pageId) affiche une page et attend que la zone de travail ait dessiné tous ses blocs ; condition préalable pour les mesures sur le rendu final. ctx.project.canvas() renvoie l'élément de la zone de travail (lecture seule, par ex. getComputedStyle) ; chaque bloc s'y trouve dans .canvas-block[data-block-id].

ctx.project.colorUsage et replaceColors#

ctx.project.colorUsage() renvoie toutes les couleurs réglables :

js
// [ { color: '#e6f4f1', art: 'bg', ort: 'Hintergrund', pageId, pageName, global, blockId, blockLabel } ]
// art: 'field' | 'bg' | 'text' | 'icon' | 'site'

Sont prises en compte les champs de couleur et les arrière-plans des blocs, color: dans le texte formaté, les couleurs de symboles, le CSS personnalisé et le bouton de retour en haut. Les couleurs inscrites en dur dans le CSS du thème n'apparaissent pas.

ctx.project.replaceColors({ '#e6f4f1': '#ffeecc' }, { blockIds, site }) remplace en une seule opération (sans effet en chaîne A→B→C) et en une seule étape d'annulation. blockIds limite à ces blocs ; site: true inclut le CSS personnalisé et le bouton de retour en haut. Les ancres (href="#abc"), sélecteurs, chaînes de caractères et url(#…) restent intacts. Valeur de retour { changed, blocks } (au test : { "changed": 2, "blocks": 2 }).

ctx.project.settings#

Réglages propres à l'extension, enregistrés dans le projet (siteSettings.extensions[<id>].settings).

js
const s = ctx.project.settings.get();     // Kopie oder null
ctx.project.settings.set({ gruss: 'Hallo' });   // ersetzt alles; set(null) löscht

Les valeurs doivent être compatibles JSON. L'utilisateur doit encore enregistrer le projet.

ctx.project.exportContribution#

Ce que l'extension apporte lors de l'export.

Syntaxe

js
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 entfernen

Champs et limites

ChampSignification
headCode à la fin de <head> sur chaque page (après la feuille de style, avant le code des insertions globales) ; 20000 caractères au maximum
bodyEndCode à la fin de <body> (après les scripts du programme, avant le code des insertions globales) ; pas bloqué par l'avis sur les cookies ; 20000 caractères au maximum
filesFichiers texte { path, text }. Le chemin doit être de la forme assets/<propre id>/… (caractères A-Za-z0-9._/-, 120 au maximum après l'identifiant, pas de ..). 30 fichiers au maximum (les suivants sont tronqués silencieusement), 400000 caractères au maximum par fichier

Une infraction au chemin ou à la taille de fichier lève une exception (« Fichier non valide dans la contribution à l'export »). La contribution est enregistrée dans le fichier de projet et n'est produite que tant que l'extension est installée et chargée. Si vous la mettez à null ou supprimez l'extension, le prochain export supprime les fichiers écrits précédemment ainsi que les dossiers vides (confirmé au test). Le programme ne supprime pas les fichiers déjà présents sur le serveur.

Dans files[].text, l'export remplace les paramètres fictifs {{secret:NAME}} et {{secret-php:NAME}} par des secrets, voir l'entrée suivante. Dans head et bodyEnd, il n'y a aucun remplacement.

ctx.project.secrets#

Les secrets (par ex. valeurs de contrôle de mots de passe) se trouvent dans le profil du programme, pas dans le projet, chiffrés lorsque Windows le propose.

js
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 caractères parmi A-Za-z0-9_ ; wert : texte, 500 caractères au maximum. Les secrets ne sont jamais relisibles ; seul names() indique lesquels existent. L'export les insère dans les fichiers de la contribution :

Paramètre fictifRemplacement
{{secret:NAME}}la valeur telle quelle
{{secret-php:NAME}}la valeur avec barre oblique inverse, guillemets et signes dollar échappés (\\, \", \$), pour une chaîne PHP entre guillemets doubles

Un secret manquant donne un texte vide.

Exemple (tiré de vn-ical, abrégé) : le mot de passe de l'administration ne quitte jamais le programme en clair. L'outil calcule le sel et la valeur de contrôle PBKDF2 et les enregistre comme secrets ; le fichier admin-config.php de la contribution ne contient que les paramètres fictifs.

js
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#

Utilise les accès IA enregistrés dans le programme (Paramètres › Clés API IA). Le texte quitte l'ordinateur en direction du fournisseur. Montrez-le à l'utilisateur.

EntréeSignification
await ai.providers()Les fournisseurs configurés : [ { id, label } ] (vide si aucun n'est enregistré)
await ai.ask({ providerId, systemPrompt, userPrompt, model, onDelta, signal, onThink })Pose une question ; renvoie le texte de la réponse. model remplace le modèle uniquement pour cette requête. onDelta(stück, gesamt) signale la réponse au fil de l'eau (streaming ; une réponse coupée par la limite de longueur n'est alors pas levée comme erreur, vérifiez-le vous-même). signal est un AbortSignal qui interrompt réellement la requête. onThink(zeichen) signale la phase de réflexion des modèles d'IA locaux (la réflexion est désactivée pour les outils)
ai.openSettings()Ouvre la boîte de dialogue des clés IA
ai.streaming, ai.thinkingtrue : ask connaît onDelta, signal et onThink (test de fonctionnalité)
ai.speech, await ai.speechProvider()Saisie vocale : speechProvider() renvoie { id, label } du fournisseur (Groq d'abord, puis ChatGPT) ou null
await ai.transcribe({ audio, language, prompt, signal })Enregistrement (Blob, par ex. audio/webm) → texte reconnu. Sans accès Groq ou ChatGPT, une exception est levée
js
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#

Importe un paquet de bloc (.vndext contenant un seul composant, sous forme d'ArrayBuffer) et l'insère dans la page actuelle. Le programme signale lui-même les erreurs.

js
const res = await fetch(ctx.extension.baseUrl + 'ical-block.vndext');
const ok = await ctx.blocks.importPackage(await res.arrayBuffer(), { position: 'end' });   // true | false

opts.position : 'end' (à la fin de la page), 'start', 'after' (après le bloc sélectionné), un nombre (emplacement, 0 = tout en haut) ; sans indication, après le bloc sélectionné. Un paquet contenant plusieurs composants n'est pas pris en charge (utilisez importToLibrary pour cela). Un bloc commun à toutes les pages (global) remplace celui de son groupe qui existe déjà.

ctx.blocks.importToLibrary#

Place un paquet dans la bibliothèque du projet, pas sur la page. Les paquets de thème y entrent avec tous leurs blocs ; un alias identique remplace l'entrée existante.

js
const r = await ctx.blocks.importToLibrary(buffer);   // { ok: true, count: 3 } | { ok: false, message }

Rien n'est affiché ; l'extension montre elle-même le résultat.

ctx.blocks.findByAlias et setValues#

ctx.blocks.findByAlias(alias) trouve les blocs de ce bloc-modèle dans la page actuelle : [ { id, selected, values } ] (values est une copie, selected est vrai pour le bloc sélectionné). L'alias est celui du paquet (pour un bloc isolé params.alias, pour un paquet de thème <alias>-<dossier>). await ctx.blocks.setValues(blockId, patch) définit des valeurs du panneau des propriétés (patch = { schluessel: wert }), redessine le bloc et crée une étape d'annulation ; valeur de retour true/false.

js
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) et ctx.blocks.selected() (bloc sélectionné ou null) décrivent les propriétés d'un bloc telles que le panneau les connaît ; ctx.blocks.pageBlocks() liste les blocs de la page actuelle.

js
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 est text, textarea, checkbox, color, range, select (options : [[Wert, Beschriftung], …]), image ou background. Les valeurs trop grandes (plus de 2000 caractères) sont absentes de values.

ctx.blocks.catalog et addFromCatalog#

await ctx.blocks.catalog() liste tous les blocs insérables (dossier des thèmes avec le thème de départ, et la bibliothèque) : [ { key, source: 'theme'|'library', theme, title, group, once } ] (once = 'menu'/'footers' pour les blocs communs à toutes les pages, sinon vide). await ctx.blocks.addFromCatalog(key, opts) en insère un (opts.position comme pour importPackage) et renvoie l'identifiant du bloc ou null.

ctx.blocks.texts#

Lire et écrire les textes modifiables de la page actuelle (y compris menu et pied de page).

js
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' } ]);   // 1

list() renvoie les textes dans l'ordre du document, uniquement pour les blocs qui se trouvent actuellement dans la zone de travail. set(einträge) définit pour chaque entrée html (nettoyé comme à la saisie : mise en forme en ligne et liens) ou text (texte brut, caractères échappés, les sauts de ligne deviennent <br>), redessine les blocs, crée une étape d'annulation et renvoie le nombre de textes modifiés.

ctx.blocks.images#

ctx.blocks.images.list() renvoie les emplacements d'image des blocs de la page : [ { blockId, blockLabel, slot, kind: 'field'|'background'|'free', label, url, alt, w, h } ]. slot est k:<Feld> (champ image dans le panneau), b:<Feld> (image d'arrière-plan) ou f:<Kennung> (image libre dans le bloc) ; w/h sont la taille affichée en px. await ctx.blocks.images.set([ { blockId, slot, url, alt } ]) définit des images (url est la fileUrl d'un fichier enregistré dans le projet, alt facultatif, 300 caractères au maximum) en une seule étape d'annulation et renvoie le nombre d'images définies.

Autres entrées de ctx.blocks#

EntréeSignification
addBlock(result, opts)Insère un résultat d'import terminé ({ status: 'ok', alias, schemaEntry, message }). Il suppose un schemaEntry produit par le programme ; les extensions utilisent importPackage
findGalleries(), updateGallery(blockId, result)Font partie de l'outil intégré VN Galerie (trouver les blocs de galerie et remplacer leurs images) ; non destinées à des blocs personnalisés
anim.targetAt(el), anim.selectedTargets(), anim.set(blockId, einträge), anim.play(blockId, cfgs), anim.mark(blockId, ids)Font partie de l'outil intégré VN Animation (animations pour textes et images) ; interface interne, peut changer

Parties serveur PHP#

Une extension peut fournir des fonctions côté serveur sur le site fini (calendrier de rendez-vous, livre d'or, statistiques …). Le schéma utilisé par toutes les extensions existantes :

  1. Les fichiers PHP se trouvent dans le dossier source de l'extension sous payload/. Un script (make-payload.py) les lit et écrit payload.js : un module qui exporte PAYLOAD comme objet { "api.php": "…", "lib.php": "…" }. Les fichiers sous data/ et uploads/ ainsi que config.php restent exclus, car ils n'apparaissent que sur le serveur.
  2. tool.js importe PAYLOAD et en construit la contribution à l'export : chaque fichier sous la forme { path: 'assets/<id>/<name>', text }, plus le config.php généré avec les réglages de l'utilisateur et un admin-config.php avec des paramètres fictifs de secrets.
  3. Lors de l'export, le programme écrit les fichiers dans publish/assets/<id>/. L'utilisateur envoie publish/ en ligne comme n'importe quel site.

Exemple (tiré de vn-ical, abrégé)

js
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);

Règles pour les parties serveur :

  • Limites : 30 fichiers au maximum par extension, 400000 caractères par fichier. Si la partie serveur est plus volumineuse, regroupez des fichiers. La contribution figure dans le fichier de projet (siteSettings.extensions[<id>].contribution) et l'alourdit d'autant.
  • Protéger le dossier data/ : le programme n'écrit pas de .htaccess pour les contributions. Le code PHP le crée lui-même (vn-ical : Require all denied avec son équivalent pour les anciennes versions d'Apache, au premier accès dans lib.php). N'affichez jamais les chemins dans les messages.
  • Générer la configuration lors de l'export : les réglages de l'utilisateur n'ont pas leur place dans des fichiers fixes. tool.js reconstruit config.php à chaque fois à partir des réglages (sous forme de nowdoc contenant du JSON, afin que rien n'ait besoin d'être échappé) et insère les secrets au moyen de paramètres fictifs.
  • Envoi d'e-mails : lors de l'export, le programme écrit les identifiants SMTP enregistrés dans le programme dans assets/vn-shared/config.php (uniquement si SMTP est configuré) ; les parties PHP les lisent avec dirname(__DIR__) . '/vn-shared/config.php' (variables $smtp_host, $smtp_port, $smtp_encryption, $smtp_username, $smtp_password, $smtp_from_email, $smtp_from_name, $hmac_secret). Voir Publication.
  • PHP 7.3 et versions ultérieures, y compris 8.x. Vérifiez chaque fichier avec php -l et testez avec php -S 127.0.0.1:<Port> sur le dossier exporté.
  • Base de données et données des visiteurs : ne jamais les livrer dans la contribution ; mots de passe uniquement sous forme de valeur de contrôle PBKDF2 ; vérifier les entrées, échapper les sorties, protection CSRF, cookie de session HttpOnly/SameSite, limitation des tentatives de connexion ; ni eval, ni innerHTML avec des données brutes.
  • Protection des données : ne chargez aucun script, police ni image provenant de serveurs tiers dans head/bodyEnd ou dans l'interface de la page.

Blocs dans une extension#

Une extension fournit des blocs sous forme de fichiers .vndext dans le paquet (block/ dans le dossier source, empaquetés par make-payload.py en <name>-block.vndext). L'outil les insère avec importPackage, puis les modifie avec findByAlias et setValues. L'alias dans params.json du bloc en est l'identifiant (vn-ical). Le bloc ne contient que l'interface et le script de la page ; il récupère les données via les fichiers de la contribution. Les textes qui entreront plus tard dans la page, prenez-les comme propriété du bloc (jamais bruts dans un data-…="{{x}}" ; utilisez {{vnEnc(x)}}).

Construire, vérifier, livrer#

Construire le paquet

text
python extensions-src/build-ext.py extensions-src/mein-werkzeug dist-ext/mein-werkzeug.vndtool

build-ext.py exige id et name dans manifest.json, place le fichier manifest.json tout au début du ZIP et empaquette tous les autres fichiers du dossier. Un fichier .vndignore (un nom par ligne, # pour les commentaires) désigne les fichiers et dossiers à exclure du paquet (dossier source payload/, block/, tests/, make-payload.py). Si un script comme make-payload.py doit passer avant, exécutez-le avant l'empaquetage.

Vérifier

  1. Installez le paquet dans la fenêtre des outils, cliquez sur la tuile. Une erreur dans tool.js laisse la tuile affichée avec ⚠ et le message ; les clients peuvent ainsi la supprimer.
  2. Testez chaque fonction une par une, y compris les cas d'erreur (aucun projet ouvert, version plus ancienne du programme).
  3. Exportez et vérifiez le résultat dans publish/ dans le navigateur ou avec PHP ; cherchez le fichier et le code bodyEnd de l'extension.
  4. Mettez la contribution à null et exportez de nouveau : les fichiers doivent disparaître.

Le programme vérifie à l'installation : manifest.json doit exister et contenir du JSON valide avec un id valide et un name, le fichier du programme doit se trouver dans le paquet. Les chemins du paquet qui sortent du dossier (.., chemins absolus, indications de lecteur) sont ignorés. 40 Mo au maximum une fois décompressé.

Galerie (deux serveurs, mêmes paquets)

GalerieFormat et règles
Galerie d'outils (gallery-server-tools, onglet « Outils »)Envoyer un .vndtool (véritable ZIP avec un manifest.json valide et le fichier du programme, 100 Mo au maximum). Le gestionnaire lit le nom, la version, la description (DE/EN) et l'auteur dans manifest.json ; l'identifiant est l'id. Aperçu : une image envoyée (PNG/JPG/GIF/WebP jusqu'à 2 Mo) ou thumbnail.jpg dans le paquet. Les nouveaux outils sont d'abord à l'état de brouillon ; seul « Visible » les rend accessibles. Les outils payants ont un prix, un lien d'achat et un identifiant de produit dans la boutique ; sans code d'achat valide, le serveur ne livre pas le paquet
Galerie de blocs (gallery-server)Accepte .vndext et .vndtool. Une extension nécessite manifest.json (id, name, facultatif version, description, author) et tool.js ; aperçu comme pour les blocs (thumbnail, thumb, preview … en .jpg/.png dans le paquet)

Règles de sécurité#

Les extensions sont du code de programme avec les droits du programme. C'est pourquoi le programme ne propose pas de place de marché ouverte ; les paquets de la galerie sont installés après une demande de confirmation.

Pour les auteurs :

  • Pas de bibliothèques tierces, pas d'adresses CDN, pas de polices web : fournissez tout vous-même.
  • Vérifiez et nettoyez les entrées ; ni eval, ni innerHTML avec des données brutes (texte via textContent ou via un assistant comme h()).
  • Identifiants uniquement via ctx.project.secrets, jamais dans le projet, jamais dans settings, jamais dans un fichier que l'utilisateur transmet.
  • Contribution uniquement sous assets/<propre id>/… ; le programme n'autorise aucun autre chemin.
  • Avec ctx.project.ai, du texte quitte l'ordinateur : prévenez-en l'utilisateur au préalable.
  • Le programme ne remet aux extensions qu'une liste d'autorisation de fonctions ; mais les objets de ctx.getPages() sont des objets de travail vivants. Ne les modifiez jamais directement.

Le programme lui-même impose des limites : format de l'ID, protection Zip-Slip lors de la décompression, dossier intermédiaire avec remplacement, 40 Mo, vérification des chemins dans la contribution, secrets jamais relisibles, noms et longueur des secrets et des réglages.

Exemple : l'extension Bonjour#

Une extension complète en trois fichiers. Elle affiche les pages du projet, mémorise un message d'accueil dans les réglages du projet et le restitue lors de l'export sous forme de fichier assets/hallo-erweiterung/gruss.txt et de commentaire à la fin de <body>. Elle a été installée dans une instance du programme et testée : afficher les pages, mémoriser, définir la contribution à l'export, exporter (le fichier et le commentaire figuraient dans publish/), supprimer la contribution, exporter de nouveau (le fichier et le dossier avaient disparu).

manifest.json

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

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

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

Construire et installer

text
python extensions-src/build-ext.py extensions-src/hallo-erweiterung dist-ext/hallo-erweiterung.vndtool

Ensuite, « + Installer une extension… », puis cliquez sur la tuile « Extension Bonjour ». Après « Beim Export mitgeben » et un export, le résultat contient à la fin de body :

html

</body>