Documentation développeur VN-Designer
04

Directives et marqueurs

vn-if, vn-class, vn-style, vn-strict-if, vn-theme-style, vn-overlay, vn-buttons, vn-menu, vn-video, vn-article, data-vn-icon et d'autres attributs du modèle, les règles des expressions et une liste des anciennes notations.

Vue d'ensemble#

Les directives sont des attributs que le programme évalue lorsqu'il dessine un bloc, puis retire du balisage. Elles rendent un modèle statique dépendant des valeurs des propriétés : afficher ou masquer un élément, poser des classes ou des styles sous condition.

Voici comment un bloc est dessiné (makeGenericRenderer dans src/renderer.js) :

  1. <vn-parameters> est retiré.
  2. {{vn-id}} est remplacé par l'identifiant de l'instance.
  3. Chaque {{expression}} est évaluée et remplacée par son résultat (Espaces réservés).
  4. Le résultat est lu comme du HTML.
  5. Les directives parcourent tous les éléments dans l'ordre du document. Pour chaque élément, dans cet ordre : vn-if, vn-class, vn-style, vn-theme-style, puis la règle pour vn-overlay.
  6. La racine reçoit la classe d'instance et, si elle n'en a pas, un id. Le LESS est compilé.

Comme l'étape 3 vient avant l'étape 5, les espaces réservés sont possibles dans les directives, mais le plus souvent inutiles : l'expression de vn-if connaît de toute façon les valeurs.

DirectiveEffet
vn-ifretirer l'élément
vn-strict-ifmarque le bloc : vn-if vérifie strictement
vn-classajouter des classes sous condition
vn-styleposer des styles en ligne sous condition
vn-theme-styleajouter des classes de thème
vn-overlaysurface d'assombrissement avec opacity et bg-color
vn-buttons, vn-menumarqueurs pour vn-theme-style
vn-videobloc vidéo avec champ d'adresse dans le panneau
vn-articleliste extensible
data-vn-iconrepérer un élément d'icône

Expressions#

Le texte d'une directive (et de chaque {{…}}) est une expression JavaScript. Elle voit toutes les valeurs du bloc sous leur nom ainsi que les aides vnEnc et vnEmbed. Techniquement, c'est le corps de new Function(…noms, 'return (' + expression + ');') (evalExpr dans src/parser.js).

Règles (toutes vérifiées)

  • Une erreur dans l'expression (erreur de syntaxe, nom inconnu, accès à undefined.x) est interceptée et donne undefined, sans message.
  • undefined n'est pas false : en mode standard, vn-if ne retire que sur false exact. Voir vn-if.
  • Les objets standard de JavaScript (Math, String, Number, JSON …) sont disponibles.
  • Dans un attribut HTML, écrivez && sous la forme &amp;&amp;, < sous la forme &lt;. À la lecture, l'analyseur HTML décode cette notation. Alternez les guillemets avec ceux de l'attribut (vn-if="mode == 'list'").
  • Les valeurs des champs range sont du texte. Comparez avec n > 3 (JavaScript convertit) ou calculez avec n * 1 ; n + 1 concatène. Voir range.
  • Les valeurs des champs checkbox sont true ou false, le widget d'arrière-plan est un objet (bg.type, bg.value, bg.parallax).

Directives#

vn-if#

Retire un élément avec son contenu si l'expression donne false.

Syntaxe

html
<p vn-if="showText">Beschreibung</p>
<div vn-if="overlay &amp;&amp; bg.type !== 'color'"></div>

Exemple (tiré de themes/vn-studio-src/components/header1)

html
<div class="vs-dim" vn-if="dim" style="background-color:{{dimColor}};opacity:{{dimOpacity}}"></div>

Ce que donne une expression et ce qui en résulte (vérifié, mode standard)

Expression (valeur)RésultatÉlément
showText (true)truereste
showText (false)falseretiré
mode == 'b' (comparaison fausse)falseretiré
!!titel (texte vide)falseretiré
titel (texte vide)""reste
n (texte "4" ou "0")textereste
gibtsNicht (nom inconnu)erreur, undefinedreste

vn-if agit lors du dessin. Une propriété n'est donc pas « masquée » : l'élément n'existe plus dans le balisage (ni dans l'export).

vn-strict-if#

