Token et les entités chainées sur Drupal 8

Le module token est un de ces modules de base, indispensable, sur tout projet Drupal 8. Il permet d'utiliser des jetons dans certains champs de saisie, que ce soit de la configuration ou du contenu, permettant de cibler la valeur d'un champ d'une entité ou d'un contenu. De nombreux modules l'utilisent pour permettre aux utilisateurs ou aux concepteurs de fournir une valeur dynamique sans avoir besoin de coder.

Regardons comment accéder aux valeurs d'un contenu depuis ces jetons, mais aussi aux valeurs indirectement associés à ces contenus, depuis des champs Entity reference.

Accéder aux champs directement attachés à une entité

Récupérer la valeur d'une entité se fait simplement. Par exemple pour récupérer le titre d'un contenu, nous utiliserons le jeton [node:title]. De même pour récupérer la valeur d'un champ particulier du contenu (donc un noeud dans la terminologie Drupal), par exemple field_name, nous pouvons utiliser [node:field_name]. En règle générale, quand vous avez la possibilité d'utiliser des jetons, vous disposez de la liste des jetons disponibles dans le contexte où vous vous trouvez (un noeud, un utilisateur, etc.).

Et vous avez tout loisir de parcourir la liste des jetons possibles et sélectionner ceux qui correspondent à votre besoin.

Jusqu'ici, tout va bien ! 

Accéder aux champs des entités référencés par une entité

Mais, on peut également avoir besoin d'accéder, toujours au moyen des jetons, à des valeurs de champs qui ne sont plus rattachés directement à l'entité qui nous sert de contexte de référence, mais qui sont rattachés à une autre entité référencée par notre contenu, voire pourquoi pas, à une entité qui est référencé par une autre entité elle-même référencé par notre contenu.

Vous suivez toujours ?

Par exemple, nous pouvons avoir un contenu (un noeud), qui référence un autre contenu, ce dernier contenu référençant un terme de taxonomie, et nous souhaitons récupérer le nom de ce terme de taxonomie.

Ou encore une autre exemple (réel) plus profond : un contenu qui référence un autre contenu, ce dernier contenu référence des paragraphes (entité paragraph), paragraphes auxquels est attaché une image (le paragraphe référence donc une entité File qui stocke l'image). Et nous souhaitons accéder à la valeur de l'url de cette image, depuis le contenu initial, et ce au moyen d'un simple token.

La version Drupal 8 de token nous permet d'arriver à nos fins en utilisant des jetons chainés les uns aux autres (auparavant, sur Drupal 7, nous avions besoin du module entity_token pour parvenir aux mêmes résultats). Mais parfois ces jetons enchainés ne sont pas tous présents dans la liste des jetons disponibles, surtout quand on arrive à 3 niveaux de profondeur ou plus. En même temps, les possibilités pour présenter des jetons enchainés jusqu'à trois (ou plus) niveaux de profondeur deviennent tellement nombreuses, que cette liste en deviendrait trop longue, perturbant la sélection des jetons principaux.

J'avoue avoir cherché un temps certain la syntaxe à utiliser. Mais après quelques lectures, et déductions, bingo, son évidence saute aux yeux. Je pose donc ici le résultat.

La clé est ici d'utiliser un jeton spécial, entity, qui va nous permettre d'enchainer les entités référencées les unes aux autres depuis notre jeton et de les parcourir comme pour une petite ballade dominicale. Et parce qu'un dessin vaut mieux souvent qu'un long discours, prenons quelques exemples.

• Nous avons un contenu (A) qui référence un autre contenu (B) avec un champ Entity Reference field_ref_content, et le contenu B contient une image, image référencée depuis le champ field_image.  Si nous souhaitons disposer de l'url de cette image depuis le contenu A, il nous suffit d'utiliser le token suivant : [node:field_ref_content:entity:field_image:entity:url]
• Nous avons un contenu (A) qui référence (field_ref_content) un autre contenu (B), ce dernier contenu référence un paragraphe (field_paragraph), paragraphe auquel est attaché une image (le paragraphe référence donc l'image depuis le champ field_image). Et nous souhaitons accéder à la valeur de l'url de cette image, depuis le contenu A. Notre token à utiliser est alors : [node:field_ref_content:entity:field_paragraph:entity:field_image:entity:url].
• Dans le cas de champs multiples il faut bien sûr cibler quelle entité à laquelle on souhaite accéder en utilisant son delta (ou son index). Par exemple un contenu (A) qui référence des paragraphes (champ multiple field_paragraphs), paragraphes qui disposent d'une image. Pour accéder à l'url de cette image pour le premier paragraphe (delta 0) nous allons alors utiliser le token : [node:field_paragraphs:0:entity:field_image:entity:url]

Au final, c'est plutôt simple, nul besoin ici d'un expert Drupal 8. Pour accéder aux valeurs d'une entité référencée, il suffit donc d'utiliser le jeton entity et de l'associer au champ Entity Reference concerné, et nous accédons alors à l'intégralité de cette entité et donc de ses champs, et ceci de façon recursive, à l'infini si besoin.