Ajout de régions dans le 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.

Tous les blocs qui se trouvaient dans des régions qui n'existent plus (parce que vous ne les avez pas définies) seront maintenant désactivés – en particulier si vous modifiez le fichier THEMENAME.info.yml et reconstruisez le cache avec drush cr, vous verrez un message similaire pour chacun :

Le bloc themename_breadcrumbs a été assigné à une région invalide breadcrumb et a été désactivé.

Si vous allez sur /admin/structure/block, tous les blocs désactivés seront listés dans la zone la plus haute avec l’indicateur (désactivé). Vous pouvez soit les faire glisser, soit utiliser le menu déroulant « Région » pour les réaffecter ou supprimer les blocs dont vous n’avez plus besoin.

Assurez-vous de conserver les régions page_top et page_bottom. Ce sont des zones « cachées » utilisées pour le balisage en haut et en bas de la page, telles que l’analytics ou la barre d’administration. Vous n'avez pas besoin de les lister dans le fichier THEMENAME.info.yml, il suffit de ne pas les supprimer du template html.html.twig. Les modules peuvent dépendre de leur présence.

Ajouter des régions dans votre fichier d’information

Commencez par déclarer les nouvelles régions dans le fichier THEMENAME.info.yml. Les régions sont déclarées comme des enfants de la clé regions de la manière suivante :

regions:
  header: 'Header'
  content: 'Content'
  footer: 'Footer'

Les clés des régions doivent être alphanumériques et peuvent contenir un underscore (_). Les clés doivent commencer par une lettre. La clé est le nom machine (utilisé dans le code), et la valeur est une version lisible, affichée dans l’interface d’administration.

Ajouter des régions dans vos templates

Pour que les régions affichent le contenu qui leur est assigné, vous devez vous assurer que vos nouvelles régions sont également ajoutées dans votre fichier page.html.twig. Les régions sont disponibles comme variables Twig, dont le nom correspond à la clé utilisée dans le fichier THEMENAME.info.yml, précédée de la chaîne page.

Exemple :

header: 'Header' 

...devient :

{{ page.header }} 

Elles se comportent comme n’importe quelle autre variable Twig et peuvent être enveloppées dans n’importe quel balisage adapté à votre cas d’usage.

(La syntaxe des zones cachées par défaut est différente, voir ci-dessous.)

Régions par défaut

Voir la documentation de page.html.twig pour la liste des régions par défaut.

• page.header
• page.primary_menu
• page.secondary_menu
• page.highlighted
• page.help (texte d’aide dynamique, principalement pour les pages d’administration)
• page.content (contenu principal de la page courante)
• page.sidebar_first
• page.sidebar_second
• page.footer
• page.breadcrumb

Si votre thème ne déclare pas de régions, Drupal utilisera cet ensemble de valeurs par défaut.

Ces zones correspondent à ce que le fichier par défaut core/modules/system/templates/page.html.twig attend, ainsi qu’aux deux zones cachées page_top et page_bottom – vous n’avez pas besoin de déclarer ces deux dernières si vous surchargez les valeurs par défaut, cependant les variables Twig {{ page_top }} et {{ page_bottom }} doivent être conservées dans le template html.html.twig.