Documentation développeur VN-Designer
11

Constructeur et blocs utilisateur

Comment le constructeur de blocs génère le modèle et le LESS à partir de lignes, de colonnes et d’éléments, quel modèle de données est enregistré, comment les blocs utilisateur et les fichiers .vndext naissent de blocs personnels et quel est le rapport avec l’éditeur de code.

Vue d’ensemble#

Le constructeur (onglet « Constructeur » dans « Ajouter un bloc ») assemble un bloc à partir de lignes, de colonnes et d’éléments. Ce n’est pas un mécanisme de rendu à part : à chaque modification, le programme génère à partir d’un petit arbre un modèle tout à fait ordinaire (<vn-parameters> plus balisage) et un LESS. Le bloc passe ensuite par le même pipeline que n’importe quel bloc importé (champs, valeurs par défaut, repérage des textes, boutons, icônes et images).

Trois voies apparentées pour obtenir un bloc personnel :

VoieRésultatReste reconstructible
ConstructeurBloc avec arbre de structure (schemaEntry.builder), alias vn-baukastenoui, avec les boutons « + » dans le bloc et la section « Structure » du panneau des propriétés
Surface libreBloc avec arbre d’éléments (schemaEntry.freeSurface), alias vn-freioui, à la souris sur la surface
Code personnaliséBloc custom-html / custom-php avec du code brutuniquement via l’éditeur de code

Le modèle de données enregistré#

Dans le projet (projekt.vnd), un bloc du constructeur est un bloc normal. Son schemaEntry porte en plus deux champs :

ChampContenu
builderL’arbre : { "v": 1, "next": 17, "rows": [ … ] }. next est le compteur des nouveaux identifiants. Une ligne (r…) possède id, d (valeurs prédéfinies) et cols ; une colonne (c…) possède id, d et items ; un élément (e…) possède id, type et d
bkGroupsOrdre des groupes de propriétés : ["block", "r1", "c2", "e3", …]

d ne contient que les valeurs prédéfinies des nœuds nouvellement créés. Tous les réglages se trouvent, comme pour n’importe quel bloc, dans block.values, sous la clé <identifiant>_<propriété>, p. ex. e3_width, c2_span, r1_perRow. Les autres champs de schemaEntry (templateHtml, lessText, fields, defaults, wrapperClass, buttonDefaults, iconDefaults) sont le résultat généré.

Exemple (mise en page « Cartes — nombre illimité », tirée d’un projet enregistré, abrégée)

json
{
  "alias": "vn-baukasten",
  "schemaEntry": {
    "label": "Baukasten",
    "builder": {
      "v": 1, "next": 17,
      "rows": [
        { "id": "r1", "d": { "gap": 4, "valign": "stretch", "perRow": 3, "mb": 4 },
          "cols": [
            { "id": "c2", "d": { "span": 4, "hasBg": true, "shadow": true, "pad": 2, "radius": 14 },
              "items": [
                { "id": "e3", "type": "image",   "d": { "ratio": "3 / 2", "radius": 8 } },
                { "id": "e4", "type": "heading", "d": { "size": 1.35 } },
                { "id": "e5", "type": "text",    "d": { "size": 0.95 } },
                { "id": "e6", "type": "button",  "d": {} }
              ] }
          ] }
      ]
    },
    "bkGroups": ["block", "r1", "c2", "e3", "e4", "e5", "e6"]
  },
  "values": { "width": "container", "paddingTop": "4", "bg": { "type": "color", "value": "#f3f4f6", "parallax": false }, "r1_perRow": "3", "r1_gap": "4" }
}

Ce qui se passe lors d’une reconstruction#

Chaque modification de structure (ajouter, déplacer, copier ou supprimer une ligne, une colonne ou un élément) passe par la même fonction : elle modifie l’arbre, régénère le modèle, le LESS et les champs, puis reporte l’état :

  • Valeurs : pour chaque clé de la nouvelle liste de champs, la valeur existante est conservée, sinon la valeur par défaut s’applique. Les valeurs dont le nom commence par _ (attribuées par le programme, comme les curseurs de texte) sont toujours conservées. Les valeurs des nœuds supprimés disparaissent.
  • Copies : un nœud copié reçoit de nouveaux identifiants et les valeurs de l’original.
  • Modifications : les textes portent des identifiants fixes (data-vn-text-id="t<nombre de l’identifiant × 100 + k>"), les images sont rattachées à leur champ (e3_src). Les boutons et les icônes numérotent les outils standard en continu ; le programme recalcule donc leurs modifications (buttonOverrides, iconOverrides) élément par élément. Les textes alternatifs, titres, tailles et liens des images sont rattachés au nom du champ.

