Les thèmes avec Twig

Pinceaux alignés plein de peinture de différentes couleurs
03 septembre 2017

Qu'est ce qu'un thème ?

Description des différents types de thèmes

Dans Drupal il y a deux notions de thèmes. Comme je n’ai pas trouvé de dénomination officielle je me permets dans cet article, de leur en donner une afin de les différencier.
Il y a tout d'abord les thèmes "Généraux"*, cette fonctionnalité gère toute la partie template/graphisme du site.
Bartik, adminimal sont des thèmes généraux. Ils ont un fichier .info ainsi que des templates Twig, des librairies, un fichier montheme.theme...
Ils sont situés dans le dossier "themes" à la racine de Drupal. Pour ces thèmes, il y aura un prochain article.
Les thèmes concernés par cet article sont les thèmes dit "locaux"*. Par exemples, "item_list", "container", “links”, “image”... sont des thèmes "locaux"*.

Où les utiliser ?

Ces thèmes permettent la mise en forme d’une donnée ou d’un groupe de données. Ils peuvent être utilisés un peu partout. Les cas les plus courant sont dans les formateurs de champs, les blocs personnalisés, les preprocess de noeud...
Les thèmes "locaux" sont utilisés lorsqu'il faut structurer via du HTML, XML ou autre, le rendu d'une donnée.

Pourquoi ?

Plusieurs raisons me poussent à utiliser les thèmes “locaux”*. Le fait qu'ils soient réutilisables et extensibles sont des raisons majeures.
Le coeur de Drupal fournit pas mal de thèmes “locaux”* ce qui permet de ne pas à avoir à gérer une multitude de sortie simple comme le rendu des images, des liens… Ou plus complexes comme les listes imbriquées, les tableaux plus ou moins complexes…
Ils peuvent aussi être surchargés d’un thème “global”* à un autre. (Voir chapitre ci-dessous.)
L'utilisation, la maintenabilité et leur caractère MVC font que les thèmes "locaux"* sont utilisés par la communauté.

 

Twig

 

Description de Twig

Twig est un moteur de templates pour le langage de programmation PHP. Il permet d'écrire la réponse textuelle lors d'une requête. Il est généralement utilisé pour écrire du HTML mais on peut aussi l'utiliser pour construire une réponse XML.
Ce moteur de template possède toute une série de fonctions et de briques logiques. Il est d'aileurs possible de créer ses propres fonctions.
Sa syntaxe est lisible et son ajout dans Drupal 8 fait qu'on ne verra plus de code métier (du PHP) se balader dans les templates. Et ça, c'est pas trop tôt !
Je ne vais pas décrire plus en profondeur les fonctionnalités de twig dans cet article. Si vous voulez en savoir plus, des liens sont présents en bas de page.

Les références de Twig

Le moteur de template Twig est présent dans plusieurs outils majeurs d'internet.
En plus d'être le moteur de template de Symfony, il est aussi présent dans Magento 2, Drupal 8 et sûrement dans d'autes framework / CMS.
Il est de plus en plus apprécié pour ces performances et sa relative simplicité d'utilisation.

Ses avantages par rapport à PHPTemplate

Twig apporte une bouffée d'air frais aux développeurs/thèmeurs Drupal. On peut (re) cité le fait qu'il est facile de lire du Twig alors que pour PHPTemplate il fallait quand même s'accrocher dans certains cas.
Il respecte le principe MVC, alors que l'on pouvait trouver 100 lignes de codes PHP pour 3 lignes de rendus dans PHPTemplate.
Il aurait aussi, mais je ne l'ai pas vérifié personnellement, de meilleurs performances que son prédécésseur.

Comment utiliser les thèmes ?

Le hook_theme() et hook_theme_registry_alter()

