Decide what to display for 'THEME HOOK' in Twig debug for special cases such as arrays of theme hooks

Created on 11 August 2017, over 7 years ago
Updated 5 August 2024, 4 months ago

Follow-up to 🐛 Twig debug output does not display all suggestions when an array of theme hooks is passed to #theme Needs work

Updated: Comment #N

Problem/Motivation

When an array of suggestions is passed to #theme, the 'THEME HOOK' part of Twig debug output will vary depending on which template overrides are in use. When using the theme suggestions hooks (like hook_theme_suggestions_HOOK_alter()) the THEME HOOK will always be the single theme hook passed to #theme.

For example, on a standard install of D8 if you view source on the homepage:

<!-- THEME DEBUG -->
<!-- THEME HOOK: 'views_view' -->
<!-- FILE NAME SUGGESTIONS:
   * views-view--frontpage--page-1.html.twig
   * views-view--page-1.html.twig
   * views-view--default.html.twig
   * views-view--frontpage--page.html.twig
   * views-view--page.html.twig
   * views-view--frontpage.html.twig
   x views-view.html.twig
-->
<!-- BEGIN OUTPUT from 'core/themes/classy/templates/views/views-view.html.twig' -->

Now, if you create views-view--frontpage--page-1.html.twig inside Bartik:

<!-- THEME DEBUG -->
<!-- THEME HOOK: 'views_view__frontpage__page_1' -->
<!-- FILE NAME SUGGESTIONS:
   x views-view--frontpage--page-1.html.twig
   * views-view--page-1.html.twig
   * views-view--default.html.twig
   * views-view--frontpage--page.html.twig
   * views-view--page.html.twig
   * views-view--frontpage.html.twig
   * views-view.html.twig
-->
<!-- BEGIN OUTPUT from 'core/themes/bartik/templates/views-view--frontpage--page-1.html.twig' -->

Proposed resolution

Discuss what we should display here.

Remaining tasks

TBD

User interface changes

TBD

API changes

TBD

🐛 Bug report
Status

Active

Version

11.0 🔥

Component
Theme 

Last updated about 19 hours ago

Created by

🇨🇦Canada star-szr

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • 🇧🇷Brazil mabho Rio de Janeiro, RJ

    A comma-separated list would be much worse in terms of readability. If you want to get a better experience inspecting theme suggestions than scanning through the source code, I can recommend the Visual Debugger module .

  • 🇪🇨Ecuador jwilson3

    Re: #9

    What value does [this THEME HOOK Twig debug line] give versus the FILE NAME SUGGESTIONS debug comment?

    In my opinion, the THEME HOOK debug output is not at all useful, in its current state. A typical f/e developer does not, and will never need to, know what exact THEME HOOK was called, because the format in which it is presented (camel case, with underscores) is not very useful.

    Here's why:

    • THEME HOOK is currently providing the same generic insight and information as the selected template in FILE NAME SUGGESTIONS, except with underscores instead of dashes and without the ".html.twig" tacked onto the end.
    • With Drupal 8+ there was a concerted effort to move all render functions out of PHP and into Twig templates. Setting aside the html_tag oddity, it would be interesting to know whether there are even still any vestiges of theme functions in PHP left over in D10/11 now? They MUST be all gone by now right? ... right?
    • There is no guarantee that the THEME HOOK formatted version of the template filename that was called is going to match the name of the preprocess hook(s) that were called before rendering the template. I mean, parts of the preprocess hook function name might match but the complete THEME HOOK string "as is" is not always going to be directly copy/paste-able or searchable/findable anywhere in a theme's codebase.
    • The only place a THEME HOOK could be used "as is" would be in the backend when a dev is creating a render array to call a theme function via #theme. But it would be so rare to need to retroactively change (harden) the #theme function that is used after the frontend template override was implemented as a Twig template, that it seems completely useless for this purpose.

    What IMO would be more useful in its stead are:

    • a list (comma-separated or otherwise) of all preprocess hook implementations that were actually called, in the correct order (ideally first to last or last to first). This can also be determined using a step debugger, but perhaps some frontend devs aren't adept at using Xdebug.
    • a copy/paste-able list of all the possible preprocess hooks that could be written for the given template. This would be nothing more than a nice-to-have and amounts to duplicate information since it can already be interpolated directly from FILE NAME SUGGESTIONS.
Production build 0.71.5 2024