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#
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
{
"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
| Champ | Type | Défaut | Signification |
|---|---|---|---|
id | texte | – | 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) |
name | texte | – | 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> | texte | vide | Description affichée sur la tuile ; même règle de langue |
version | texte | vide | Affichée sur la tuile et utilisée pour la comparaison de mise à jour avec la galerie. À augmenter à chaque modification |
icon | texte | sigle tiré du nom | Court 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 ») |
author | texte | vide | Auteur |
main | texte | tool.js | Fichier 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
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#
- Démarrage : le programme lit
ext:list(tous les dossiers sousextensions/avec unmanifest.jsonvalide dont l'idcorrespond au nom du dossier) et charge chaquemainparimport()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). - Clic sur la tuile :
run(ctx, opts)est appelé.ctxest une vue propre à chaque extension : en plus,ctx.extensionet unctx.projectlimité à son propreid. - Fenêtre :
ctx.openToolWindowferme une fenêtre d'outil déjà ouverte ainsi que l'aperçu des tuiles, puis affiche la nouvelle fenêtre (voir ci-dessous). - 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
ctx.openToolWindow(titel, element, { large: true })| Paramètre | Type | Signification |
|---|---|---|
titel | texte | Titre dans l'en-tête de la fenêtre |
element | élément DOM | Contenu. Le programme l'accroche dans la fenêtre ; vous le construisez vous-même |
large | booléen | Fenêtre plus grande, librement redimensionnable (jusqu'à 1000 × 820 px, centrée en haut), sans marge intérieure propre ; pour les outils à interface multicolonne |
Exemple
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ée | Signification |
|---|---|
ctx.projectDir | Dossier 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.closeToolWindow | voir 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.project | Interface du projet, voir ci-dessous (copies en lecture, liste d'autorisation pour modifier) |
ctx.blocks | Interface 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
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).
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.
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 :
// [ { 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é ».
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 :
// [ { 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 :
// [ { 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).
const s = ctx.project.settings.get(); // Kopie oder null
ctx.project.settings.set({ gruss: 'Hallo' }); // ersetzt alles; set(null) löschtLes 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
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 entfernenChamps et limites
| Champ | Signification |
|---|---|
head | Code à la fin de <head> sur chaque page (après la feuille de style, avant le code des insertions globales) ; 20000 caractères au maximum |
bodyEnd | Code à 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 |
files | Fichiers 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.
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 fictif | Remplacement |
|---|---|
{{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.
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ée | Signification |
|---|---|
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.thinking | true : 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 |
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.
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' (à 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.
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.
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.
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).
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() 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ée | Signification |
|---|---|
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 :
- Les fichiers PHP se trouvent dans le dossier source de l'extension sous
payload/. Un script (make-payload.py) les lit et écritpayload.js: un module qui exportePAYLOADcomme objet{ "api.php": "…", "lib.php": "…" }. Les fichiers sousdata/etuploads/ainsi queconfig.phprestent exclus, car ils n'apparaissent que sur le serveur. tool.jsimportePAYLOADet en construit la contribution à l'export : chaque fichier sous la forme{ path: 'assets/<id>/<name>', text }, plus leconfig.phpgénéré avec les réglages de l'utilisateur et unadmin-config.phpavec des paramètres fictifs de secrets.- Lors de l'export, le programme écrit les fichiers dans
publish/assets/<id>/. L'utilisateur envoiepublish/en ligne comme n'importe quel site.
Exemple (tiré de vn-ical, abrégé)
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.htaccesspour les contributions. Le code PHP le crée lui-même (vn-ical:Require all deniedavec son équivalent pour les anciennes versions d'Apache, au premier accès danslib.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.jsreconstruitconfig.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 avecdirname(__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 -let testez avecphp -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 ; nieval, niinnerHTMLavec des données brutes. - Protection des données : ne chargez aucun script, police ni image provenant de serveurs tiers dans
head/bodyEndou 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
python extensions-src/build-ext.py extensions-src/mein-werkzeug dist-ext/mein-werkzeug.vndtoolbuild-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
- Installez le paquet dans la fenêtre des outils, cliquez sur la tuile. Une erreur dans
tool.jslaisse la tuile affichée avec ⚠ et le message ; les clients peuvent ainsi la supprimer. - Testez chaque fonction une par une, y compris les cas d'erreur (aucun projet ouvert, version plus ancienne du programme).
- Exportez et vérifiez le résultat dans
publish/dans le navigateur ou avec PHP ; cherchez le fichier et le codebodyEndde l'extension. - Mettez la contribution à
nullet 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)
| Galerie | Format 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, niinnerHTMLavec des données brutes (texte viatextContentou via un assistant commeh()). - Identifiants uniquement via
ctx.project.secrets, jamais dans le projet, jamais danssettings, 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
{
"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; }Construire et installer
python extensions-src/build-ext.py extensions-src/hallo-erweiterung dist-ext/hallo-erweiterung.vndtoolEnsuite, « + 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 :
</body>