New |add_suggestion Twig Filter Added to Drupal 10!

Drupal 10’s front-end continues to make great strides! This time, we’ve added a new Twig filter called add_suggestion. View the change record at https://www.drupal.org/node/3301862, and the issue at https://www.drupal.org/i/3301373

What does the new Twig filter do?

The new |add_suggestion filter will create a new template suggestion based on the value passed in. This new suggestion will have the highest priority.

This enables things like

{{ content.field_items|add_suggestion(‘details’) }}

Which would render in the following field--details.html.twig (assuming that that template file exists):

{# field--details.html.twig #}
{%
  set classes = [
    'details-item',
    'details-item-' ~ field_name|clean_class,
  ]
%}
<details{{ attributes.addClass(classes) }}>
  <summary{{ title_attributes }}>{{ label }}</summary>
  <div class="details-item__content">
    {% for item in items %}
      <div{{ item.attributes.addClass('details-item__content-item') }}>{{ item.content }}</div>
    {% endfor %}
  </div>
</details>

This field--details.html.twig can be shared across any field that uses the new |add_suggestion Twig filter!

This enables a whole bunch of possibilities within Drupal theming! One use case that I’m excited about is passing titles ({{ label }} in the templates) to something like field--h3.html.twig . Within Drupal (and other CMS’s) it’s often difficult to keep a correct document outline (h3’s nested only under h2’s etc). This will help smooth the process.

History of this filter

This filter was originally created by Lullabot’s Hawkeye Tenderwolf, who wrote an article a couple years back called, Level Up Your Twiggery (which is still a fantastic article!). In this article Hawkeye created this filter as the |as filter (which makes sense semantically).

Several months ago I mentioned this filter and use-case to Acquia’s Lauri Eskola (Drupal front-end framework manager and core committer), and he saw the value immediately. We reached out to Hawkeye, who created the initial merge request.

Work and bike-shedding were done, including renaming the filter from |as to |add_suggestion at the suggestion of core committer Alex Pott. The thinking was that by renaming it to “add suggestion” will give new Drupal front-enders more insight to what’s happening under the hood.

These new suggestions will (currently) not show in Twig debug

Note that these issues will currently not be viewable in the HTML comments when Twig debug mode is enabled. This is because of the core issue Twig debug output does not display all suggestions when an array of theme hooks is passed to #theme. This is the same issue that also causes the Views module’s templates to not show. The issue is currently set to “Needs Review” and we need lots of testing to ensure that this doesn’t break anything.

More Twig goodness is coming!

Relevant to this is the Create twig filters: |add_class, |remove_class, and |set_attribute issue that’s currently being worked on. This will pair nicely with |add_suggestion by chaining filters, for example:

{{ content.field_item|add_suggestion('icon')|add_class('icon--forward') }}

The example above will load the field--icon.html.twig and add an icon--forward CSS class!

Beyond this new filter, we’re working on lots of new front-end tools for Drupal 10 (not all of which will make the 10.0.0 release), including a |value filter, single directory components, and more!