Why my template suggestions don't work?

Sometimes I found that when I created a suggestion for a Drupal field, it didn't work, I tried some things and cleared the cache several times, but nothing, until I found the answer in the Drupal documentation.

Let's talk a bit about what these things are.

What are template suggestions?

"Template suggestions" are a way to personalize the appearance of content elements. By default, Drupal provides several that you can use, following a pattern you can find at https://www.drupal.org/node/2354645.

You can create different versions of a template in Drupal so that they apply according to certain criteria, for example, you could make one for nodes that only applies when a specific field has a certain value.

How are template suggestions created?

To create "template suggestions", you need to know the system of nomenclature used by Drupal. Typically, it's something like node--type.tpl.php, where type represents the name of the content type and node indicates the entity type.

Using the theme_suggestions_HOOK_alter hook, you can define new templates that allow you to personalize the presentation of your site, the following is an example with the entity type node:

function MYMODULE_theme_suggestions_node_alter(array && $suggestions, array $variables) {
  if (\Drupal::currentUser()->isAuthenticated()) {
    $suggestions[] = 'node__logged_in';
  }
}

The code above works as follows:

• the first part hook represents the name of the module or theme from which the implementation is made.
• the following HOOK that is in uppercase refers normally to the type of entity that will be rendered, it can be node, user, form_element, etc.
• all elements added to the array $suggestions will be the template suggestions that can be added to your theme to personalize the presentation under certain conditions, in this case, one that indicates that the user is authenticated, but you could create more complex conditions, since $variables also comes with the entity with all its data.

How to discover which templates are available?

As I explained, Drupal already offers many templates that you can use, to discover them, you just need to add the following lines to the file sites/development.services.yml, and then clear the cache.

parameters:
  twig.config:
    debug: true

Also make sure that the following lines are not commented out in the file sites/default/settings.php

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
  include $app_root . '/' . $site_path . '/settings.local.php';
}

Once you've done that, when you go to any page of the site and inspect its source code, you'll be able to see some comments indicating which templates are available.

And now, why does Drupal not recognize my templates?

In PHP, template suggestions are defined with underscores _, but when creating the files, you must replace them with hyphens -, here are some examples:

• node__logged_in -> node--logged-in.html.tpl
• field__user_badges -> field--user-badges.html.tpl
• page__user__view -> page--user--view.html.tpl

I hope this clarification saves you some headaches.