Documentation développeur VN-Designer
01

Vue d'ensemble et premier bloc

Ce qu'est un bloc, comment est structuré un dossier de bloc, un premier bloc personnel en dix minutes (dossier, paquet, import, test), les termes essentiels et une vue d'ensemble de tous les chapitres.

Qu'est-ce qu'un bloc ?#

Un site dans VN-Designer se compose de blocs placés les uns sous les autres sur une page : menu, en-tête, bloc de texte, galerie, formulaire, pied de page. Chaque bloc provient d'un composant (« Baustein ») : une description réutilisable en trois parties.

PartieFichierRôle
Balisage et champs de saisietemplate.htmlHTML du bloc, plus les champs que montre le panneau des propriétés
Stylestyle.lessLESS (ou CSS) avec les valeurs des champs comme variables
Aperçuthumb.pngImage pour la sélection (facultatif)

Un utilisateur insère un composant, modifie textes et images directement dans la zone de travail et règle couleurs, espacements et interrupteurs dans le panneau des propriétés. À l'export, cela donne du HTML et du CSS simples, sans bibliothèque d'exécution.

text
Paket (.vndext)  →  Import  →  Baustein (Vorlage + LESS + Felder)
                                      │ einfügen
                                      ▼
                       Block auf der Seite (gespeicherte Werte)
                                      │ zeichnen: {{…}} und Direktiven auswerten, LESS übersetzen
                         ┌────────────┴────────────┐
                         ▼                         ▼
                  Editor (bearbeitbar)     Export (HTML + style.css)

Termes#

TermeSignification
BlocUne instance sur une page, avec ses propres valeurs et ses propres modifications de texte
Composant (« Baustein »)Le modèle réutilisable dont naissent les blocs (template.html, style.less, thumb.png)
PaquetUn fichier ZIP .vndext avec un ou plusieurs composants, params.json et des fichiers communs
ThèmeUn paquet avec de nombreux composants assortis (du menu au pied de page) et un CSS de thème commun
ExtensionUn outil .vndtool pour le programme lui-même (vérifications, assistants, fichiers serveur). Elle peut apporter des composants, mais c'est autre chose qu'un paquet
Propriétés (champs, paramètres)Les champs de saisie du panneau des propriétés ; chaque champ a un nom et une valeur
AliasLe nom technique d'un composant (alias dans params.json) ; il détermine la classe CSS des instances
RacineLe premier élément de template.html ; il porte la classe d'instance
InstanceUn bloc isolé sur une page ; deux blocs du même composant sont deux instances avec des classes propres

Structure d'un dossier de bloc#

Voici l'aspect du dossier d'un paquet contenant un composant :

text
meine-bloecke/
  params.json                  Name, Alias und Liste der Bausteine
  components/
    hinweiskarte/
      template.html            Pflicht: Markup und <vn-parameters>
      style.less               optional: Stil (LESS oder CSS)
      thumb.png                optional: Vorschau in der Auswahl
    _images/                   optional: gemeinsame Bilder, Verweis ../_images/<datei>
  plugins/theme/css/style.css  optional: Theme-CSS, einmal pro Projekt geladen

template.html#

Balisage d'un bloc : un élément racine, dedans le bloc <vn-parameters>, puis le contenu avec espaces réservés et directives. Voir Le modèle.

style.less#

Style du bloc. Chaque champ est disponible comme variable LESS @name. Voir Style du bloc.

thumb.png#

Image d'aperçu du composant pour la sélection et la bibliothèque. Si elle manque, la sélection affiche un symbole de remplacement. Voir Paquets.

params.json#

Décrit le paquet : name, alias et components avec path, _group (catégorie) et _title (nom affiché). Voir Paquets.

components/_images#

Dossier d'images commun. Les références dans le modèle et le LESS s'écrivent ../_images/<fichier> ; l'import dépose les fichiers dans le projet. Voir Paquets.

Premier bloc personnel en 10 minutes#

L'exemple construit une carte d'information avec espacement, couleur d'accent et un interrupteur pour le texte complémentaire. Vous avez besoin de VN-Designer avec un projet ouvert et d'un éditeur de texte qui enregistre les fichiers en UTF-8 sans BOM.

1. Créer le dossier et les fichiers#

Créez cette arborescence (noms de dossiers libres, les chemins dans params.json doivent correspondre) :

text
meine-bloecke/
  params.json
  components/
    hinweiskarte/
      template.html
      style.less

