Template Whisperer — Content-first templating in Drupal 8

7 min readSep 22, 2018

We recently released update 2.0 of Template Whisperer, so it is more than time to talk about it.
This module radically changed our development process in our Drupal 8 projects. Thanks to Template Whisperer, we could dramatically improve the quality of our work while gaining flexibility and improving development speed.

You might not think that programmers are artists, but programming is an extremely creative profession. It’s logic-based creativity.”
- John Romero, Co-founder of id Software

The idea behind Template Whisperer is to let editors take the lead on content for special pages.

Before we dive into the subject, let me clear out the special pages term. Here are some pretty nice illustrations of what it can stand for:

The well known content listing (with a pagination or infinite scroll);
The famous Agenda page with filters;
The crucial page with a 4 steps form;
The landing page of the key product;
The board members listing page;
The donation form page;
…

In other words, you surely understand that those page should be simple Node entities but became an unhealthy mix of Views/Panel or Hooks/Block layout containing the node ID with its own logic (e.g. from the URL).

A user interface should be so simple that a beginner in an emergency can understand it within ten seconds.”
- Ted Nelson, creator of Hypertext

Thanks to Template Whisperer, the content creators don’t need to access Views, Panel, Display Suit, Layout, Block Layout ou any other monolithic module that is so hard to grasp for basic editing.
And it’s easier for developers too! They don’t need to create specific Controllers, spaghetti hooks or hardcode content ID in the only purpose of managing special cases.

In short, with this module developers are less solicitated for tasks that can now be done by content editors by using the node edit form.
That way, editors can enjoy more creative flexibility and can control the website better while administration interfaces can remain simple and easy-to-use — unlike Panel, Layout or Views.

You can now change the URL of the page “Our projects” without breaking the breadcrumbs;
You can now change the title of the page “Contact us”;
You can now translate the URL of your “Our summer events” page;
You can now greatly improve the SEO of all special pages (the metatags module can be used!)
You can forget inconsistant URL schemas between the “News” page and the news article itself.

Thanks to Template Whisperer, the content editor edits the site using only entity formsthat hold the whole power of Drupal (URL, translation, fields, Metatags, Pathauto, publish status, Workflow, etc) to which they can now apply Suggestions.
Developers can then use those newly generated template suggestions and add blocks, forms, or simply a different HTML layout and look by editing the template. You can even link to those pages!

Everything is done naturally by using the goodness of Drupal 8 engine. Say goodbye to all those bad practices and to all the bad hooks habits. Embrace the Template Whisperer revolution!
Your clients will get a feeling of being able to modify more things while you can keep everything under control because they only edit the entities themselves. Nothing is hardcoded anymore!

“Template Whisperer is 100% happiness, 20% fun and 0% headache.”
- Toni, a nice and math enthusiast developer

And I haven’t said everything! Once coupled with Pathauto, it is then possible to automatically generate clean URL aliases for better SEO!

Which developers was never wondering how to setup the “Article” content type so that it automatically uses the URL prefix that is set for the “News” page without having to code an exception? Well, with Template Whisperer you can use a specific Token and it works out-of-the-box! With the help of Pathauto, everything is configurable and easy to manage.

Template Whisperer is the bomb.”
- Vincent, a clever developer

Plugging: we use Template Whisperer with the additional help of Bamboo Twig on a daily basis. Together, they provide you with a powerful cocktail of genius flexibility to build incredibly well accomplished projects while keeping them maintainable and scalable and reducing the need to click in the interface. Code first!
If you don’t know Bamboo Twig yet, go and read the article(fr).

Yeah… not convinced”
- Gilles, a not so clever developer

How does it work?

Template Whisperer is the logical follow-up to the Core initiative of theme suggestions in Drupal 8.
With this module, by applying a suggestion to a page, we extend the initial theme suggestions to be able to cover specific templating needs.

By default, Drupal exposes 6 theme suggestions on an entity:

* node--2--full.html.twig
* node--2.html.twig
* node--page--full.html.twig
* node--page.html.twig
* node--full.html.twig
* node.html.twig

Template Whisperer is going to plug itself on this system to add its own suggestions, increasing the total of possibilities to 10.