Limites : au maximum 6 colonnes côte à côte dans une ligne normale, au maximum 24 dans une ligne en grille (voir ci-dessous) ; liste : 12 entrées au maximum ; diaporama d’images : 20 diapositives au maximum. La description de la mise en page « Diaporama d’images » indique « jusqu’à 12 » ; le code en autorise 20.

Le bloc#

Chaque bloc du constructeur possède d’abord le groupe « Bloc » avec ces propriétés :

CléTypePar défautSignification
widthChoixcontainerLargeur du contenu : container (1140 px), narrow (760 px), full (pleine largeur)
minHeightPlage 0–100, pas de 50Hauteur en pourcentage de la hauteur de l’écran ; 0 = selon le contenu. Au-dessus de 0, la hauteur est fixe (vh) et le surplus est coupé, afin qu’un arrière-plan ne grandisse pas pendant la saisie
vAlignChoixcenterPosition verticale du contenu (uniquement si minHeight > 0)
paddingTop, paddingBottomPlage 0–14, pas de 0,54Espacement en haut/en bas en rem
textColorCouleur#4b5563Couleur du texte du bloc
headColorCouleur#111827Couleur des titres
bgArrière-planCouleur #ffffffvoir Arrière-plan
bgPosterImagevideImage d’aperçu pendant le chargement de la vidéo (uniquement pour un arrière-plan vidéo)
overlay, overlayColor, overlayOpacityInterrupteur, couleur, plage 0–1désactivé, #000000, 0,5Assombrissement au-dessus de l’image ou de la vidéo d’arrière-plan

La charpente du balisage généré :

html
<section class="vn-bk" data-bg-video="{{bg.type == 'video' &amp;&amp; bg.value.url}}">
  <vn-parameters> … </vn-parameters>
  <div class="mbr-fallback-image" vn-if="bg.type == 'video'" style="background-image:url('{{bgPoster}}')"></div>
  <div class="vn-overlay" vn-if="overlay &amp;&amp; bg.type !== 'color'" opacity="{{overlayOpacity}}" bg-color="{{overlayColor}}"></div>
  <div class="vn-bk-inner">
    <div class="vn-bk-row vn-bk-r1" vn-class="{'vn-bk-rev': r1_reverse}">
      <div class="vn-bk-col vn-bk-c2"> <div class="vn-bk-el vn-bk-e3 vn-bk-t-image"> … </div> </div>
    </div>
  </div>
</section>

Le bloc est un conteneur (container-type: inline-size) ; les retours à la ligne pour les largeurs étroites dépendent de la largeur du bloc (@container), pas de la fenêtre : jusqu’à 700 px de largeur de bloc, toutes les colonnes sont empilées.

Arrière-plan : image, couleur ou vidéo#

bg est un champ d’arrière-plan à trois possibilités : image, couleur, vidéo. La valeur est un objet : { "type": "color", "value": "#ffffff", "parallax": false } ; pour une image "value": { "url": "…" }, pour une vidéo "value": { "url": "<fichier ou adresse YouTube/Vimeo>" }. Le LESS connaît les valeurs sous les noms @bg-type, @bg-value et @bg-parallax. La parallaxe (background-attachment: fixed) n’existe que pour l’image. Pour la vidéo, l’adresse se trouve dans l’attribut data-bg-video du bloc ; la page terminée charge pour cela le script vendor/vn-bgvideo/. Le contenu du bloc reste librement constructible.

Lignes#

Propriétés de chaque ligne (groupe « Ligne n ») :

CléTypePar défautSignification
perRowPlage 0–60Colonnes par ligne. 0 : la largeur de chaque colonne (span) se règle individuellement. Supérieur à 0 : grille, toutes les colonnes ont la même largeur, en nombre illimité, et passent d’elles-mêmes à la ligne
gapPlage 0–123Espacement des colonnes (unité 0,5 rem)
valignChoixflex-startflex-start, center, flex-end, stretch (même hauteur)
reverseInterrupteurdésactivéOrdre inversé sur téléphone
mbPlage 0–120Espace en dessous (unité 0,5 rem)

Grille « Cartes en nombre illimité »#

