Ajouter un script
De nombreuses bibliothèques Jquery sont présentes en natif dans l'architecture de Drupal.
Cependant, leur mise en oeuvre dans mon site n'a pas été intuitive pour plusieurs raisons :
la documentation en français sur la question est très rare ;
la documentation en anglais n'est pas adaptée pour un développeur amateur ;
Ces notes restituent donc les étapes à suivre pour utiliser un script JS dans un site sous Drupal.
NB1 : Pour clarifier ces notes, je suppose dans la suite de ce billet que le thème sur lequel nous travaillons se nomme dh. Les fichiers seront donc stockés dans le répertoire custom/dh.
NB2 : revoir l'organisation des fichiers d'un thème.
0. Les étapes :
adapter le fichier dh.info.yml présent dans themes/custom/dh (ou "dh" est à remplacer par le nom de votre thème) ;
adapter le fichier dh.libraries.yml présent dans ce même répertoire ;
créer votre fichier script.js ;
décocher "agréger les fichiers javascript" de la page /admin/config/development/performance ; enregistrer cette modification ;
vider les caches (depuis cette même page) ;
re-cocher "agréger les fichiers javascript".
1. le fichier dh.info.yml
le fichier dh.info.yml doit comporter dans sa section libraries la ligne - dh/global-scripts où global-scripts est une section du fichier des librairies.
name: dh
type: theme
description: 'mon theme drupal 8 '
package: dh
core: 8.x
libraries:
- dh/global-styling
- dh/global-scripts
base theme: classy
logo: images/dhsite.gif
screenshot: screenshot.png
regions:
header: Header
content: Content
help: Help
breadcrumb: Breadcrumb
page_top: 'Page top'
page_bottom: 'Page bottom'
highlighted: Highlighted
featured: Featured
sidebar_first: 'Left sidebar'
sidebar_second: 'Right sidebar'
footer: Footer
2. le fichier dh.libraries.yml
Ajouter la section global-scripts (cf. dh.info.yml) et ses 2 sous-sections : js et dependencies.
la section js indique le nom et l'emplacement du script. Dans mon exemple :
il se nomme script.js ;
il se trouve dans le dossier "custom/dh/js" ( rappel : dh est le nom du thème) ;
la section "dependencies" liste les bibliothèques utiles à l'exécution de "script.js" ;
dans mon exemple, celles-ci figurent dans le cœur de drupal (dossier "core" du site).
global-styling:
css:
component:
css/style.css: {}
css/dhv3-sf.css: {}
global-scripts:
js:
js/script.js: {}
dependencies:
- core/jquery
- core/jquery.ui
3. le fichier script.js
Dans ce fichier figureront les instructions permettant de styliser nos pages de manière dynamique.
En dehors de Drupal, la bonne pratique pour un script qui utilise des fonctions d'une bibliothèque jQuery est de l'encadrer par :
$(function(){
....
});
Dans l'environnement Drupal (version >8), la bonne pratique est de l'encadrer par :
(function ($) {
Drupal.behaviors.NS = {
attach: function (context, settings) {
......
}
};
})(jQuery);
Ce code attache le script à l'objet "drupal.behaviors" sous le NameSpace NS :
NS : identifiant qui devrait être unique ;
attach : la fonction qui sera exécutée lors du (re)chargement de la page ;
context : le DOM (lorsque la page est chargée pour la première fois, "context" contient l'intégralité du DOM, mais après une requête AJAX, il contient tous les nouveaux éléments chargés) ;
settings : toutes les variables injectées côté serveur.
Pour des plus amples informations sur Drupal.behaviors, cliquez ici.
Dans le script suivant, "dh" est le nom de l'espace de nom (namespace). Il colore en rouge le contenu des balises <h1>et les éléments du DOM de classe .book-navigation puis affiche le texte "et oui, ca marche" dans la console des outils de développement web des navigateurs.
(function ($) {
Drupal.behaviors.dh = {
attach: function (context, settings) {
$('h1').css('color','red');
$('.book-navigation', context).css('color','red');
console.info ('et oui, ca marche...');
}
};
})(jQuery);
Pour ajouter un script aux pages d'un site sous Drupal :
- déclarer la hiérarchie global-scripts dans la hiérarchie racine du thème ( xxxx.info.yml ) ;
- définir cette hiérarchie dans la hiérarchie libraries du thème ( xxx.librarie.yml) ;
- si le script fait appel à une bibliothèque jQuery, alors dans le script définir l'appel à jQuery par (function ($) {
Drupal.behaviors.xxxx = {
attach: function (context, settings) {
......
}
};
})(jQuery);