Documentation développeur VN-Designer
07

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.

LieuLe script s'exécute-t-il ?Comment
Export (publish/), aperçu dans le navigateur et aperçu en directoui, normalementLa 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 codenonSeul le HTML du template y est affiché

Ordre d'une page exportée (d'après buildExportHtml) :

  1. <head> : CSS de Bootstrap, CSS de Bootstrap Icons, les fichiers CSS des bibliothèques d'exécution utilisées, style.css.
  2. <body> : le code HTML de tous les blocs de la page dans l'ordre, chacun avec ses scripts en ligne.
  3. 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

html
<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ègleDescription
EmplacementÀ l'intérieur de l'élément racine, en général comme dernier enfant
TypeSeul un <script> sans src et sans type étranger est exécuté dans l'éditeur (type vide, text/javascript, application/javascript, module)
Types étrangerstype="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
Conditionsvn-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

js
(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 …
  });
})();
MarqueurAdéquationRaison
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-…à éviterLe 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 communesDans 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 ») :

js
(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.

js
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

html
<div class="vn-bgvid-empty" data-vn-editor-only vn-if="!videoFile &amp;&amp; !videoUrl">
  Noch kein Video gewählt — im Eigenschaften-Panel unter „Video“ eine Datei wählen.
</div>
AttributValeurSignification
data-vn-editor-onlyinterrupteurL'é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

js
var inEditor = !!el.closest("#canvas");
if (inEditor) return;        // ou omettre seulement l'effet, mais définir le contenu
Valeur de el.closest("#canvas")Signification
ÉlémentÉditeur (zone de travail)
nullExport, 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 directExport
Scripts de blocisolés, après chaque rendunormalnormal
el.closest("#canvas")Élémentnullnull
window.bootstrapprésentprésent (après les scripts de bloc)présent (après les scripts de bloc)
jQuerynonnon (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'exportoui, si utilisées
Éléments data-vn-editor-onlyvisiblessuppriméssupprimés
PHPne s'exécute pas (leurres)s'exécute via le serveur locals'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 :

MoyenRésultat dans l'éditeurConséquence
document.documentElement.classList.contains("is-builder")falseLe 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")falsecomme ci-dessus (seule la lightbox en tient compte)
document.currentScriptnullL'é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.topfalseIl 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 scriptComportement dans l'éditeur
setTimeout, setInterval, requestAnimationFrameLes 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 windowLe rappel s'exécute immédiatement (avec un décalage, setTimeout 0)
window.onload = fnest exécuté immédiatement comme rappel
document.readyStatetoujours complete
document.write, document.writelnne fait rien
location.assign, .replace, .reload ; location.href = …ne fait rien ; la lecture fonctionne
alert, confirm, promptne font rien (confirm renvoie false, prompt null)
autres appels document/windownormal (liés à l'objet réel)
this, self, globalThis, window.windowle 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ègleJustification
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, clonageSinon 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'ensuitePlacer 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êmesLes 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ègleDescription
SourceLe vrai texte figure dans le template (ou dans un attribut data- comme data-words)
EffetLe script ne découpe ou ne remplace le contenu qu'au chargement de la page
ÉditeurAucun effet, seulement l'état initial (voir Règles)
Sans JavaScriptLe 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

js
var RM = !!(window.matchMedia && matchMedia("(prefers-reduced-motion: reduce)").matches);
if (!RM && "IntersectionObserver" in window) { /* démarrer l'effet d'apparition */ }
css
@media (prefers-reduced-motion: reduce) {
  .mein-block .effekt { animation: none !important; transition: none !important; }
}
BlocComportement 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 Popupse 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

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.

gateThirdPartyEmbeds (export, sur chaque bloc) et gateRawScriptText (insertions HTML globales) reconnaissent :

ContenuReconnaissanceCatégorie
Google Maps (<iframe src>)google.<tld>/maps, maps.google., goo.gl/mapsfunctional
Intégration YouTubeyoutube.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, GoogleAnalyticsObjectstatistics
Pixel Facebookconnect.facebook.net, facebook.com/tr ; en ligne fbq(marketing

Pour tout le reste, marquez vous-même l'élément :

html
<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>
AttributValeursSignification
data-vn-consent-categoryfunctional, statistics, marketingL'élément est bloqué jusqu'à ce que la catégorie soit acceptée ; agit indépendamment du domaine

Ce que l'export en fait

html

<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>
MarqueurSignification
data-vn-cc-srcLe src d'origine ; redevient src après consentement
type="text/plain" + data-vn-cc-categoryScript bloqué ; après consentement, un vrai <script> est inséré, type et data-vn-cc* disparaissent, les autres attributs restent
.vn-cc-gateEnveloppe avec surcouche (« Charger le contenu », « Paramètres ») ; « Charger le contenu » ne débloque que cette seule intégration

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é) :

AppelRetourSignification
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) :

js
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();
  });
}

À 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 :

