Un thème est un ensemble de fichiers qui définissent le niveau de présentation. Vous pouvez également créer un ou plusieurs sous-thèmes ou variantes de thème. Seul un fichier .info.yml est obligatoire, mais la plupart des thèmes et sous-thèmes utilisent d'autres fichiers. Cette page énumère les fichiers et dossiers que l’on trouve typiquement dans un thème ou sous-thème.
L'ajout de régions dans un thème nécessite :
- L'ajout des métadonnées de la région dans le fichier THEMENAME.info.yml.
- La modification du fichier page.html.twig et l'affichage des nouvelles régions.
Remarque. Si vous déclarez une ou plusieurs régions dans votre thème, même une seule, toutes les régions par défaut ne seront plus appliquées et vous prenez la responsabilité de déclarer toutes les zones que vous souhaitez utiliser.
Cette documentation est destinée aux thèmes. Pour les informations concernant les modules, voir la section Ajouter des feuilles de style (CSS) et JavaScript (JS) dans un module Drupal 8.
Dans Drupal 8, les feuilles de style (CSS) et JavaScript (JS) sont chargées via le même système pour les modules (code) et les thèmes, appelé : bibliothèques de ressources.
Twig est un moteur de templates pour PHP, qui fait partie du framework Symfony2.
Dans Drupal 8, Twig remplace PHPTemplate comme moteur de templates par défaut. L’un des résultats de ce changement est que toutes les fonctions theme_* et fichiers *.tpl.php basés sur PHPTemplate ont été remplacés par des fichiers templates *.html.twig.
Drupal vous permet de remplacer tous les templates utilisés pour générer le balisage HTML, afin que vous puissiez contrôler entièrement le balisage affiché dans votre thème personnalisé. Il existe des templates pour chaque élément de la page, depuis le HTML de haut niveau jusqu’aux petits champs.
Remplacement des templates
Vous pouvez remplacer les templates principaux de Drupal en ajoutant dans le dossier de votre thème des templates conformément à une convention de nommage spécifique.
Drupal charge les templates selon certaines conventions de nommage. Cela vous permet de surcharger les templates en les ajoutant dans votre thème avec des noms spécifiques.
Après avoir ajouté un template, vous devez vider le cache afin que Drupal détecte votre nouveau template.
Ă€ propos de Twig
Twig est un langage de templates compilé basé sur PHP. Lorsque votre page web est affichée, le moteur Twig prend le template et le transforme en un template PHP « compilé » qui est stocké dans un répertoire protégé à l'adresse sites/default/files/php/twig. La compilation est effectuée une seule fois, les fichiers templates sont mis en cache pour une réutilisation et recompilés lors du vidage du cache Twig.
Lorsqu'on travaille avec un fichier de template Twig, la plupart des variables sont documentées dans les commentaires du fichier template. Cependant, lorsque ce n’est pas le cas, ou lorsque des thèmes ou modules introduisent de nouvelles variables, nous avons besoin d’un moyen pour détecter toutes les variables disponibles dans le cadre du template. Twig fournit la fonction dump() pour détecter et vérifier les variables dans les fichiers de template.
Le moteur de template Twig offre un outil de débogage.
L’implémentation Drupal 8 ajoute également un outil supplémentaire permettant de trouver le template qui génère un rendu.
Avertissement : activer le débogage Twig peut casser certaines parties du site, en particulier Views. Voir ce problème.
Activer le débogage
Vous activez le débogage Twig dans sites/default/services.yml.
Comment fonctionne Twig habituellement
Par défaut, le moteur de thème Twig compile les templates en code PHP et stocke ce code compilé en mémoire. Le code compilé n’est pas adapté au développement car les modifications dans les templates Twig ne sont pas immédiatement reflétées sur votre site Drupal.