Un marqueur sur un élément quelconque du bloc (en général sur l'élément racine). Il fait passer tous les vn-if du bloc en mode strict. L'attribut lui-même est retiré.

Syntaxe

html
<section class="mein-block" vn-strict-if>
  <div vn-if="overlay">…</div>
</section>

Différences avec le mode standard (vérifié)

Standardavec vn-strict-if
Élément retiré pourfalse exacttoute valeur fausse : false, 0, texte vide, null, undefined
Nom inconnul'élément restele nom vaut undefined, l'élément est retiré
Erreur dans l'expressionl'élément restel'élément est retiré
Math, String …disponiblesdisponibles

Une valeur range est du texte et compte donc comme vraie même pour "0" : écrivez Number(n) > 0. Le mode strict ne vaut que pour vn-if ; vn-class et vn-style restent inchangés. Il a été introduit pour des blocs repris d'autres projets et les nouveaux blocs en ont rarement besoin : écrivez-y plutôt des expressions sans ambiguïté.

vn-class#

Ajoute des classes à un élément selon les valeurs. Les classes existantes restent ; rien ne peut être retiré ainsi.

Syntaxe

html
<section vn-class="{'klasse-a': bedingung, 'klasse-b klasse-c': bedingung2}"> … </section>
<div vn-class="[{'a': x}, {'b': y}]"> … </div>
<div vn-class="'ansicht-' + mode"> … </div>

Résultats autorisés

RésultatEffet
Objet { 'classe': valeur }chaque clé dont la valeur est vraie est ajoutée ; une clé peut contenir plusieurs classes séparées par des espaces
Liste [ … ]chaque élément est traité comme un résultat isolé (objets, textes, listes imbriquées)
Texte 'a b'les classes sont ajoutées
tout le reste (null, nombre …) et une erreurrien

Exemple (tiré de themes/vn-studio-src/components/menu1)

html
<nav global once="menu" class="navbar vn-menu" vn-class="{'navbar-expand-lg': !collapsed, 'sticky-top': sticky, 'vs-transparent': transparent}">

vn-style#

Pose des styles en ligne à partir d'un objet.

Syntaxe

html
<h2 vn-style="{'font-size': sizeTitle + 'rem', color: titelFarbe}">Titel</h2>

Règles (vérifiées)

  • Les clés peuvent s'écrire en camelCase (fontSize) ou avec un trait d'union entre guillemets ('font-size').
  • La valeur est affectée à l'élément comme style (el.style[propriété] = valeur). Les valeurs invalides et les propriétés inconnues sont ignorées en silence. Un texte vide ou null ne pose rien.
  • Les propriétés personnalisées (--nom) sont rejetées : on ne peut pas les poser ainsi ({'--k': 1} reste sans effet). Écrivez-les comme un attribut style ordinaire avec un espace réservé : style="--k:{{k}}".
  • Si le résultat n'est pas un objet (par exemple un texte 'color:red'), rien ne se passe.
  • Le style se trouve sur l'élément (en ligne) et l'emporte donc sur les règles du LESS, sauf si elles portent !important.

Exemple (d'après le modèle de gallery-content : taille de police par titre depuis un curseur, dans la notation du programme)

html
<h2 class="titel" vn-style="{'font-size': sizeTitle + 'rem'}">Titel</h2>

vn-theme-style#

Ajoute des classes issues des réglages du thème (par exemple display-7 pour la taille de police d'un thème avec classes d'affichage).

Syntaxe

html
<h2 vn-theme-style="display-2">Titel</h2>
<div vn-buttons vn-theme-style="display-7"><a class="btn btn-primary" href="#">Eins</a></div>

Effet (vérifié)

L'élément estLes classes atterrissent sur
un conteneur avec vn-buttonschaque .btn qu'il contient
un conteneur avec vn-menuchaque .nav-link et .dropdown-item qu'il contient
sinonl'élément lui-même

Si un conteneur n'a pas d'enfants correspondants, il reçoit lui-même les classes. L'attribut vn-theme-style est retiré ensuite ; vn-buttons et vn-menu restent dans le balisage comme marqueurs.

vn-overlay#

Une surface qui assombrit ou teinte un arrière-plan. vn-overlay est une classe ; deux attributs la pilotent.

Syntaxe

html
<div class="vn-overlay" vn-if="overlay" opacity="{{overlayOpacity}}" bg-color="{{overlayColor}}"></div>

Attributs

NomValeurSignification
opacitynombre de 0 à 1devient le style en ligne opacity
bg-colorcouleurdevient le style en ligne background-color

De plus, le programme pose toujours position: absolute; inset: 0; pointer-events: none. Les deux attributs sont retirés ensuite. Si l'un manque, le programme ne pose pas le style correspondant.

Les champs overlay, overlayColor, overlayOpacity sont créés automatiquement par le programme si le modèle contient le mot overlay (Champs de superposition automatiques).

vn-buttons#

Un marqueur sur le conteneur d'un groupe de boutons. Il n'a aucun effet propre ; il détermine où un vn-theme-style placé sur le même élément écrit ses classes (sur chaque .btn). L'attribut reste dans le balisage. Plus sur les boutons : Contenus modifiables directement.

html
<div vn-buttons vn-theme-style="display-7">
  <a class="btn btn-primary" href="#">Eins</a>
  <a class="btn btn-secondary" href="#">Zwei</a>
</div>

vn-menu#

Un marqueur sur le conteneur des entrées de menu (<ul vn-menu>). Il n'a aucun effet propre ; avec vn-theme-style sur le même élément, les classes vont à chaque .nav-link et .dropdown-item. Le programme reconnaît les entrées de menu indépendamment de cela, d'après leurs classes, voir Menus.

html
<ul class="navbar-nav" vn-menu vn-theme-style="display-4">
  <li class="nav-item"><a class="nav-link" href="#">Start</a></li>
</ul>

vn-video#

Repère un conteneur avec une vidéo (iframe ou video). Le programme en fait un champ d'adresse dans le panneau et convertit l'adresse en adresse intégrable.

Syntaxe

html
<div vn-video class="ratio ratio-16x9">
  <iframe src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"></iframe>
</div>

Comportement (vérifié dans l'éditeur et dans l'export)

  • Le conteneur ne compte que s'il contient un iframe, un video ou (pour un conteneur sans vidéo par défaut) l'attribut data-vn-video-empty="1" avec une valeur.
  • Pour chaque conteneur, le panneau montre un groupe « Vidéo » (avec plusieurs : « Vidéo 1 », « Vidéo 2 » …) avec un champ d'adresse (YouTube, Vimeo ou fichier vidéo), « Choisir un fichier vidéo… », « Démarrer automatiquement » et « Boucle ». L'enregistrement se fait dans _videoUrl<i>, _videoAuto<i>, _videoLoop<i> (i compte les conteneurs à partir de 0). Sans saisie, l'adresse du modèle s'applique ; les valeurs par défaut pour la lecture automatique et la boucle sont lues par le programme dans l'adresse (?autoplay=1, ?loop=1).
  • YouTube devient youtube-nocookie.com/embed/…, Vimeo devient player.vimeo.com/video/… ; un fichier (.mp4, .webm, .ogv, .m4v, une adresse file: ou assets/videos/) devient <video controls playsinline preload="metadata">. Une adresse vide montre dans l'éditeur une indication absente de l'export.
  • Dans l'éditeur, rien ne démarre de lui-même.
  • De plus, chaque iframe[data-src] du bloc (vidéo dans un popup, chargée à l'ouverture) est converti en adresse intégrable.

vn-article#

Repère une liste (ul ou ol) comme un seul champ modifiable dans lequel la touche Entrée crée un nouvel élément de liste. data-multiline est équivalent.

Syntaxe

html
<ul vn-article>
  <li>Erster Punkt</li>
  <li>Zweiter Punkt</li>
</ul>

Les éléments ne sont alors pas des champs de texte à part. Listes imbriquées : seule la plus externe est le champ. Détails : Champs de liste.

data-vn-icon#

Repère un élément comme icône que l'utilisateur peut remplacer par un clic dans l'éditeur (symbole, taille, couleur, lien).

Syntaxe

html
<i class="bi bi-star-fill" data-vn-icon></i>
<span data-vn-icon class="mein-symbol"></span>

Comportement (vérifié)

  • <i class="bi bi-…"> et <span class="bi bi-…"> sont pris en compte même sans le marqueur, sauf dans un texte, un bouton et les icônes de menu. data-vn-icon n'est donc nécessaire que pour d'autres éléments.
  • À l'import, le programme attribue data-vn-icon-id="iconN" et retire le marqueur. Toutes les classes sauf bi et bi-… sont conservées comme « classes supplémentaires ».
  • Dans l'export, l'identifiant disparaît ; l'icône y apparaît sous la forme <i class="bi bi-…">.

Plus : Icônes.

vn-parameters#

Le bloc contenant les champs de saisie. Ce n'est pas une directive, mais il est traité comme tel : il se trouve dans le modèle, est retiré lors du dessin et n'est jamais exporté. Voir Champs de saisie.

Autres marqueurs dans le modèle#

Un auteur peut écrire ces attributs dans le modèle. Le programme ou les scripts fournis les évaluent.

data-bg-video#

Porte l'adresse d'une vidéo d'arrière-plan sur l'élément racine. Voir Attributs racine.

data-vn-editor-only#

L'élément n'apparaît que dans l'éditeur ; l'export le retire. En détail dans Scripts dans les blocs.

html
<div class="vn-bgvid-empty" data-vn-editor-only vn-if="!videoFile">Noch kein Video gewählt …</div>

data-vn-popup-close#

Un élément portant cet attribut ferme le popup dans lequel se trouve le bloc (par exemple un bouton « Non merci »). Voir Popup.

html
<a class="btn btn-primary" href="#" data-vn-popup-close>Schließen</a>

Bloque un iframe ou un script dans l'export jusqu'à ce que le visiteur ait accepté la catégorie dans VN Cookie Consent. Ne s'applique que si l'avis sur les cookies du projet est activé.

Syntaxe

html
<iframe src="https://example.com/karte" data-vn-consent-category="functional"></iframe>

Valeurs : functional, statistics, marketing. Le programme reconnaît lui-même les services connus (cartes, YouTube, outils d'analyse) ; l'attribut est la voie pour tout le reste. Lors du blocage, il écrit src dans data-vn-cc-src et pose type="text/plain" sur les scripts. Voir Cookie Consent et protection des données.

Sur un lien (<a>) : ouvre les paramètres des cookies. La boîte de dialogue de lien l'écrit elle-même lorsque l'utilisateur choisit « Ouvrir les paramètres des cookies ». Voir Ouvrir les paramètres des cookies.

html
<a href="#" data-vn-cookie-settings>Cookie-Einstellungen</a>

data-vn-anim et data-vn-anim-t#

Une animation sur un texte ou une image. L'outil « VN Animation » la pose ; dans l'export figurent data-vn-anim="fadeUp" (nom de l'animation) et data-vn-anim-t="scroll" (déclencheur : scroll, load ou hover) avec les variables en ligne --vn-a, --vn-d, --vn-dl, --vn-e, --vn-n. À partir de ces marqueurs, l'export crée les @keyframes et le petit script pour « à l'apparition ». Les écrire à la main n'a de sens que si vous écrivez aussi les variables en ligne ; utilisez l'outil pour cela.

data-multiline#

Comme vn-article : fait d'une liste un champ avec saisie par ligne. Voir vn-article.

Marqueurs posés par le programme#

Le programme pose ces attributs à l'import ou lors du dessin. Ne les écrivez pas vous-même ; ils figurent dans le modèle enregistré (et dans l'éditeur de code) et disparaissent dans l'export.

AttributPosé surBut
data-vn-text-id="tN"chaque texte modifiableidentifiant stable (clé des modifications de texte)
data-vn-image-key="feld"<img src="{{feld}}"> et l'élément racine avec un widget d'arrière-planun clic ouvre la sélection d'image pour ce champ
data-vn-free-image-id="fiN"images fixes dans le balisageremplacement par un clic
data-vn-button-id="btnN", data-vn-btn-extra-classeschaque <a class="btn">dialogue de bouton ; les classes supplémentaires sont conservées
data-vn-icon-id="iconN", data-vn-icon-extra-classeschaque icônedialogue d'icône

Les cinq groupes sont intégrés et retirés lors de l'export. Comment ils apparaissent et ce qu'ils font : Contenus modifiables directement. D'autres attributs purement internes (data-vn-text-color, data-vn-svg, data-vn-tip-*, data-vn-cms*, data-vn-drag*) ne sont pas traités dans ce chapitre ; ils relèvent des outils et du CMS.

Anciennes notations#

À l'import, le programme accepte encore les noms d'anciens paquets et les réécrit ; lors du dessin, il comprend les deux notations. Cette liste ne sert qu'à la compatibilité. Les nouveaux blocs utilisent les noms VN.

Ancienne notationAujourd'huiRemarque
mbr-parametersvn-parametersbalise ; les deux sont lues
mbr-ifvn-if
mbr-classvn-class
mbr-stylevn-style
mbr-theme-stylevn-theme-styleà l'import seulement pour les thèmes avec tailles de police d'affichage ; sinon l'attribut reste sans effet
mbr-buttonsvn-buttons
mbr-menuvn-menu
mbr-videovn-video
mbr-icondata-vn-icon
mbr-articlevn-article
{{mbr-id}}{{vn-id}}les deux sont remplacées
classe mbr-overlayclasse vn-overlayles deux sont évaluées (la classe n'est pas renommée à l'import)

Ces classes restent inchangées à l'import, car le CSS de thème et les plugins les utilisent. Le programme les connaît toujours :

ClasseSignification pour le programme
mbr-text, mbr-section-title, mbr-title, mbr-fonts-styledétection du texte (en plus des balises h1 à h6, p, li …) et cible des règles de police valables pour tout le site
mbr-iconfont, mbri-…détection d'icône ; la classe mbri-… est retirée, l'icône reste vide jusqu'au choix
mbr-fallback-imagecalque d'image de remplacement que le programme insère lui-même pour data-bg-video
mbr-parallax-backgrounddéclenche le plugin de parallaxe en mode thème Bootstrap

Attributs d'anciens paquets que le programme n'évalue pas et qui restent sans effet dans le balisage : data-app-selector, data-app-placeholder, data-toolbar, always-top, not-draggable, position-absolute et group="…" sur l'élément racine.