js
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 :

  1. Solution en deux clics dans le bloc : d'abord seulement une image d'aperçu avec un bouton de lecture (button avec img), et c'est le clic qui crée l'<iframe>. Exemple gallery-content/vn-bloecke/src/effekte/videoprivacy/template.html :
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>
  1. 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

html
<div class="mein-block" data-titel="{{vnEnc(titel)}}"></div>
js
var titel = decodeURIComponent(box.getAttribute("data-titel") || "");
Fonction auxiliaireValable dansSignification
vnEnc(wert){{…}} et conditions dans le templateencodeURIComponent(String(wert)) ; undefined/null donne ''
vnEmbed(adresse){{…}} dans le templateadresse 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èqueUsageExport (condition)
Bootstrap 5.0.1 (CSS + JS Bundle)Grille, classes utilitaires, dropdown, collapse, tooltip, modaltoujours (bundle : window.bootstrap), sauf en mode thème Bootstrap
Bootstrap IconsPolice de symboles bi bi-…toujours (vendor/bootstrap-icons/)
DrapeauxDrapeaux de pays (SVG, 4:3 et 1:1)comme fichiers de projet sous assets/, seulement ceux utilisés
jQuery 3.5.1Seulement pour d'anciens thèmes Bootstrap 4 et leurs pluginsseulement en mode thème (vendor/jquery.min.js)
VN LightboxZoom/déplacement d'imagesparamètre de la page activé
VN Consentement aux cookiesBannière, blocages, vnCookieConsentparamètre de la page activé
VN PopupBlocs popupla page contient un popup
VN CMSModification sur la page terminéela page contient un bloc CMS
VN Sous-menuNiveau de menu qui se déploie sur le côtéli.vn-submenu dans le HTML
VN TooltipInfobulles sur des motsspan.vn-tip dans le HTML
VN VidéoFonctions supplémentaires pour vidéos auto-hébergéesvideo.vn-video-el dans le HTML
VN Vidéo d'arrière-planVidéo d'arrière-plan (fichier, YouTube, Vimeo)data-bg-video avec valeur ou .vn-bgvid
VN TraducteurTraduction en directparamètre de la page activé
VN WhatsAppBouton de contact flottantparamètre de la page (avec numéro)
VN Formulaire (vn-sform), Form RendererFormulaires, envoiform.vn-sform-form ou bloc Form Renderer
VN Visionneuse PDF (PDF.js 3.11.174)PDF et tableauxbloc avec adresse de la visionneuse
VN Recherche, VN BlogSystèmes PHPblocs correspondants
jszip, less, CodeMirrorUniquement dans l'éditeurjamais 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.

js
document.addEventListener("DOMContentLoaded", function () {
  var el = document.querySelector("#mein-id-modal");
  if (el && window.bootstrap) new bootstrap.Modal(el).show();
});
RemarqueDescription
AttributsNoms 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-…)
ÉditeurLe 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 :

html
<section class="menu" plugins="DropDown, TouchSwipe"> … </section>
AttributValeurSignification
pluginsListe 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.

html
<img class="vn-zoom" src="assets/images/foto.jpg" alt="Foto" data-vn-caption="Bildunterschrift">

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èqueUsageComment un bloc l'utilise
VN Vidéo (vendor/vn-video)Heure de début/fin, vitesse, chargement différé, VN Playervideo.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 contenudata-bg-video="<adresse>" ou classe vn-bgvid (Arrière-plan vidéo)
VN Formulaire (vendor/vn-sform)Vérification et envoi de formulaires statiquesform.vn-sform-form (Formulaires)
Form Renderer (vendor/vn-formrender)Formulaire à partir de JSON, règles, envoi PHPsection.vn-formrender avec .vnfr-data (Form Renderer)
VN Visionneuse PDF (vendor/vn-pdf-viewer)PDF.js avec rechercheiframe[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ègeEffetRemè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 initialeLes modifications du panneau sont invisibles dans l'éditeurDéfinir l'état initial, puis terminer
Le script masque du contenu (opacity:0, display:none, .reveal) et ne l'affiche que via un observateurDans l'éditeur, seul l'arrière-plan apparaîtNe 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 globalDeuxième instance casséeClasses, {{vn-id}}, espace de noms
document.currentScript sans replinull dans l'éditeurdocument.querySelector(…) comme repli
Test sur is-builderL'éditeur n'est jamais reconnuclosest('#canvas')
Accès à bootstrap/vnCookieConsent pendant l'analyseundefinedAttendre DOMContentLoaded
jQuery présupposéabsent dans l'éditeur et dans l'export normalJavaScript pur
Dispositif de protection window (window.fertig)réinitialisé à chaque rendu dans l'éditeur, permanent sur la vraie pageMarqueur sur l'élément
<script type="module"> avec import statiquenon 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 ligneFournir avec le bloc ou omettre
Accès à location pour rediriger dans l'éditeursans effet (volontairement)utile seulement sur la vraie page