Aller au contenu principal


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.

Billet créé le :
17 nov 2020

0. Les étapes :

  1. adapter le fichier dh.info.yml présent dans themes/custom/dh (ou "dh" est à remplacer par le nom de votre thème) ;

  2. adapter le fichier dh.libraries.yml présent dans ce même répertoire ;

  3. créer votre fichier script.js ;

  4. décocher "agréger les fichiers javascript" de la page /admin/config/development/performance ; enregistrer cette modification ;

  5. vider les caches (depuis cette même page) ;

  6. 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);