Avec perRow > 0, la ligne est une grille. Le bouton « + Colonne » ajoute alors une copie de la dernière colonne avec son contenu et ses réglages ; la largeur par colonne (span) n’a plus d’importance. Avec perRow > 2, un bloc de 701 à 1000 px de large affiche deux cartes par ligne ; à partir de 700 px et en dessous, chaque carte est seule sur sa ligne.

Colonnes#

CléTypePar défautSignification
spanPlage 1–1212Largeur sur 12 (uniquement dans les lignes avec perRow = 0). Lors de l’ajout ou de la copie d’une colonne, le programme répartit les 12 parts de façon égale
alignChoixleftAlignement du texte dans la colonne
valignChoixflex-startContenu à la verticale : haut, milieu, bas
gapPlage 0–122Espacement des éléments (unité 0,5 rem)
padPlage 0–120Marge intérieure (unité 0,5 rem)
hasBgInterrupteurdésactivéArrière-plan personnalisé (carte)
bgCouleur#ffffffCouleur d’arrière-plan de la carte
radiusPlage 0–4012Arrondi en px
shadowInterrupteurdésactivéOmbre

Éléments#

Il existe dix types d’éléments. Chaque propriété s’appelle <identifiant>_<clé> dans l’objet de valeurs. Tous les éléments ont en outre la classe racine vn-bk-el vn-bk-<identifiant> vn-bk-t-<type>.

Image (image)#

Balisage : <img src="{{e3_src}}" alt="">. L’image est cliquable et se redimensionne avec des poignées.

CléTypePar défautSignification
srcImageimage de substitutionFichier
widthPlage 10–100100Largeur en %
ratioChoix4 / 3auto, 1 / 1, 4 / 3, 3 / 2, 16 / 9, 21 / 9, 3 / 4, 2 / 3
fitChoixcovercover (remplir) ou contain (afficher en entier)
radiusPlage 0–608Arrondi en px
roundInterrupteurdésactivéCercle (1:1)
shadowInterrupteurdésactivéOmbre
alignChoixinheritinherit, left, center, right

Titre (heading)#

Balisage : <h2 class="vn-bk-tx" data-vn-text-id="t…">. Le niveau (h1 à h6) est réglé par l’utilisateur dans le texte.

CléTypePar défautSignification
sizePlage 1–6 (0,1)2,2Taille en rem
weightChoix700400, 500, 600, 700, 800
alignChoixinheritcomme ci-dessus
useColor, colorInterrupteur, couleurdésactivé, #111827couleur personnalisée, sinon headColor du bloc
lhPlage 1–2 (0,05)1,2Hauteur de ligne
lsPlage −3–12 (0,5)0Espacement des lettres (centièmes d’em)
upperInterrupteurdésactivéMAJUSCULES

Texte (text)#