Here is an example where we apply the suggestion “News collection” to the Basic Page node titled “Our news”:

 * node--2--page--full--news-collection.html.twig
 * node--page--full--news-collection.html.twig
 * node--2--page--news-collection.html.twig
 * node--page--news-collection.html.twig
 * node--2--full.html.twig
 * node--2.html.twig
 * node--page--full.html.twig
 * node--page.html.twig
 * node--full.html.twig
 * node.html.twig

Use case

Let’s see how the module works with a simple use case.

Create a suggestion

Go to www.example.com/admin/structure/template-whisperer

Create a template suggestion by clicking “Add suggestion”.

2. Attach a new “Template Whisperer” field to an entity

Inspired by the process of Metatag module, you can add a new Template Whisperer field to your entity.

Go to the page Manage fields of the content type you want to add your suggestion to;

Select the field type “Template Whisperer”;

Set a shiny new and unpredictable name for it, like “Template Whisperer”.

3. Create an entity and set a suggestion

Go on the Content listing and create a new entity;
You should be able to see a new section in the Advanced tabs section to the right;

Select the suggestion you created in the previous step and save your content.

4. Create a new Twig file based on your new suggestion

You only have to add your specific HTML, custom block or form to a newly created template.

Snippets

The examples below are coupled with Pathauto and Bamboo Twig in order to boost Template Whisperer capabilities.

Inject a “News collection” block in my “News” page with Twig

Thanks to Bamboo Twig, you are able to call a custom block directly from the newly created template.

{% extends "@theme/content/node.html.twig" %}{% block node_content_below %}
  <section>
    <div class="container">
      {{ bamboo_render_block('mymodule_news_collection_block') }}
    </div>
  </section>
{% endblock %}

Add an exception to a block from the Block Layout based on the suggestion

Sometimes you don’t want to modify Twig templates to hide or display a block. You can use the default Block Layout then.

Template Whisperer exposes a block visibility condition — that is, most surprisingly, called “Template Whisperer” — that allows you to configure a block visibility based on a Template Whisperer suggestion that is attached to a node or content.

Go to the Block Layout admin page www.example.com/admin/structure/block;
Click on “Configure” for the block you want to edit.

Automatically generate the URL for “Projects” pages based on the “parent” page with the suggestion “Our projects”

Token can be used with Pathauto to generate pages URL based on other pages Template Whisperer suggestions.

For example, you have a “Projects” page with the suggestion “projects_collection”. What you want to achieve with your “Project” content type is the following:

Our projects — “Basic page” node -> /projects
Project — “Project” node -> /projects/my-project

With the Token integration, you can define a new Pathauto pattern using the suggestion-lookup token.

/[suggestion:lookup:projects_collection:entity:url:path]/[node:title]

Create a link to a page using a Suggestion

Twig Template Whisperer exposes a Twig function tw_suggestion_entities. This function can be used to get all the entities attached to a specific suggestion.

Example: You have a “Our projects” page with a projects_collection suggestion. You want to add a link "View all our projects" in the "Last projects" page:

{% set suggestions = tw_suggestion_entities('projects_collection') %}
{% if suggestions %}
  <a href="{{ path('entity.node.canonical', {'node': suggestions|first.id}) }}">see all my projects</a>
{% endif %}

PHP

Sometimes, the previous Twig function is not necessaiy. You just need to get all the linked entities of a Template Whisperer suggestion. To achieve that, use the services \Drupal\template_whisperer\TemplateWhispererManager & \Drupal\template_whisperer\TemplateWhispererSuggestionUsage.

$twManager = \Drupal::service('plugin.manager.template_whisperer');
$twSuggestionUsage = \Drupal::service('template_whisperer.suggestion.usage');

// Get entities from suggestion, if exists.
$suggestion = $twManager->getOneBySuggestion('projects_collection');
if(suggestion) {
  $entities = $twSuggestionUsage->listUsage($suggestion);
}

Sources

The official documentation.

For the most curious, here are a couple of additional info that inspired this module and article.

Kevin Wenger (Juin, 2018). Bamboo Twig, Beyond Twig. Retrieved from https://antistatique.net

Kevin Wenger & member of the Drupal Documenation Working Group (July, 2018). Official Documentation — Template Whisperer. Retrieved from https://www.drupal.org

Kevin Wenger & member of the Drupal Documenation Working Group (Juin, 2017). Official Documentation — Bamboo Twig. Retrieved from https://www.drupal.org