Commençons par le hook_theme() qui est le hook principal concerné par cet article. Grâce à ce hook il est possible de déclarer de nouveaux thèmes.
Le retour de cette fonction est un tableau où chaque entrée est un thème.
Je ne vais pas détailler tous les paramètres car vous retrouverez la documentation officielle ici.
Les principaux paramètres sont les suivants :

  • Variables
    La clé #variables permet de définir les variables à passer au thème lors de son appel. Si cette entrée est vide, toutes les variables passées au render array ne seront reprise ni dans le preprocess ni dans le template.

  • Template
    Cette clé permet de définir le nom du template twig qui sera appelé lors du rendu. L’extension ainsi que sa localisation par défaut sont implicites, vous n’aurez qu’à renseigner le nom du fichier et à le placer dans le dossier ‘templates’ à la racine du module.

Exemple de hook_theme

                    
function hook_theme($existing, $type, $theme, $path) {
    return [
        'instagram_media' => [
            'variables' => [
                'type_media' => NULL,
                'url_media' => NULL,
                'title_media' => NULL,
                'url_link' => NULL,
                'description' => NULL
            ],
        ],
    ];
}
                    
                

D’après la documentation, il est possible de modifier la déclaration d’un thème existant depuis ce même hook grâce au paramètre $existing.
Pour ma part, je préfère appeler le hook ci-dessous afin de bien séparer la déclaration et l’altération de thème.
Il est temps de parler du hook_theme_registry_alter() .
Ce hook permet de modifier la déclaration d’un thème existant, afin d'ajouter des variables, de modifier la localisation du template etc.
Il est possible de faire pas mal de choses avec cette surcharge de thème, vous pouvez même ordonnancer l’appel de preprocess afin de définir un ordre pour X ou Y raison.
Cette modification couplée à une surcharge de template permet de personnaliser un thème existant sans passer par la case "Création d'un nouveau thème qui fait exactement la même chose à un détail prêt".

Appel de rendu d'un thème

Pour afficher un thème il faut se tourner vers les render array. L'utilisation est assez simple et lisible. La puissance des render array est leurs imbrications les uns dans les autres ainsi qu’une utilisation simplifiée des caches grâce à la clé #cache. Mais ceci viendra dans un autre article.
Voici un exemple d’un render array :

                    
$output['render_theme'] = [
    '#theme' => 'nom_de_mon_theme',
    '#variables1' => 'Valeur',
    '#variables2' => 158
    ];
}
                    
                

 

La clé requise est la clé #theme, elle permet d’indiquer qu’on veut afficher un thème en lui passant le nom de celui-ci.
Par la suite, il est possible de passer toutes les variables définies dans le hook_theme() en précédant chaque nom par un #.
Bien entendu le rendu de thème, hérite de toute la panoplie de fonctionnalités des render array. Comme de définir un max age ou un context aux caches (avec la clé #cache). Il est possible d’utiliser les clés #prefix ou #suffix , même si il est préférable de ne pas les utiliser et de bien séparer le code PHP du HTML/Twig.

 

La surcharge de thème

Ça c’est le truc chouette !
Les templates des thèmes du coeur, des modules contrib ou vos propre thèmes peuvent être surchargés. Il faut juste copier coller le template d’origine dans votre thème “global”* et vous pouvez réécrire tout le HTML. Vous aurez en votre possession toutes les variables du thème pour écrire votre propre architecture HTML.
Vous pouvez aussi intervenir au niveau PHP sur les variables juste avant le rendu du thème grâce au hook_preprocess() .
Si, sur un thème existant, vous devez passer des variables au preprocess vous pouvez altérer la déclaration des thèmes grâce au hook_theme_registry_alter() .

Autres articles en français

Article sur l'utilisation de Twig dans Drupal 8 , par HappyCulture
Article sur l'utilisation du render array , par HappyCulture
Une présentation vidéo de Twig , par Flocon de Toile au DrupalCamp 2016.
Article sur l'utilisation de Twig , par Flocon de Toile

Documentation des thèmes et de twig officiel

Documentation Drupal
Documentation Twig


Retour