Balisage : <p class="vn-bk-tx" data-vn-text-id="t…">. Propriétés : size (0,7–2,5 ; par défaut 1), align, useColor/color (#4b5563), lh (1–2,4 ; par défaut 1,65).

Bouton (button)#

Balisage : <a class="btn btn-primary" href="#">Mehr erfahren</a> ; la cible, le texte, la couleur et l’icône sont réglés par l’utilisateur dans la boîte de dialogue du bouton. Propriétés : align, size (sm, md, lg ; par défaut md), full (pleine largeur).

Icône (icon)#

Balisage : <i class="bi bi-star-fill" data-vn-icon></i>. Propriétés : size (1–10 rem, par défaut 2,5), color (#2563eb), circle (arrière-plan rond), bg (#e0e9ff), align.

Liste (list)#

Un ul avec jusqu’à 12 entrées ; chaque entrée porte vn-if="<identifiant>_count >= k". Propriétés : count (1–12, par défaut 4), bullet (check, dot, arrow, star, dash, none), bulletColor, size, useColor/color, gap (0–6).

Diaporama d’images (slider)#

Un carrousel Bootstrap avec jusqu’à 20 diapositives, chacune avec une image (<identifiant>_src1 … _src20) et deux textes (titre et texte) portant les identifiants t<nombre × 100 + 2k − 1> et t<nombre × 100 + 2k>. Propriétés : count (masquée, 1–20, par défaut 3), ratio (sans auto ; par défaut 16 / 9), fit, radius (12), arrows, dots, captions, auto (secondes avant la diapositive suivante, 0 = désactivé ; par défaut 5), fade (fondu au lieu du défilement). Les diapositives peuvent être ajoutées, supprimées et déplacées dans le panneau ; l’image et les textes se déplacent ensemble.

Espaceur (spacer)#

Une surface vide, h (0,5–12 rem, par défaut 2).

Séparateur (divider)#

Un hr. Propriétés : color (#d1d5db), thick (1–8 px), width (10–100 %), style (solid, dashed, dotted), align (left, center, right ; par défaut center).

Vidéo (video)#

Un iframe qui n’apparaît que si une adresse est saisie : src="{{vnEmbed(<Kennung>_url)}}". vnEmbed convertit les adresses YouTube et Vimeo en adresse d’intégration. Propriétés : url, ratio (16 / 9, 4 / 3, 1 / 1, 21 / 9), width (20–100), radius, align.

Carte (map)#

Un iframe avec https://www.google.com/maps?q=<Adresse>&output=embed. Propriétés : addr (adresse), height (200–700 px, par défaut 360), radius.

Mises en page de l’onglet Constructeur#

L’onglet propose neuf modèles ; chacun est un arbre prêt à l’emploi :

IdentifiantNomStructure
leerVideune ligne, une colonne
bild-linksImage à gauche, texte à droitedeux colonnes : image ; texte d’accroche, titre, texte, bouton
bild-rechtsTexte à gauche, image à droitecomme ci-dessus, ligne avec reverse (sur téléphone, l’image vient en premier)
zentriertTexte centréune colonne, width: narrow
zwei-spaltenDeux colonnes de textedeux colonnes, chacune avec titre et texte
karten-rasterCartes — nombre illimitégrille perRow: 3 avec des cartes (image, titre, texte, bouton)
symbole-rasterAvantages avec icône — nombre illimitégrille avec icône, titre, texte
bilder-sliderDiaporama d’images — nombre illimité de diapositivesun diaporama de trois diapositives
heroEn-tête avec image d’arrière-plangrand titre, texte, bouton ; assombrissement activé, width: narrow

Blocs utilisateur#

Un bloc utilisateur est un bloc personnalisé qui est stocké sous un nom propre dans le profil du programme et peut être inséré dans chaque projet (onglet « Blocs utilisateur »).

Enregistrer avec ★#

Le bouton ★ (dans la barre du bloc et dans le panneau des propriétés) demande le nom et la catégorie et enregistre le bloc entier : schemaEntry avec l’arbre de structure, values et toutes les personnalisations (textes, boutons, icônes, images, textes alternatifs, animations). Le nouveau nom devient en même temps le nom d’affichage (schemaEntry.label) du bloc. Dans le profil, les éléments suivants sont créés sous user-blocks/ :

FichierContenu
<id>.json{ id, name, label, category, created, dataJson, theme, files } ; l’identifiant a la forme ub-<heure><aléa>
<id>.jpgAperçu, capturé à partir de la zone du bloc sur la zone de travail (480 px de large au maximum)
<id>-files/assets/…Copies des fichiers auxquels le bloc fait référence

Dans le texte de dataJson, l’espace réservé @@VNPROJ@@ remplace le chemin du projet. Est considérée comme fichier toute référence de la forme @@VNPROJ@@/assets/<chemin> (images, mais aussi d’autres fichiers sous assets/) ainsi que les scripts d’un thème Bootstrap 4 (theme.files). Lors de l’insertion dans un projet, le programme y copie les fichiers (les fichiers existants restent intacts) et insère le chemin du projet cible. Ensuite, c’est un bloc comme les autres et il conserve aussi une structure du constructeur.

Limites : nom de 80 caractères au maximum, données du bloc de 60 Mo au maximum.

Catégories#

La catégorie est un texte libre (40 caractères au maximum, sans caractères de contrôle). Le programme propose cette liste et la complète par les catégories déjà utilisées : En-tête, Pied de page, Menu, Texte, Images et galerie, Cartes, Formulaire, Contact, Tarifs, Autre. Le programme devine une présélection à partir du nom (« hero » → En-tête, « footer » → Pied de page, « galerie » → Images et galerie …). L’onglet « Blocs utilisateur » regroupe par catégorie et propose un filtre ; avec le bouton étiquette 🏷, on modifie la catégorie après coup, avec ✎ le nom, et avec 🗑 on supprime le bloc (les blocs déjà insérés restent dans leurs projets).

Export en .vndext#

Deux voies transforment un bloc en un fichier de paquet transmissible contenant un seul bloc :

VoieOùContenu du modèle
⤓ « Enregistrer en fichier .vndext »Panneau des propriétés du bloc, directement depuis la zone de travailintégré : les textes, boutons, icônes, images, textes alternatifs et liens figurent dans le modèle ; les valeurs réglées des champs simples (nombre, texte, couleur, interrupteur, choix) figurent comme valeurs par défaut dans <vn-parameters>. Les valeurs composées comme bg restent à la valeur par défaut du bloc
⇩ « Exporter en fichier .vndext »Carte d’un bloc utilisateurle modèle enregistré sans modification ; les personnalisations qui ne figurent que dans values et les overrides sont perdues

Le paquet contient :

text
params.json                       { "name": "<Name>", "alias": "<Alias des Blocks>", "components": [ { "path": "components/component1" } ] }
components/component1/template.html
components/component1/style.less
components/component1/thumb.png   (nur wenn eine Vorschau aufgenommen werden konnte)
components/_images/<pfad>         Bilder und Dateien aus assets/ des Projekts

Les références à @@VNPROJ@@/assets/ deviennent ../_images/. L’alias est celui du bloc (pour un constructeur, vn-baukasten). Lorsque le fichier est inséré dans un autre projet, la structure du constructeur a disparu : le modèle est un bloc normal ; la structure du constructeur n’est pas écrite dans le fichier (seul ★ la conserve). Une surface libre devient elle aussi un bloc normal à l’export.

Rapport avec l’éditeur de code#

Le bouton « </> Code » du panneau des propriétés ouvre le HTML et le LESS du bloc. Il montre l’état visible, intégré : les textes, boutons, icônes et images, avec toutes leurs personnalisations, figurent directement dans le HTML. Cela vaut aussi pour les blocs de l’onglet « Code personnalisé » (custom-html, custom-php).

  • Le constructeur et la surface libre sont verrouillés : leur code ne peut pas être modifié (message au clic ; de même dans le menu contextuel et dans le chat IA). On les reconstruit avec « + » et le panneau des propriétés.
  • À l’application (✓), le programme vérifie le HTML (lint) et signale les erreurs de syntaxe avec le numéro de ligne (« Le HTML contient n erreur(s) de syntaxe » ; la vérification connaît {{…}}, les blocs PHP et <?php … ?>) ; le navigateur remanierait silencieusement un HTML erroné. Il compare en outre les classes avant et après l’application et avertit si des classes ont été perdues. Les deux avertissements peuvent être confirmés avec « Appliquer quand même ».
  • Une page entière collée (<html>, <head>, <body>) est placée dans une enveloppe dans le bloc, afin que ses classes ne disparaissent pas. Les déchets de framework étrangers provenant de textes du chat IA collés sont supprimés. Un préfixe de langage (« css: ») placé devant le LESS est supprimé.
  • Le PHP dans le HTML est stocké de façon protégée sous forme de <script type="text/x-vn-php"> et retransformé en code PHP brut à l’export. La page doit alors s’appeler .php ; le programme propose de changer le nom du fichier. Si le script PHP porte l’attribut data-position="top", le code est placé au début du fichier à l’export (p. ex. pour session_start()).
  • Espaces réservés : dans custom-html/custom-php, le programme n’évalue pas {{…}} (les accolades ouvrantes sont protégées avant le rendu) ; dans tous les autres blocs, si.
  • Après l’application, les overrides (textes, boutons, icônes, images) sont vidés, car ils figurent désormais dans le modèle ; les champs et les valeurs par défaut sont redérivés de <vn-parameters>, les valeurs existantes sont conservées.
  • Le LESS est compilé à titre d’essai avant l’application. En cas d’erreur LESS, la boîte de dialogue reste ouverte et indique l’erreur ; le HTML est alors déjà appliqué, le CSS non.

Surface libre#

La surface libre fonctionne comme le constructeur, mais avec un positionnement libre : schemaEntry.freeSurface = { v: 1, next, s: { … }, items: [ { id, type, g: { x, y, w, h, z }, d } ] }. g est la géométrie en pourcentage de la largeur et de la hauteur de la surface (h 0 = automatique, z = couche). 60 éléments au maximum. Tous les autres réglages se trouvent dans block.values sous <identifiant>_<nom>. Sur téléphone, la surface empile les éléments les uns sous les autres (point de rupture réglable) ou s’adapte à l’échelle.