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) :
<vn-parameters>est retiré.{{vn-id}}est remplacé par l'identifiant de l'instance.- Chaque
{{expression}}est évaluée et remplacée par son résultat (Espaces réservés). - Le résultat est lu comme du HTML.
- 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 pourvn-overlay. - 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.
| Directive | Effet |
|---|---|
vn-if | retirer l'élément |
vn-strict-if | marque le bloc : vn-if vérifie strictement |
vn-class | ajouter des classes sous condition |
vn-style | poser des styles en ligne sous condition |
vn-theme-style | ajouter des classes de thème |
vn-overlay | surface d'assombrissement avec opacity et bg-color |
vn-buttons, vn-menu | marqueurs pour vn-theme-style |
vn-video | bloc vidéo avec champ d'adresse dans le panneau |
vn-article | liste extensible |
data-vn-icon | repé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 donneundefined, sans message. undefinedn'est pasfalse: en mode standard,vn-ifne retire que surfalseexact. Voir vn-if.- Les objets standard de JavaScript (
Math,String,Number,JSON…) sont disponibles. - Dans un attribut HTML, écrivez
&&sous la forme&&,<sous la forme<. À 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
rangesont du texte. Comparez avecn > 3(JavaScript convertit) ou calculez avecn * 1;n + 1concatène. Voir range. - Les valeurs des champs
checkboxsonttrueoufalse, 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
<p vn-if="showText">Beschreibung</p>
<div vn-if="overlay && bg.type !== 'color'"></div>Exemple (tiré de themes/vn-studio-src/components/header1)
<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) | true | reste |
showText (false) | false | retiré |
mode == 'b' (comparaison fausse) | false | retiré |
!!titel (texte vide) | false | retiré |
titel (texte vide) | "" | reste |
n (texte "4" ou "0") | texte | reste |
gibtsNicht (nom inconnu) | erreur, undefined | reste |
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
<section class="mein-block" vn-strict-if>
<div vn-if="overlay">…</div>
</section>Différences avec le mode standard (vérifié)
| Standard | avec vn-strict-if | |
|---|---|---|
| Élément retiré pour | false exact | toute valeur fausse : false, 0, texte vide, null, undefined |
| Nom inconnu | l'élément reste | le nom vaut undefined, l'élément est retiré |
| Erreur dans l'expression | l'élément reste | l'élément est retiré |
Math, String … | disponibles | disponibles |
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
<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ésultat | Effet |
|---|---|
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 erreur | rien |
Exemple (tiré de themes/vn-studio-src/components/menu1)
<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
<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 ounullne 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 attributstyleordinaire 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)
<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
<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 est | Les classes atterrissent sur |
|---|---|
un conteneur avec vn-buttons | chaque .btn qu'il contient |
un conteneur avec vn-menu | chaque .nav-link et .dropdown-item qu'il contient |
| sinon | l'é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
<div class="vn-overlay" vn-if="overlay" opacity="{{overlayOpacity}}" bg-color="{{overlayColor}}"></div>Attributs
| Nom | Valeur | Signification |
|---|---|---|
opacity | nombre de 0 à 1 | devient le style en ligne opacity |
bg-color | couleur | devient 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.
<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.
<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
<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, unvideoou (pour un conteneur sans vidéo par défaut) l'attributdata-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>(icompte 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 devientplayer.vimeo.com/video/…; un fichier (.mp4,.webm,.ogv,.m4v, une adressefile:ouassets/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
<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
<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-iconn'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 saufbietbi-…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.
<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.
<a class="btn btn-primary" href="#" data-vn-popup-close>Schließen</a>data-vn-consent-category#
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
<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.
data-vn-cookie-settings#
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.
<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.
| Attribut | Posé sur | But |
|---|---|---|
data-vn-text-id="tN" | chaque texte modifiable | identifiant 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-plan | un clic ouvre la sélection d'image pour ce champ |
data-vn-free-image-id="fiN" | images fixes dans le balisage | remplacement par un clic |
data-vn-button-id="btnN", data-vn-btn-extra-classes | chaque <a class="btn"> | dialogue de bouton ; les classes supplémentaires sont conservées |
data-vn-icon-id="iconN", data-vn-icon-extra-classes | chaque icône | dialogue 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 notation | Aujourd'hui | Remarque |
|---|---|---|
mbr-parameters | vn-parameters | balise ; les deux sont lues |
mbr-if | vn-if | |
mbr-class | vn-class | |
mbr-style | vn-style | |
mbr-theme-style | vn-theme-style | à l'import seulement pour les thèmes avec tailles de police d'affichage ; sinon l'attribut reste sans effet |
mbr-buttons | vn-buttons | |
mbr-menu | vn-menu | |
mbr-video | vn-video | |
mbr-icon | data-vn-icon | |
mbr-article | vn-article | |
{{mbr-id}} | {{vn-id}} | les deux sont remplacées |
classe mbr-overlay | classe vn-overlay | les 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 :
| Classe | Signification pour le programme |
|---|---|
mbr-text, mbr-section-title, mbr-title, mbr-fonts-style | dé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-image | calque d'image de remplacement que le programme insère lui-même pour data-bg-video |
mbr-parallax-background | dé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.