params.json

json
{
  "name": "Meine Blöcke",
  "alias": "meine-bloecke",
  "components": [
    { "path": "components/hinweiskarte", "_group": "Hinweise", "_title": "Hinweiskarte" }
  ]
}

components/hinweiskarte/template.html

html
<section class="mb-karte">
  <vn-parameters>
    <header>Größe</header>
    <input type="range" title="Abstand oben und unten" name="abstand" min="0" max="8" step="1" value="3">
    <header>Anzeigen</header>
    <input type="checkbox" title="Zusatztext" name="showText" checked>
    <header>Farben</header>
    <input type="color" title="Hintergrund der Karte" name="kartenFarbe" value="#eef2ff">
    <input type="color" title="Akzentfarbe" name="akzent" value="#4f46e5">
  </vn-parameters>
  <div class="container">
    <div class="mb-karte-box">
      <h2>Willkommen</h2>
      <p vn-if="showText">Dieser Block ist in zehn Minuten entstanden. Texte ändern Sie direkt im Editor.</p>
      <a class="btn btn-primary" href="#">Mehr erfahren</a>
    </div>
  </div>
</section>

components/hinweiskarte/style.less

less
padding-top: (@abstand * 1rem);
padding-bottom: (@abstand * 1rem);

.mb-karte-box {
  background: @kartenFarbe;
  border-left: 6px solid @akzent;
  border-radius: 0.75rem;
  padding: 2rem;
}
.mb-karte-box h2 { color: @akzent; }
.mb-karte-box .btn-primary {
  background-color: @akzent !important;
  border-color: @akzent !important;
  color: #fff !important;
}

Ce qui se passe ici : les lignes sans sélecteur (padding-top …) valent pour la racine <section> ; @abstand, @kartenFarbe et @akzent sont les champs de <vn-parameters> ; vn-if="showText" retire le paragraphe lorsque l'interrupteur est désactivé.

2. Empaqueter#

Un paquet est un fichier ZIP portant l'extension .vndext. Les chemins dans le ZIP doivent être écrits avec des barres obliques (components/hinweiskarte/template.html).

Windows 10/11 (tar intégré), dans une PowerShell :

text
cd meine-bloecke
& "$env:SystemRoot\System32\tar.exe" -a -c -f ..\meine-bloecke.zip params.json components
Rename-Item ..\meine-bloecke.zip meine-bloecke.vndext

Avec Python (indépendant de la plateforme, c'est aussi ainsi qu'empaquettent les scripts de thème du programme) :

python
import os, zipfile
src = 'meine-bloecke'
with zipfile.ZipFile('meine-bloecke.vndext', 'w', zipfile.ZIP_DEFLATED) as z:
    for root, _, files in os.walk(src):
        for name in files:
            full = os.path.join(root, name)
            z.write(full, os.path.relpath(full, src).replace(os.sep, '/'))

