Le modèle (template.html)
Structure de template.html : élément racine et ses attributs, espaces réservés {{…}} avec expressions et fonctions d'aide, images et liens, Bootstrap, blocs valables pour tout le site et ce qui se passe dans l'éditeur et dans l'export.
Structure#
template.html décrit le balisage d'un bloc. Il se compose d'un élément racine qui englobe tout le reste. Dans l'élément racine figurent d'abord le bloc <vn-parameters> (les champs de saisie, voir Champs de saisie), puis le balisage proprement dit avec espaces réservés et directives.
<section class="mb-karte">
<vn-parameters>
<header>Größe</header>
<input type="range" title="Abstand" name="abstand" min="0" max="8" step="1" value="3">
</vn-parameters>
<div class="container">
<h2>Willkommen</h2>
<p vn-if="abstand > 1">Text mit Abstand {{abstand}}</p>
</div>
</section>L'élément racine#
Le premier élément du fichier est la racine (section ; pour le menu et le pied de page aussi nav ou footer). Le programme ajoute à la racine ce qui marque le bloc comme instance :
- la classe d'instance
vn-imp-<alias>-<ID du bloc>(le CSS du bloc repose dessus, voir LESS : Portée et racine), - l'
idblk-<ID du bloc>, ou l'ID d'ancre fixé par l'utilisateur. Si la racine porte elle-même unid, il est conservé.
Le bloc de paramètres#
<vn-parameters> va dans la racine (pas avant) et est retiré lors du dessin. Détails : Champs de saisie.
Balisage#
Tout le reste est du HTML5 ordinaire avec ces ajouts :
- Les espaces réservés
{{…}}insèrent des valeurs (Espaces réservés). - Les directives (
vn-if,vn-class,vn-style…) rendent des éléments dépendants de valeurs (Directives). - Les classes de Bootstrap 5 et de Bootstrap Icons sont disponibles (Bootstrap).
- Les scripts (
<script>sanssrc) restent dans le balisage ; voir Scripts dans les blocs. - Les textes, images, boutons et icônes deviennent automatiquement modifiables dans l'éditeur (Contenus modifiables directement).
Attributs sur l'élément racine#
Le programme évalue ces attributs sur l'élément racine.
global#
Rend le bloc valable pour tout le site : il n'existe qu'une fois dans le projet et apparaît sur chaque page (menu, pied de page).
Syntaxe
<nav global once="menu" class="navbar vn-menu"> … </nav>
<footer global once="footers" class="vn-footer"> … </footer>Attributs
| Nom | Valeur | Par défaut | Signification |
|---|---|---|---|
global | interrupteur | – | Le bloc est valable pour tout le site. Doit figurer sur le tout premier élément du fichier (vérifié : un bloc <vn-parameters> placé avant, ou un div englobant, empêche la détection) |
Tout le reste (groupes, position dans l'export, remplacement) se trouve sous Blocs valables pour tout le site.
once#
Le nom du groupe d'un bloc valable pour tout le site. Chaque groupe a au plus un bloc dans le projet : un bloc inséré ensuite remplace l'ancien.
| Valeur | Signification |
|---|---|
menu | groupe « Menu » : dans l'export, le bloc se place au-dessus du contenu de la page |
footers | groupe « Pied de page » : le bloc se place en dessous |
| autre texte | groupe portant ce nom ; placé en haut si le nom contient menu, nav ou header (la casse ne compte pas), sinon en bas |
once sans global n'a aucun effet (vérifié). Sans once, le groupe s'appelle global.
group#
group="Content" sur l'élément racine figure dans de nombreux paquets. Le programme ne l'évalue pas. La catégorie dans la sélection vient de _group dans params.json (Désignations). Vous pouvez omettre l'attribut.
plugins#
plugins="DropDown, TouchSwipe" nomme les dossiers de plugins dont a besoin un bloc issu d'un thème Bootstrap 4. Il n'agit qu'en mode thème Bootstrap du projet et seulement sur un <section> : l'export charge alors en plus les scripts de ces plugins (voir Mode Bootstrap). Il est superflu pour les blocs reposant sur le Bootstrap 5 fourni.
data-bs-version#
data-bs-version="5.1" repère un bloc comme conçu pour Bootstrap 5. Son seul effet : si un tel bloc arrive dans un projet qui fonctionne en mode thème Bootstrap (Bootstrap 4), le programme affiche une remarque indiquant qu'il peut avoir un aspect différent.
data-bg-video#
Porte l'adresse d'une vidéo d'arrière-plan pour tout le bloc. La valeur est en général un espace réservé qui ne donne une adresse que lorsque la vidéo est choisie.
Syntaxe
<section class="mein-header" data-bg-video="{{bg.type == 'video' && bg.value.url}}">
<vn-parameters>
<fieldset name="bg">
<input type="video" title="Video" value="">
<input type="image" title="Bild (Ersatzbild)" value="../_images/ersatz.jpg" selected>
<input type="color" title="Farbe" value="#111111">
</fieldset>
</vn-parameters>
…
</section>Comportement (vérifié)
- Si la valeur est vide ou
false,undefined,null,0, rien ne se passe (avec un autre type d'arrière-plan, le HTML contientdata-bg-video="false"). - Sinon, le programme insère comme premier enfant de la racine un calque
<div>pour l'image de remplacement (sa classe figure sous Anciennes notations) et ajoute du CSS : racineposition: relative; overflow: hidden, calque absolu et remplissant,.container/.container-fluidàz-index: 2. Les règles sont dans:where(…)afin qu'un CSS de thème propre ait la priorité. - Dans l'export, la page charge
vendor/vn-bgvideo/vn-bgvideo.jssi au moins un bloc porte une adresse vidéo. Le script intègre la vidéo (YouTube, Vimeo ou fichier) à l'affichage de la page. Lorsque VN Cookie-Consent est activé, YouTube et Vimeo ne se chargent, à partir de la version 1.3.100, qu'après l'accord pour « Marketing » (d'ici là, l'image de remplacement reste affichée ; voir Lecture sur la page). Dans l'éditeur, on ne voit que l'image de remplacement.
vn-strict-if#
Un marqueur sur la racine (ou un élément quelconque) qui rend vn-if strict dans tout le bloc. Voir vn-strict-if.
id et class#
Les valeurs de class propres restent, la classe d'instance s'y ajoute. Un id propre est conservé ; sans id, le programme pose blk-<ID du bloc> ou l'ID d'ancre de l'utilisateur. Dans les références à l'intérieur du bloc, utilisez {{vn-id}} (Espaces réservés), pas des ID fixes : le même bloc peut figurer plusieurs fois sur une page.
Attributs non évalués#
Ces attributs figurent sur l'élément racine dans d'anciens paquets. Le programme les ignore ; ils restent dans le balisage et ne gênent pas : group, always-top, not-draggable, position-absolute, data-app-selector, data-app-placeholder, data-toolbar.
Espaces réservés#
Un espace réservé {{expression}} est remplacé par son résultat lors du dessin. Cela vaut partout dans le modèle : dans le texte, dans les attributs, dans <script> et <style>. L'expression est du JavaScript (Expressions) et connaît toutes les valeurs du bloc sous leur nom.
{{name}}#
Insère la valeur d'un champ.
Syntaxe
<h2>{{titel}}</h2>
<div style="min-height:{{hoehe}}vh"></div>
<img src="{{foto}}" alt="">Exemple (tiré de themes/vn-studio-src/components/header1)
<section class="vn-hero" vn-class="{'vs-fullscreen': fullScreen}" style="min-height:{{hoehe}}vh">Ce que devient le résultat (vérifié)
| Résultat de l'expression | inséré comme |
|---|---|
| texte, nombre | le texte |
true, false | true, false |
undefined, null (aussi en cas d'erreur dans l'expression) | texte vide, sans message |
liste [1,2] | 1,2 |
| objet | [object Object] |
Expressions#
Entre les accolades peut figurer n'importe quelle expression JavaScript, pas seulement un nom.
<p>{{ n > 3 ? 'viel' : 'wenig' }}</p>
<div style="height:{{logoSize * 1.8}}rem"></div>
<a data-n="{{ Number(anzahl) + 1 }}">…</a>- Les espaces autour de l'expression sont retirés.
- Dans les attributs, le programme reconvertit
&&(&&),<,>,",'et&avant l'évaluation :data-bg-video="{{bg.type == 'video' && bg.value.url}}"fonctionne. - Les valeurs
rangesont du texte :{{n + 1}}donne le texte41pourn = "4";{{n * 2}}donne8(vérifié). - Les objets standard de JavaScript (
Math,String…) sont disponibles. - Une erreur donne un texte vide ; il n'y a pas de message d'erreur. Vérifiez dans l'éditeur les expressions inhabituelles.
Champs d'objet#
Le widget d'arrière-plan fournit un objet. Dans le modèle, ces champs sont disponibles (nom du widget ici bg) :
| Expression | Image | Couleur | Vidéo |
|---|---|---|---|
{{bg.type}} | image | color | video |
{{bg.value}} | l'adresse de l'image | #rrggbb | [object Object] |
{{bg.value.url}} | l'adresse de l'image | – | l'adresse de la vidéo |
{{bg.parallax}} | true/false | false | false |
Pour une image, bg.value se comporte dans le modèle comme l'adresse en texte et possède .url (vérifié) : les deux notations url({{bg.value}}) et url({{bg.value.url}}) fonctionnent.
<div class="deckel" style="background-image: url({{bg.value}});"></div>Voir Widget d'arrière-plan.
{{vn-id}}#
Donne l'identifiant de l'instance : blk-<ID du bloc> ou l'ID d'ancre de l'utilisateur. Avec lui, vous formez des ID qui restent uniques même avec plusieurs blocs identiques sur une page. Le remplacement vaut dans tout le modèle, aussi dans le texte de <script>.
Syntaxe
<button class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#{{vn-id}}-nav"></button>
<div class="collapse navbar-collapse" id="{{vn-id}}-nav"> … </div>vnEnc(texte)#
Échappe un texte pour un attribut data-… : le résultat est encodeURIComponent(String(valeur)) ; undefined et null donnent un texte vide. Dans le script, vous le relisez avec decodeURIComponent.
Syntaxe
<h1 data-swapwords="{{vnEnc(swapWords)}}">…</h1>var worte = decodeURIComponent(h.getAttribute("data-swapwords") || "").split("|");Exemple (tiré de gallery-content/vn-kinetic-theme, bloc « Hero 1 ») : les mots proviennent d'un champ de texte du panneau qui peut contenir n'importe quel caractère. Plus : Données de texte dans les attributs.
vnEmbed(adresse)#
Convertit une adresse YouTube ou Vimeo en adresse intégrable ; les autres adresses restent inchangées.
<iframe src="{{vnEmbed(videoUrl)}}" allowfullscreen></iframe>| Entrée | Résultat |
|---|---|
https://youtu.be/dQw4w9WgXcQ | https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?rel=0&modestbranding=1&playsinline=1 |
https://vimeo.com/76979871 | https://player.vimeo.com/video/76979871 |
| autre adresse | inchangée |
Espaces réservés dans les boutons#
Dans un bouton (<a class="btn …">), les espaces réservés dans le texte et le href ne sont pas évalués. Le programme reconstruit chaque bouton à partir de sa valeur par défaut et des modifications de l'utilisateur dans la boîte de dialogue du bouton ; la valeur par défaut est le texte brut du modèle, de sorte que {{name}} apparaît tel quel sur la page (vérifié dans l'éditeur et dans l'export).
<a class="btn btn-primary" href="{{ziel}}">{{beschriftung}}</a> Ce qui fonctionne : un espace réservé dans un lien ordinaire (<a href="{{ziel}}">Text {{x}}</a> sans la classe btn), dans un <button> et dans des attributs comme title ou alt. L'utilisateur gère le texte du bouton et la cible sur le bouton lui-même.
Espaces réservés dans les scripts et les attributs#
Le remplacement s'effectue sur le texte du modèle, avant sa lecture comme HTML. Il en découle :
- Un espace réservé fonctionne aussi dans le contenu de
<script>(var s = "{{n}}";donnevar s = "2";). - Une valeur contenant
"casse un attribut ; une valeur contenant<ou>peut modifier le balisage. Pour les textes du panneau, utilisezvnEncou insérez-les seulement comme contenu textuel. - Chaque
{{ … }}du modèle est évalué comme expression, y compris dans le code JavaScript. Une suite{{ou}}dans le script (par exemplefunction(){{…}}ou une expression d'objet imbriquée) donne un résultat absurde ou un texte vide. Écrivez les accolades dans le script avec des espaces ({ {,} }) ou sur des lignes séparées.
Images et liens#
La manière dont les images et les liens deviennent remplaçables dans l'éditeur est décrite dans Contenus modifiables directement. Pour le modèle, on retient :
- Champ d'image :
<img src="{{feld}}">, oùfeldest un champtype="image". Exactement un espace réservé commesrc(sans autre texte) repère l'image ; un clic dessus ouvre dans l'éditeur la sélection d'image pour ce champ. - Image d'arrière-plan :
style="background-image: url({{bg.value}});"(dansstyleou dansvn-style) repère cet élément pour le widgetbg. En outre, avec un widget d'arrière-plan, c'est toujours la racine qui porte ce repère. - Image fixe :
<img src="https://…">ou unstyleavecbackground-image: url(…)sans espace réservé est une image libre et peut être remplacée par un clic. - Liens : les espaces réservés dans
hreffonctionnent pour les liens ordinaires (<a href="{{ziel}}">), pas pour les boutons (voir ci-dessus). - Adresses de fichiers : dans le projet, les images figurent sous la forme
file:///…/assets/…. L'export réécrit chaque adresse de ce type dans le HTML et le CSS enassets/…et copie les fichiers ; seuls les fichiers référencés sont inclus.
Bootstrap et classes#
Le programme fournit Bootstrap 5.0.1 (grille, classes utilitaires, composants) et les Bootstrap Icons. Les deux sont disponibles dans l'éditeur et dans chaque page exportée (vendor/bootstrap.min.css, vendor/bootstrap.bundle.min.js, vendor/bootstrap-icons/) ; les blocs n'ont rien à inclure.
- Utilisez les classes de Bootstrap 5 (
container,row,col-md-6,d-flex,gap-3,btn,btn-primary…) etbi bi-<nom>pour les icônes. - jQuery n'est pas disponible (seulement en mode thème Bootstrap pour les thèmes Bootstrap 4).
- Les composants JS de Bootstrap fonctionnent via des attributs
data-bs-…(data-bs-toggle="collapse"). Les attributs de la version 4 (data-toggle,data-target…) sont complétés à l'import par leur équivalentdata-bs-…(Attributs Bootstrap). - Donnez à vos classes des noms avec le préfixe du bloc (
mb-karte,vnkn-hero). Le CSS du bloc est limité à l'instance, mais les classes du CSS de thème et de Bootstrap ne le sont pas.
Blocs valables pour tout le site#
Menu et pied de page appartiennent à chaque page. Un bloc avec global sur l'élément racine ne se trouve pas dans une page mais dans la liste des blocs globaux ; dans l'export, il figure sur chaque page, les groupes de menu en haut, tous les autres en bas, et son CSS une seule fois dans style.css. Tout le reste : Blocs valables pour tout le site : global et once.
Éditeur et export#
Le même modèle est dessiné deux fois : pour la zone de travail et pour l'export. Les deux utilisent la même fonction de dessin (render) ; ensuite, ils diffèrent.
| Éditeur | Export | |
|---|---|---|
<vn-parameters> | retiré | retiré |
{{…}}, directives | évaluées | évaluées (même résultat) |
| Textes, images, boutons, icônes | contenteditable, identifiants data-vn-…, classes comme vn-editable-text ; un clic ouvre des dialogues | modifications intégrées, tous les identifiants de l'éditeur retirés |
data-vn-editor-only | visible | retiré (Scripts) |
<script> dans le bloc | s'exécute via des substituts de window, document, minuteries ; chaque nouveau dessin arrête les anciennes minuteries | reste inchangé dans la page (Scripts) |
| Vidéos avec lecture automatique | ne démarrent pas | démarrent (sans son) |
Vidéo d'arrière-plan (data-bg-video) | image de remplacement | vidéo via vn-bgvideo.js |
| Adresses d'images | file:///… | assets/… |
| CSS | @layer vn-blocks, Bootstrap et thème dans @scope (#canvas) | un style.css, pas de couches (Priorité) |
PHP (<script type="text/x-vn-php">) | ne s'exécute pas | est remplacé par le code PHP brut ; la page a besoin de l'extension .php (le programme propose de la renommer) |
| Popup, CMS | cadre et marquage | conteneur de popup, marqueurs CMS et appels PHP |