Token and chained entities on Drupal 8

The token module is one of these essential modules on any Drupal 8 project. It allows you to use tokens in certain input fields, whether configuration or content, to target the value of one entity field. Many modules use it to allow users or site builder to provide dynamic value without the need for coding.

Let's see how to access the content's values from these tokens, but also to the values ​​indirectly associated with these contents, from Entity reference fields.

Access fields directly attached to an entity

Recovering the value of a content's field is done simply. For example, to retrieve the title of a content, we will use the token [node:title]. Similarly to retrieve the value of a particular field of content (so a node in Drupal terminology), eg field_name, we can use [node:field_name]. Generally, when you have the ability to use tokens, you have a list of tokens available in the context you are in (a node, a user, etc.).

And you have all the time to browse the list of available tokens and select those that correspond to your need.

So far, so good !

Access to fields of entities referenced by an entity

But we may also need to access, always with tokens, to field values ​​that are no longer attached directly to the entity that is the reference context, but which are attached to another entity referenced by our content, or even why not, to an entity that is referenced by another entity itself referenced by our content.

Are you still following?

For example, we may have content (a node), which reference an another content, the latter content referencing a taxonomy term, and we wish to retrieve the name of that taxonomy term.

Or another (deeper) example: a content that references another content, the latter content references some paragraphs (paragraph entity), paragraphs to which an image is attached (the paragraph therefore references a File entity that stores the image) . And we want to retrieve the image's url, from the initial content, and this always with a simple token.

The Drupal 8 token module allows us to achieve our ends by using tokens chained to each other (previously, on Drupal 7, we needed the entity_token module to achieve the same results, module included with the entity module). But sometimes these chained tokens are not all present in the list of tokens available, especially when one reaches 3 levels of depth or more. At the same time, the possibilities of presenting chained tokens up to three (or more) levels of depth become so numerous, that this list would become too long, disrupting the selection of the main tokens.

I confess to having looked for a certain time the syntax to use. But after a few readings, and deductions, bingo, its obviousness is obvious (oups!). I therefore share the result here.

The key here is to use a special token, entity, which will allow us to chain the entities referenced one to the other from our token and to traverse them as for a small Sunday ballad. And because a drawing is better than a long speech, let us take a few examples.

• We have a content (A) that references another content (B) with an Entity Reference field field_ref_content, and the content B contains an image, image referenced from field field_image. If we want to have the url of this image from the A content, we just need to use the following token: [node:field_ref_content:entity:field_image:entity:url]
• We have a content (A) that references (field_ref_content) another content (B), the latter content references a paragraph (field_paragraph), paragraph to which an image is attached (the paragraph therefore references the image from field field_image). And we want to retrieve the image's url, from the content A. Our token to be used is then: [node:field_ref_content:entity:field_paragraph:entity:field_image:entity:url].
• In the case of multiple fields it is of course necessary to target which entity to be accessed using its delta (or its index). For example, a content (A) that references paragraphs (multiple field field_paragraphs), paragraphs that have an image. To access the url of this image for the first paragraph (delta 0) we will then use the token: [node:field_paragraphs:0:entity:field_image:entity:url]

Finally, it is rather simple, no need here of a Drupal 8 expert. To access the values ​​of a referenced entity, it is therefore enough to use the token entity and to associate it with the Entity Reference field used, and then we access the entirety of this entity and therefore its fields, and this in a recursive way, to infinity if needed.