Quand on intègre un projet sur Drupal, on a le choix entre utiliser un thème existant ou en créer un de toutes pièces. Dans la plupart des projets en agence, le thème existe déjà et n'a pas besoin d'être recréé. Nous verrons dans cet article comment créer un thème custom lorsque vous n'avez pas de thème existant.
Pourquoi créer un thème custom plutôt qu'utiliser un thème existant ?
Drupal propose des thèmes contrib prêts à l'emploi comme Olivero (le thème par défaut) ou Bootstrap. Ils peuvent être utiles pour des prototypes ou des projets sans charte graphique contraignante, mais ils ont leurs limites.
En agence, on travaille à partir de maquettes précises, souvent réalisées sur Figma ou Adobe XD. Adapter un thème existant à une charte sur-mesure revient souvent à passer plus de temps à défaire ce qui a déjà été fait qu'à recréer le thème. Partir d'un thème vierge donne un contrôle total sur le rendu, le HTML généré et les performances.
C'est aussi ce qui distingue le travail d'un développeur front Drupal expérimenté : savoir construire une base propre, sans dette technique dès le départ.
La structure minimale d'un thème Drupal
Un thème Drupal custom repose sur deux fichiers indispensables, placés dans un dossier dédié sous /themes/custom/nom_du_theme/. Attention, il est très important de placer votre dossier de thème dans le dossier custom, sinon Drupal ne vous proposera pas d'activer votre thème, car il en le détectera pas.
Le fichier .info.yml, c'est la carte d'identité du thème, sans lui, Drupal ne le reconnaîtra pas non plus. Ce fichier pourra contenir la liste de vos régions HTML, vos librairies, vos dépendences, etc. Voici les informations basiques à renseigner dans mon_theme.info.yml :
name: Mon Thème
type: theme
description: 'Thème custom du projet'
core_version_requirement: ^10 || ^11
base theme: false
libraries:
- mon_theme/global
Le fichier .libraries.yml, il déclare les fichiers CSS et JS que Drupal doit charger, ses informations sont récupérées dans le .info.yml, dans la partie libraries. Drupal ne charge rien automatiquement : tout doit être déclaré dans mon_theme.libraries.yml :
global:
css:
theme:
css/style.css: {}
js:
js/main.js: {}
dependencies:
- core/drupal
Si vos styles ou scripts ne s'affichent pas, pensez à vider le cache Drupal après chaque modification de ces fichiers. Drupal met en cache les déclarations de librairies.
L'arborescence de base ressemble à ceci :
mon_theme/
├── mon_theme.info.yml
├── mon_theme.libraries.yml
├── css/
│ └── style.css
├── js/
│ └── main.js
└── templates/
Intégrer ses premiers templates Twig
Une fois le thème activé, on peut commencer à surcharger les templates Twig de Drupal. Tous les templates de base se trouvent dans le cœur de Drupal, l'idée est de les copier dans le dossier templates/ de son thème et de les modifier.
Si vous n'êtes pas encore à l'aise avec Twig, je vous recommande de lire mon article dédié à Twig sur Drupal avant de continuer.
Les premiers templates qu'on surcharge généralement :
- page.html.twig : structure globale de la page
- node.html.twig : rendu d'un contenu
- block.html.twig : rendu d'un bloc
- html.html.twig : structure HTML de base, balise <html> et < <head>
Pour cibler un type de contenu précis, Drupal utilise un système de suggestions. Par exemple, node--article.html.twig s'appliquera uniquement aux contenus de type "article". Drupal cherche d'abord le template le plus spécifique, et remonte progressivement vers le plus générique. Pour être le plus précis possible, lorsque vous êtes sûr que votre page ne sera utiliser qu'une seule fois, vous pouvez directement placer l'ID de votre node dans le nom du fichier.
Pour savoir quel template Drupal cherche à charger sur une page donnée, activez le mode debug Twig dans votre fichier services.yml :
parameters:
twig.config:
debug: true
Une fois activé, Drupal affiche dans le code source HTML de votre navigateur des commentaires qui indiquent exactement quels templates sont utilisés et quelles suggestions sont disponibles. C'est l'outil le plus utile au quotidien pour un développeur front Drupal.
Gérer ses styles : SCSS et librairies Drupal
Drupal ne compile pas le SCSS nativement, il faudra passer par un outil externe comme npm avec un watcher SCSS, ou un task runner comme Gulp. Visual Studio Code, un IDE que j'utilise, possède des modules permettant de faire cette compilation. Le fichier compilé est ensuite déclaré dans .libraries.yml.
Une structure SCSS courante sur un thème Drupal :
scss/
├── base/
│ ├── _variables.scss
│ └── _reset.scss
├── components/
│ ├── _header.scss
│ └── _card.scss
├── layout/
│ └── _grid.scss
└── style.scss
Le fichier style.scss importe tout le reste. Le fichier compilé style.css est celui déclaré dans .libraries.yml.
Deux erreurs classiques à éviter :
- Oublier de vider le cache Drupal après avoir modifié .libraries.yml, les changements ne s'appliquent pas sans ça.
- Déclarer plusieurs librairies sans les attacher aux bons templates, une librairie déclarée dans .info.yml sous libraries est chargée globalement sur tout le site, ce qui peut alourdir les pages inutilement.
Pour n'attacher une librairie qu'à un template spécifique, utilisez {{ attach_library('mon_theme/ma_librairie') }} directement dans le fichier .html.twig concerné.