3. Importer#

  1. Ouvrez un projet (l'import dépose les images dans le dossier du projet).
  2. Cliquez sur + Ajouter un bloc et choisissez l'onglet Fichier (.vndext). Choisissez le fichier ou glissez-le dans la fenêtre.
  3. Par défaut, le composant « Hinweiskarte » n'arrive que dans la bibliothèque (onglet « Bibliothèque », interrupteur sous la zone de dépôt : « Ajouter uniquement à la bibliothèque ») et peut de là être placé sur la page. Activez l'interrupteur (il s'appelle alors « Insérer directement dans le projet ») et le composant arrive aussitôt sur la page.

Un paquet contenant plusieurs composants montre une sélection avec les aperçus.

4. Tester#

  • Panneau des propriétés : le bloc a les groupes « Größe », « Anzeigen » et « Farben ». Déplacez le curseur, désactivez le texte complémentaire et changez les couleurs : le bloc est redessiné à chaque modification.
  • Modifier directement : cliquez dans « Willkommen » et tapez. Cliquez sur le bouton : la boîte de dialogue du bouton s'ouvre. Les deux sont automatiques, sans que le modèle ne fasse rien pour cela.
  • Erreurs dans le LESS : si le bloc affiche l'étiquette rouge « ⚠ Erreur CSS », le message figure dans l'info-bulle.
  • Aperçu en direct : avec F5, le programme montre la page terminée comme dans l'export, avec des boutons pour tablette (820 px) et téléphone (390 px). Vérifiez-y les media queries.
  • Export : le bouton « Exporter » écrit le dossier avec index.html et style.css. Le résultat ne contient aucune trace de l'éditeur.

5. Continuer à travailler#

  • Modifiez les fichiers du dossier, empaquetez à nouveau et importez à nouveau. La bibliothèque ne remplace rien : chaque import crée une nouvelle entrée.
  • Un bloc qui se trouve déjà sur une page conserve son modèle enregistré : le programme ne modifie jamais des projets existants par une mise à jour de paquet. Pour tester, insérez à nouveau le composant.
  • Plus rapide : ouvrez le bloc avec le bouton </> Code du panneau des propriétés, modifiez le modèle ou le LESS et confirmez avec ✓ Appliquer. Cela ne modifie que ce bloc. Reportez ensuite les modifications dans vos fichiers.
  • Prenez l'habitude de placer un paquet dans un dossier des thèmes (onglet « Thèmes », choisir le dossier des thèmes) : il y apparaît comme catalogue chaque fois que vous ouvrez la boîte de dialogue.
  • Un bloc que vous avez construit dans l'éditeur, enregistrez-le avec ⤓ directement comme fichier .vndext ou avec ★ comme bloc utilisateur.

Pièges fréquents#

Tous ces points sont documentés en détail dans les chapitres. En voici la version courte :

SymptômeCauseChapitre
L'import signale « JSON non valide » ou « template.html introuvable »BOM dans params.json ; barres obliques inverses dans le ZIPci-dessus, Paquets
Bloc sans aucun CSS, étiquette « ⚠ Erreur CSS »Erreur dans le LESS : variable inconnue (@bg-… sans widget d'arrière-plan), tréma dans un nom de champ, BOMLESS
{{…}} donne partout un texte vide, vn-if ne masque rienun nom de champ est invalide en JavaScript (trait d'union, chiffre au début, mot réservé)Noms
Un élément reste malgré vn-ifvn-if ne retire que pour false exact ; un texte vide ou une faute de frappe dans le nom le laisse en placevn-if
{{beschriftung}} apparaît tel quel dans le boutonDans <a class="btn">, les espaces réservés ne sont pas évaluésEspaces réservés dans les boutons
n + 1 donne 41Les valeurs des curseurs sont du texterange
Le bloc a un autre aspect dans l'éditeur que dans l'export!important contre Bootstrap/CSS du thème ; les couches n'existent que dans l'éditeurPriorité
Une règle du CSS du thème n'agit pas dans l'éditeur#canvas, body, html, :root dans @scope ; correct : :scopeLe piège #canvas
L'image d'arrière-plan manque après l'importValeur par défaut file:///… vers l'ordinateur de l'auteur ; correct : ../_images/…image

Vue d'ensemble des chapitres#

ChapitreContenu
Vue d'ensemble et premier blocce chapitre
Le modèleélément racine, attributs racine, espaces réservés, images et liens, Bootstrap, éditeur et export
Champs de saisie<vn-parameters> : tous les types de saisie, widget d'arrière-plan, condition, valeurs par défaut, exemple
Directives et marqueursvn-if, vn-class, vn-style, vn-overlay, vn-video et autres ; anciennes notations
Style du blocstyle.less : variables, portée, priorité de l'éditeur et de l'export, pièges
Contenus modifiables directementtexte, images, icônes, boutons, menus, liens, CMS, popup
Scripts dans les blocs et les thèmesJavaScript dans le bloc, détection de l'éditeur, Cookie Consent, bibliothèques fournies
Formulairesformulaire statique vn-sform, envoi PHP, protection anti-spam, VN Form Editor
Arrière-plans, médias et blocs d'outilsarrière-plan et vidéo, lightbox, galerie, visionneuse PDF, recherche, blog, animations, traducteur
Paquets et thèmes.vndext, params.json, import, CSS du thème, dossier des thèmes
Constructeur et blocs utilisateurblocs faits de lignes, colonnes et éléments, blocs utilisateur
Extensionsextensions d'outils .vndtool, manifest.json, interface du programme ctx
Exporter et publierce que l'export écrit, aperçu, envoi FTP, règles de confidentialité
Pièges et liste de contrôlelistes de contrôle avant publication, tableau de tous les pièges avec cause et solution
Référence rapidetableaux de tous les types de saisie, directives, espaces réservés, fichiers de paquet, fonctions ctx et bibliothèques