Scripts dans les blocs et les thèmes
Comment un bloc apporte du JavaScript, comment il reconnaît l'éditeur, ce que l'éditeur fait des scripts, comment le consentement aux cookies et la protection des données sont intégrés, quelles bibliothèques sont fournies sous vendor/ et quels pièges existent.
Vue d'ensemble#
Un bloc apporte du JavaScript sous forme de <script> en ligne dans le template. Il n'existe pas de fichier JS propre à chaque bloc ou thème. Le script se trouve en général à la fin de l'élément racine et est livré avec le template : dans l'éditeur, dans l'aperçu et dans l'export.
| Lieu | Le script s'exécute-t-il ? | Comment |
|---|---|---|
Export (publish/), aperçu dans le navigateur et aperçu en direct | oui, normalement | La page est servie par un serveur local (preview-server.cjs), le script s'exécute comme sur la vraie page |
| Éditeur (zone de travail) | oui, isolé | src/editor-scripts.js exécute les scripts en ligne après chaque rendu avec des substituts (voir Comportement dans l'éditeur) ; peut être désactivé |
| Éditeur de code | non | Seul le HTML du template y est affiché |
Ordre d'une page exportée (d'après buildExportHtml) :
<head>: CSS de Bootstrap, CSS de Bootstrap Icons, les fichiers CSS des bibliothèques d'exécution utilisées,style.css.<body>: le code HTML de tous les blocs de la page dans l'ordre, chacun avec ses scripts en ligne.- Ensuite
vendor/bootstrap.bundle.min.js, puis les scripts des bibliothèques d'exécution (lightbox, consentement aux cookies, popup, CMS, vidéo …), puis les scripts de l'utilisateur.
Scripts dans les blocs#
Script en ligne dans le template#
Syntaxe
<section class="va va-inhalt" group="Content">
<vn-parameters> … </vn-parameters>
<div class="va-in" data-anim="{{anim}}"> … </div>
<script>(function(){
[].forEach.call(document.querySelectorAll(".va-in"), function(R){
if (R.__vaInit) return; R.__vaInit = 1; /* une seule fois par élément */
if (R.closest("#canvas")) return; /* ne rien faire dans l'éditeur */
/* … effet … */
});
})();</script>
</section>(Modèle tiré de gallery-content/vn-bloecke/src/artikel/inhalt/template.html ; le marqueur y figure sous forme d'attribut data-va-init, la propriété JS est recommandée.)
| Règle | Description |
|---|---|
| Emplacement | À l'intérieur de l'élément racine, en général comme dernier enfant |
| Type | Seul un <script> sans src et sans type étranger est exécuté dans l'éditeur (type vide, text/javascript, application/javascript, module) |
| Types étrangers | type="text/x-vn-php" (code PHP protégé) et les blocs de données JSON ne sont pas exécutés par l'éditeur et ne sont pas touchés par le consentement aux cookies |
| Substituts | {{…}} est remplacé dans tout le template, y compris dans le texte du script. Une double accolade ouvrante dans le script (par exemple un littéral d'objet dans un littéral d'objet, {{a:1}}) est évaluée comme une expression : écrivez { { ou évitez cette suite |
| Conditions | vn-if sur le <script> est possible ; s'il disparaît, le script manque |
| Fichiers externes | <script src="…"> s'exécute dans l'export, pas dans l'éditeur. Évitez les serveurs tiers (CDN) pour des raisons de protection des données |
Initialisation unique#
Le script doit trouver tous les éléments de son bloc dans le document et n'initialiser chacun qu'une seule fois. Définissez le marqueur comme propriété JavaScript de l'élément, pas comme attribut data-.
Syntaxe
(function () {
var roots = document.querySelectorAll(".mein-block");
Array.prototype.forEach.call(roots, function (box) {
if (box.vnInit) return; // déjà fait (propriété, pas un attribut)
box.vnInit = 1;
if (box.closest("#canvas")) return;
// … initialisation …
});
})();| Marqueur | Adéquation | Raison |
|---|---|---|
Propriété JS (box.vnInit = 1) | recommandé | Appartient à l'élément, jamais dans le HTML, jamais dans le template enregistré, jamais dans l'export |
Attribut data-… | à éviter | Le script parcourt tous les éléments de la page ; un ancien script de bloc posait l'attribut sur des éléments de nouveaux blocs, et ceux-ci n'étaient alors jamais initialisés. De plus, un attribut se retrouve dans le DOM, qui peut être figé plus tard |
Variable globale (window.fertig = true) | uniquement pour des fonctions auxiliaires communes | Dans l'éditeur, window.… ne vaut que pour une passe de rendu (voir plus bas) ; sur la vraie page, elle reste en place pour tous les blocs |
Espace de noms commun pour plusieurs instances (tiré du bloc « Intégration vidéo ») :
(function () {
var V = window.vfvd = window.vfvd || {}; // créer une seule fois, réutiliser ensuite
if (!V.parse) {
V.ed = function (e) { return !!(e && e.closest && e.closest("#canvas")); };
V.parse = function (raw) { /* … */ };
}
// … pour chaque instance …
})();Ordre et attente#
Au moment où le script de bloc s'exécute (analyse de <body>), les éléments suivants n'existent pas encore : window.bootstrap, window.vnCookieConsent, window.VNPopup, les éléments situés plus bas dans la page. Attendez DOMContentLoaded ou load.
function late(fn) {
if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", fn);
else fn();
}
late(function () {
var cc = window.vnCookieConsent; // disponible maintenant (si le consentement aux cookies est activé)
var BS = window.bootstrap; // Bootstrap 5.0.1
});Dans l'éditeur, DOMContentLoaded et load sont déjà passés ; l'éditeur appelle immédiatement ces rappels (avec un léger décalage) et indique document.readyState === "complete". La même écriture fonctionne donc aux deux endroits.
Marqueur data-vn-editor-only#
Les éléments avec data-vn-editor-only sont des leurres pour l'éditeur. L'export les supprime (publish.js : container.querySelectorAll('[data-vn-editor-only]').forEach(remove)). Cas typiques : lignes d'indication (« Aucune vidéo choisie »), exemples de contenu pour des sorties PHP qui ne s'exécutent pas dans l'éditeur.
Syntaxe
<div class="vn-bgvid-empty" data-vn-editor-only vn-if="!videoFile && !videoUrl">
Noch kein Video gewählt — im Eigenschaften-Panel unter „Video“ eine Datei wählen.
</div>| Attribut | Valeur | Signification |
|---|---|---|
data-vn-editor-only | interrupteur | L'élément apparaît dans l'éditeur et dans l'aperçu du bloc, pas dans l'export |
Reconnaissance de l'éditeur#
Reconnaissance avec el.closest('#canvas')#
La seule reconnaissance fiable est la position dans le canvas : la zone de travail est un élément d'ID canvas dans le même document que le programme (pas d'iframe). Un élément de bloc a #canvas pour ancêtre dans l'éditeur, mais pas dans l'export ni dans l'aperçu.
Syntaxe
var inEditor = !!el.closest("#canvas");
if (inEditor) return; // ou omettre seulement l'effet, mais définir le contenuValeur de el.closest("#canvas") | Signification |
|---|---|
| Élément | Éditeur (zone de travail) |
null | Export, aperçu ou aperçu en direct |
Éditeur, aperçu et export en comparaison#
| Caractéristique | Éditeur (zone de travail) | Aperçu et aperçu en direct | Export |
|---|---|---|---|
| Scripts de bloc | isolés, après chaque rendu | normal | normal |
el.closest("#canvas") | Élément | null | null |
window.bootstrap | présent | présent (après les scripts de bloc) | présent (après les scripts de bloc) |
| jQuery | non | non (uniquement en mode thème Bootstrap) | non (uniquement en mode thème Bootstrap) |
| Bibliothèques d'exécution (lightbox, consentement, popup …) | non (exception : VN Sous-menu) | oui, comme dans l'export | oui, si utilisées |
Éléments data-vn-editor-only | visibles | supprimés | supprimés |
| PHP | ne s'exécute pas (leurres) | s'exécute via le serveur local | s'exécute sur votre serveur |
| Envoi d'e-mails | — | vers un récepteur de courrier local (fichiers .eml) | via votre serveur SMTP |
Ce qui ne convient pas à la reconnaissance#
Vérifié dans une instance en cours d'exécution :
| Moyen | Résultat dans l'éditeur | Conséquence |
|---|---|---|
document.documentElement.classList.contains("is-builder") | false | Le programme ne pose jamais la classe ; il ne l'active délibérément pas globalement pour ne pas activer les règles .is-builder à chaque bloc importé |
document.body.classList.contains("is-builder") | false | comme ci-dessus (seule la lightbox en tient compte) |
document.currentScript | null | L'éditeur exécute les scripts via new Function ; un script qui cherche son bloc via currentScript a besoin d'un repli (document.querySelector(…)) |
window.self !== window.top | false | Il n'y a pas d'iframe |
Comportement dans l'éditeur#
Substituts au lieu d'une exécution libre#
La zone de travail fait partie de la fenêtre du programme. Un script de bloc ne s'exécute donc pas librement, mais dans une fonction qui masque les noms globaux par des substituts (new Function('document','window','location','setTimeout',…)). Ainsi, un script ne peut ni rediriger le programme ni continuer à s'exécuter après le rendu suivant.
| Accès dans le script | Comportement dans l'éditeur |
|---|---|
setTimeout, setInterval, requestAnimationFrame | Les rappels ne s'exécutent que tant que la passe de rendu dans laquelle le script a démarré est valide ; chaque nouveau rendu met fin à toutes les chaînes de l'ancien |
document.addEventListener('DOMContentLoaded'/'load'/'readystatechange', fn) et la même chose sur window | Le rappel s'exécute immédiatement (avec un décalage, setTimeout 0) |
window.onload = fn | est exécuté immédiatement comme rappel |
document.readyState | toujours complete |
document.write, document.writeln | ne fait rien |
location.assign, .replace, .reload ; location.href = … | ne fait rien ; la lecture fonctionne |
alert, confirm, prompt | ne font rien (confirm renvoie false, prompt null) |
autres appels document/window | normal (liés à l'objet réel) |
this, self, globalThis, window.window | le substitut |
Les erreurs du script sont seulement écrites dans la console (Block-Skript im Editor nicht ausgeführt: …) et ne perturbent pas la zone de travail.
Nouveau rendu et minuteries#
À chaque rendu de la zone de travail (renderCanvasNow), le programme appelle d'abord stopBlockScripts() (les minuteries et chaînes de la passe précédente prennent fin), reconstruit tous les blocs et exécute ensuite, quand tout est dans le document et que le CSS est appliqué, les scripts en ligne de chaque bloc. Presque chaque modification dans le panneau déclenche un rendu : le script s'exécute donc souvent de nouveau, sur des éléments neufs.
Les propriétés de window ne valent que pour une passe#
Ce qu'un script de bloc accroche à window (window.initialisiert = true, window.vfvd = {…}) va dans un stockage qui est rejeté au rendu suivant. Sinon, le dispositif de protection if (!window.fertig) { window.fertig = true; … } resterait en place, et le script ne redémarrerait plus jamais après le premier nouveau rendu. Sur la vraie page, cette limitation n'existe pas.
Vérifié : un script qui pose window.__leak = 5 ne laisse rien sur le vrai window ; après stopBlockScripts(), typeof window.initFlag vaut de nouveau undefined.
Désactivation#
Dans les paramètres de la page se trouve l'interrupteur pour les scripts de bloc dans l'éditeur (siteSettings.editorScripts, activé par défaut). Désactivé : les scripts de bloc ne s'exécutent jamais dans l'éditeur ; les blocs qui ne produisent leur contenu visible que par JavaScript n'affichent alors que l'état initial.
Règles pour les scripts dans l'éditeur#
| Règle | Justification |
|---|---|
Ne pas faire dans l'éditeur (no-op) tout ce qui déplace, masque ou remplace du DOM : reconstruction de carrousel, révélation avec opacity:0, repli, clonage | Sinon le contenu disparaît ou n'est plus cliquable |
| Définir malgré tout un état initial dépendant des paramètres (premier mot, valeur finale du compteur, date) et ne terminer qu'ensuite | Placer if (closest('#canvas')) return; tout au début fait que l'éditeur n'affiche pas les modifications du panneau (symptôme « la machine à écrire n'affiche pas le nouveau mot ») |
Ne jamais réécrire le contenu d'un champ de texte (pas de <span> par lettre, pas de innerHTML sur des éléments data-vn-text-id) | À la frappe suivante, le programme enregistre comme texte le innerHTML actuel du champ (événement de saisie) ; un état intermédiaire de l'effet deviendrait le texte enregistré |
| Pas de processus permanents sans fin qui ne s'arrêtent pas d'eux-mêmes | Les minuteries sont certes annulées, mais les écouteurs d'événements sur document/window restent jusqu'au rechargement |
Animations de texte à l'exécution#
Les effets qui découpent ou réécrivent du texte (afficher les lettres une à une, compteur qui monte, machine à écrire, mots qui changent) ont lieu à l'exécution dans le navigateur. Dans le HTML enregistré, le texte complet et statique figure toujours. C'est ainsi que les moteurs de recherche, le traducteur, le CMS et l'édition de texte le trouvent.
| Règle | Description |
|---|---|
| Source | Le vrai texte figure dans le template (ou dans un attribut data- comme data-words) |
| Effet | Le script ne découpe ou ne remplace le contenu qu'au chargement de la page |
| Éditeur | Aucun effet, seulement l'état initial (voir Règles) |
| Sans JavaScript | Le texte reste entièrement lisible |
| Avec « moins de mouvement » | L'effet est supprimé (section suivante) |
Pour des animations simples sans script propre, il existe l'outil VN Animation (Animations) : il pose des attributs data-vn-anim et fournit les keyframes et un petit script d'observation.
Moins de mouvement#
Tout ce qui bouge doit respecter le réglage système « Réduire les animations » : par CSS et par script.
Syntaxe
var RM = !!(window.matchMedia && matchMedia("(prefers-reduced-motion: reduce)").matches);
if (!RM && "IntersectionObserver" in window) { /* démarrer l'effet d'apparition */ }@media (prefers-reduced-motion: reduce) {
.mein-block .effekt { animation: none !important; transition: none !important; }
}| Bloc | Comportement avec « moins de mouvement » |
|---|---|
| VN Animation (règles d'export) | [data-vn-anim] { animation: none !important } |
VN Vidéo d'arrière-plan (vendor/vn-bgvideo) | La vidéo n'est pas lancée ; l'image d'aperçu reste |
| VN Popup | se ferme sans animation |
| VN Galerie (carrousel) | défile sans défilement doux |
Défilement doux vers les ancres (vn-bgvid-scroll) | saute au lieu de glisser |
Consentement aux cookies et protection des données#
Si VN Consentement aux cookies est activé dans les paramètres du projet, l'export bloque les contenus connus de tiers jusqu'à ce que la catégorie correspondante soit acceptée. Les contenus externes (cartes, vidéos, suivi) ne se chargent alors qu'après consentement ou clic.
Blocage automatique#
gateThirdPartyEmbeds (export, sur chaque bloc) et gateRawScriptText (insertions HTML globales) reconnaissent :
| Contenu | Reconnaissance | Catégorie |
|---|---|---|
Google Maps (<iframe src>) | google.<tld>/maps, maps.google., goo.gl/maps | functional |
| Intégration YouTube | youtube.com/embed/…, youtube.com/v/…, aussi youtube-nocookie.com (l'adresse IP part vers le fournisseur dès le chargement du lecteur) | marketing |
| Intégration Vimeo (à partir de la version 1.3.100) | player.vimeo.com/video/… (l'adresse de page vimeo.com/<n°> n'est pas une intégration et n'est pas reconnue) | marketing |
| Google Analytics / Tag Manager | <script src> avec googletagmanager.com, google-analytics.com ; code en ligne avec gtag(, googletagmanager, GoogleAnalyticsObject | statistics |
| Pixel Facebook | connect.facebook.net, facebook.com/tr ; en ligne fbq( | marketing |
Pour tout le reste, marquez vous-même l'élément :
<iframe src="https://example.com/widget" data-vn-consent-category="functional"></iframe>
<script src="https://example.com/stats.js" data-vn-consent-category="statistics"></script>| Attribut | Valeurs | Signification |
|---|---|---|
data-vn-consent-category | functional, statistics, marketing | L'élément est bloqué jusqu'à ce que la catégorie soit acceptée ; agit indépendamment du domaine |
Ce que l'export en fait
<div class="vn-cc-gate" data-vn-cc-category="marketing" style="width:560px;height:315px">
<iframe data-vn-cc-src="https://www.youtube-nocookie.com/embed/ID" …></iframe>
<div class="vn-cc-gate-overlay">
<p class="vn-cc-gate-text" data-vn-cc-category="marketing"></p>
<div class="vn-cc-gate-buttons"><button type="button" class="vn-cc-gate-accept"></button><button type="button" class="vn-cc-gate-settings"></button></div>
</div>
</div>
<script type="text/plain" data-vn-cc-category="statistics" data-vn-cc-src="https://example.com/stats.js"></script>| Marqueur | Signification |
|---|---|
data-vn-cc-src | Le src d'origine ; redevient src après consentement |
type="text/plain" + data-vn-cc-category | Script bloqué ; après consentement, un vrai <script> est inséré, type et data-vn-cc* disparaissent, les autres attributs restent |
.vn-cc-gate | Enveloppe avec surcouche (« Charger le contenu », « Paramètres ») ; « Charger le contenu » ne débloque que cette seule intégration |
Blocage propre au bloc (balisage de la barrière)#
Les blocs qui rechargent leur matériel externe par JavaScript (clic sur une image d'aperçu, carte) construisent eux-mêmes le blocage et utilisent la même interface. Le bloc reste ainsi indépendant du fait que le consentement soit activé ou non.
Interface window.vnCookieConsent (présente seulement après DOMContentLoaded ; uniquement si le consentement aux cookies est activé) :
| Appel | Retour | Signification |
|---|---|---|
getConsent() | { necessary: true, functional, statistics, marketing } (valeurs booléennes) | État du consentement ; sans décision, tout vaut false |
openSettings() | — | Ouvre la fenêtre des paramètres |
labelGates() | — | Réétiquette tous les .vn-cc-gate-text, .vn-cc-gate-accept et .vn-cc-gate-settings (à appeler après votre propre insertion) |
L'événement vn-cc-activated est déclenché sur l'enveloppe dès qu'elle a été débloquée (clic sur « Charger le contenu » ou consentement à la catégorie). Réagissez-y pour charger.
Schéma (abrégé de gallery-content/vn-bloecke/src/video/embed/template.html) :
var c = window.vnCookieConsent && window.vnCookieConsent.getConsent ? window.vnCookieConsent : null;
function ask(host, go) {
if (!c || c.getConsent().marketing) { go(); return; } // sans consentement ou déjà autorisé
host.classList.add("vn-cc-gate");
host.setAttribute("data-vn-cc-category", "marketing");
var o = document.createElement("div");
o.className = "vn-cc-gate-overlay";
o.innerHTML = '<p class="vn-cc-gate-text" data-vn-cc-category="marketing"></p>'
+ '<div class="vn-cc-gate-buttons"><button type="button" class="vn-cc-gate-accept"></button>'
+ '<button type="button" class="vn-cc-gate-settings"></button></div>';
host.appendChild(o);
if (c.labelGates) c.labelGates();
host.addEventListener("vn-cc-activated", function f() {
host.removeEventListener("vn-cc-activated", f);
o.remove(); host.classList.remove("vn-cc-gate", "vn-cc-activated");
go();
});
}Événement vn-cc-consent#
À partir de la version 1.3.100, VN Cookie-Consent déclenche sur le document l'événement vn-cc-consent après chaque nouveau choix du visiteur (« Enregistrer », « Tout accepter », « Nécessaires uniquement ») ; event.detail est le nouveau consentement (le même objet que getConsent()). Il n'est pas déclenché au chargement de la page avec un choix déjà enregistré, ni au clic sur « Charger le contenu » d'une enveloppe isolée (c'est le rôle de vn-cc-activated). Un script qui ne doit charger quelque chose qu'après consentement vérifie donc getConsent() au démarrage et écoute en plus l'événement :
function ok() {
var c = window.vnCookieConsent;
return !c || !c.getConsent || !!c.getConsent().marketing; // ohne Cookie-Consent auf der Seite: sofort
}
function start() { /* Fremdinhalt laden */ }
if (ok()) start();
else document.addEventListener("vn-cc-consent", function f() {
if (!ok()) return;
document.removeEventListener("vn-cc-consent", f);
start();
});C'est ainsi que fonctionne la vidéo d'arrière-plan (vendor/vn-bgvideo/vn-bgvideo.js) : lorsque le consentement aux cookies est activé, les arrière-plans YouTube et Vimeo ne se chargent qu'après l'accord du visiteur pour « Marketing » ; l'image de remplacement reste affichée d'ici là (Arrière-plan vidéo).
YouTube et Vimeo seulement après un clic#
Le principe de protection des données : il n'y a aucune connexion à YouTube ou Vimeo avant que le visiteur n'agisse. Deux voies :
- Solution en deux clics dans le bloc : d'abord seulement une image d'aperçu avec un bouton de lecture (
buttonavecimg), et c'est le clic qui crée l'<iframe>. Exemplegallery-content/vn-bloecke/src/effekte/videoprivacy/template.html:
<div class="vf-vd" data-v="{{video}}">
<div class="vf-vd-frame">
<button class="vf-vd-poster" type="button" aria-label="Video abspielen">
<img src="{{imgPoster}}" alt="Vorschaubild">
<span class="vf-vd-label">Video abspielen</span>
</button>
</div>
</div>
<script>(function(){document.querySelectorAll(".vf-vd").forEach(function(b){if(b.dataset.vfInit)return;b.dataset.vfInit=1;
var fr=b.querySelector(".vf-vd-frame"),po=b.querySelector(".vf-vd-poster");if(!po)return;
po.addEventListener("click",function(){if(b.closest("#canvas"))return;
var raw=(b.dataset.v||"").trim(),id=raw,m=raw.match(/(?:v=|youtu\.be\/|embed\/|shorts\/|live\/)([A-Za-z0-9_-]{11})/);if(m)id=m[1];
if(!/^[A-Za-z0-9_-]{6,20}$/.test(id))return;
var f=document.createElement("iframe");f.src="https://www.youtube-nocookie.com/embed/"+id+"?autoplay=1&rel=0";f.title="Video";
f.allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen";f.setAttribute("allowfullscreen","");f.setAttribute("referrerpolicy","strict-origin-when-cross-origin");
fr.appendChild(f);b.classList.add("is-playing");po.hidden=true})})})();</script>- Intégration avec blocage : un
<iframe>normal avec une adresse ; quand le consentement est activé, l'export le bloque automatiquement (Blocage automatique).
Données de texte dans des attributs : vnEnc#
Dans le template, un texte issu du panneau ne doit jamais figurer brut dans data-…="{{x}}" : un guillemet ou {{ dans le texte casse le balisage. Utilisez vnEnc(text) et décodez dans le script.
Syntaxe
<div class="mein-block" data-titel="{{vnEnc(titel)}}"></div>var titel = decodeURIComponent(box.getAttribute("data-titel") || "");| Fonction auxiliaire | Valable dans | Signification |
|---|---|---|
vnEnc(wert) | {{…}} et conditions dans le template | encodeURIComponent(String(wert)) ; undefined/null donne '' |
vnEmbed(adresse) | {{…}} dans le template | adresse YouTube/Vimeo → adresse intégrable (youtube-nocookie.com/embed/… ou player.vimeo.com/video/…) ; les autres adresses restent inchangées |
{{vn-id}} | Template (texte, attributs, aussi dans le texte du script) | ID du bloc ou ID d'ancre de l'instance ; ID uniques : id="{{vn-id}}-nav" |
Ces trois éléments sont des aides de l'expression de template, pas des fonctions JavaScript globales : dans le script lui-même, elles n'existent pas (window.vnEnc) (vérifié : typeof window.vnEnc === "undefined"). Les expressions s'exécutent en outre avec accès aux objets standard globaux (String, Number, Math, encodeURIComponent …).
Bibliothèques fournies#
Tout ce qui est externe et dont un bloc a besoin doit être fourni (pas d'appels à des CDN, pas de polices web). Lors de l'export, le programme ne copie que ce que les pages utilisent réellement. Les bibliothèques suivantes se trouvent sous vendor/ ; le choix dépend de traces dans le HTML terminé.
| Bibliothèque | Usage | Export (condition) |
|---|---|---|
| Bootstrap 5.0.1 (CSS + JS Bundle) | Grille, classes utilitaires, dropdown, collapse, tooltip, modal | toujours (bundle : window.bootstrap), sauf en mode thème Bootstrap |
| Bootstrap Icons | Police de symboles bi bi-… | toujours (vendor/bootstrap-icons/) |
| Drapeaux | Drapeaux de pays (SVG, 4:3 et 1:1) | comme fichiers de projet sous assets/, seulement ceux utilisés |
| jQuery 3.5.1 | Seulement pour d'anciens thèmes Bootstrap 4 et leurs plugins | seulement en mode thème (vendor/jquery.min.js) |
| VN Lightbox | Zoom/déplacement d'images | paramètre de la page activé |
| VN Consentement aux cookies | Bannière, blocages, vnCookieConsent | paramètre de la page activé |
| VN Popup | Blocs popup | la page contient un popup |
| VN CMS | Modification sur la page terminée | la page contient un bloc CMS |
| VN Sous-menu | Niveau de menu qui se déploie sur le côté | li.vn-submenu dans le HTML |
| VN Tooltip | Infobulles sur des mots | span.vn-tip dans le HTML |
| VN Vidéo | Fonctions supplémentaires pour vidéos auto-hébergées | video.vn-video-el dans le HTML |
| VN Vidéo d'arrière-plan | Vidéo d'arrière-plan (fichier, YouTube, Vimeo) | data-bg-video avec valeur ou .vn-bgvid |
| VN Traducteur | Traduction en direct | paramètre de la page activé |
| VN WhatsApp | Bouton de contact flottant | paramètre de la page (avec numéro) |
VN Formulaire (vn-sform), Form Renderer | Formulaires, envoi | form.vn-sform-form ou bloc Form Renderer |
| VN Visionneuse PDF (PDF.js 3.11.174) | PDF et tableaux | bloc avec adresse de la visionneuse |
| VN Recherche, VN Blog | Systèmes PHP | blocs correspondants |
| jszip, less, CodeMirror | Uniquement dans l'éditeur | jamais dans l'export |
Les entrées suivantes décrivent les bibliothèques qu'un auteur de bloc utilise ou pilote depuis un bloc. L'intégration est toujours la même : ne rien faire (poser le marqueur), l'export insère lui-même <link>/<script>.
Bootstrap 5.0.1 et Bootstrap Icons#
Le bundle fournit window.bootstrap (Collapse, Dropdown, Tooltip, Modal, Carousel …). Il s'exécute après les scripts de bloc.
document.addEventListener("DOMContentLoaded", function () {
var el = document.querySelector("#mein-id-modal");
if (el && window.bootstrap) new bootstrap.Modal(el).show();
});| Remarque | Description |
|---|---|
| Attributs | Noms de Bootstrap 5 (data-bs-toggle, data-bs-target) ; pour les noms de Bootstrap 4 (data-toggle, data-target, data-dismiss, data-ride, data-slide, data-slide-to, data-parent), l'import ajoute à la lecture les noms de la version 5 (data-bs-…) |
| Éditeur | Le bundle est chargé dans l'éditeur (les menus et dropdowns fonctionnent) ; jQuery ne l'est pas |
| Symboles | <i class="bi bi-NAME"> ; la liste des symboles (2078 symboles) est parcourue dans la boîte de dialogue des symboles |
jQuery et plugins de thème (mode thème Bootstrap)#
Un projet peut tourner sur le Bootstrap d'un thème (par exemple Bootstrap 4.5 ; siteSettings.bootstrapMode = 'theme'). L'export charge alors, à la place de Bootstrap 5, cet ordre : jQuery (vendor/jquery.min.js, 3.5.1), Popper, le JS Bootstrap du thème, le défilement doux, les plugins des blocs utilisés (avec leurs dépendances), enfin le script du thème.
Les plugins qu'un bloc veut figurent sur l'élément racine :
<section class="menu" plugins="DropDown, TouchSwipe"> … </section>| Attribut | Valeur | Signification |
|---|---|---|
plugins | Liste de noms de plugins (virgule, casse indifférente) | Uniquement en mode thème : charge ces dossiers de plugins du thème (plugins/<name>/, seulement .js ; pour les paires, la version .min) |
Les dépendances sont intégrées (masonry a besoin de imagesloaded ; gallery a besoin de imagesloaded et masonry). Un marqueur d'arrière-plan parallaxe dans le balisage déclenche le plugin parallax. Les fichiers de script se trouvent dans le projet sous assets/theme-js/, afin que l'export fonctionne sans le paquet.
VN Lightbox#
Images zoomables et déplaçables sur tout le site. Le bloc ne fait que marquer ce qui doit être zoomé ; détails et attributs : Lightbox.
<img class="vn-zoom" src="assets/images/foto.jpg" alt="Foto" data-vn-caption="Bildunterschrift">VN Consentement aux cookies#
Fenêtre de paramètres, blocages, configuration window.VN_COOKIE_CONFIG, l'interface vnCookieConsent et l'événement vn-cc-consent. Lien pour la rouvrir : <a href="#" data-vn-cookie-settings> (Lien de cookies). Catégories : functional, statistics, marketing ; consentement dans localStorage.
VN Popup#
Fenêtre au-dessus de la page ; déclenchement par lien, durée, défilement, sortie de la page ; interface VNPopup (Popup).
VN CMS#
Modification sur la page terminée (vendor/vn-cms, PHP). Marqueurs et dossier serveur : CMS.
VN Sous-menu#
JS pur, insère lui-même ses règles CSS (<style data-vn-submenu>), pose window.__vnSubmenu. Balisage : Sous-menu. Il est aussi chargé dans l'éditeur (vendor/vn-submenu/vn-submenu.js dans index.html).
VN Tooltip#
Active span.vn-tip[data-bs-toggle="tooltip"] via le tooltip de Bootstrap ; sans Bootstrap 5, l'indication title reste. Balisage : Infobulles.
VN Traducteur#
Bouton de langue pour les visiteurs ; seules les exceptions sont à marquer : Traducteur.
VN WhatsApp#
Bouton de contact flottant, uniquement via le paramètre de la page (window.VN_WHATSAPP_CONFIG : phone, message, side, bottomOffset, sideOffset, bubbleEnabled, bubbleTitle, bubbleText, bubbleDelay). Un bloc n'a rien à y voir ; pour un lien vers WhatsApp, voir Téléphone et WhatsApp.
VN Vidéo, vidéo d'arrière-plan, formulaires, PDF, recherche, blog#
Ces bibliothèques appartiennent à des blocs terminés. Leurs marqueurs et paramètres figurent dans les chapitres Formulaires et Médias.
| Bibliothèque | Usage | Comment un bloc l'utilise |
|---|---|---|
VN Vidéo (vendor/vn-video) | Heure de début/fin, vitesse, chargement différé, VN Player | video.vn-video-el avec des valeurs data-… (Vidéo auto-hébergée) |
VN Vidéo d'arrière-plan (vendor/vn-bgvideo) | Vidéo derrière le contenu | data-bg-video="<adresse>" ou classe vn-bgvid (Arrière-plan vidéo) |
VN Formulaire (vendor/vn-sform) | Vérification et envoi de formulaires statiques | form.vn-sform-form (Formulaires) |
Form Renderer (vendor/vn-formrender) | Formulaire à partir de JSON, règles, envoi PHP | section.vn-formrender avec .vnfr-data (Form Renderer) |
VN Visionneuse PDF (vendor/vn-pdf-viewer) | PDF.js avec recherche | iframe[data-vn-pdf-src] (PDF) |
VN Recherche (vendor/vn-search) | Recherche plein texte (PHP) | section.vn-search (Recherche) |
VN Blog (vendor/vn-blog) | Blog (PHP, SQLite) | Include dans le script PHP protégé (Blog) |
Pièges : le script s'exécute dans l'éditeur et détruit du contenu#
Tous les signalements de problèmes de scripts à ce jour se ramènent à ces catégories :
| Piège | Effet | Remède |
|---|---|---|
Le script réécrit le contenu d'un élément data-vn-text-id | À la frappe, l'état intermédiaire est enregistré ; texte « détruit » | Effets seulement hors du canvas ; garder le texte statique dans le template |
if (closest('#canvas')) return; avant la définition de la valeur initiale | Les modifications du panneau sont invisibles dans l'éditeur | Définir l'état initial, puis terminer |
Le script masque du contenu (opacity:0, display:none, .reveal) et ne l'affiche que via un observateur | Dans l'éditeur, seul l'arrière-plan apparaît | Ne masquer qu'après le test de l'éditeur |
Marqueur d'initialisation data-… | Les nouveaux blocs sont ignorés par les anciens scripts « comme déjà traités » | Propriété JS sur l'élément |
| ID fixes / un état global | Deuxième instance cassée | Classes, {{vn-id}}, espace de noms |
document.currentScript sans repli | null dans l'éditeur | document.querySelector(…) comme repli |
Test sur is-builder | L'éditeur n'est jamais reconnu | closest('#canvas') |
Accès à bootstrap/vnCookieConsent pendant l'analyse | undefined | Attendre DOMContentLoaded |
| jQuery présupposé | absent dans l'éditeur et dans l'export normal | JavaScript pur |
Dispositif de protection window (window.fertig) | réinitialisé à chaque rendu dans l'éditeur, permanent sur la vraie page | Marqueur sur l'élément |
<script type="module"> avec import statique | non exécutable dans l'éditeur (s'exécute dans new Function) | Script classique |
Texte brut dans data-x="{{x}}" | Le balisage casse avec des guillemets ou {{ | vnEnc(x) + decodeURIComponent |
| Adresses externes propres (CDN, polices) | Protection des données, inutilisable hors ligne | Fournir avec le bloc ou omettre |
Accès à location pour rediriger dans l'éditeur | sans effet (volontairement) | utile seulement sur la vraie page |