Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
Template suggestions use underscores but template files currently use hyphens. Now that we are using templates by default for themeable output, this is a little bit of mental gymnastics (phrase c/o @joelpittet) that seems unnecessary.
Originally this issue proposed that we have theme suggestions defined with hyphens but then that doesn't work too well for specific prepare/preprocess functions since they would need to be converted to underscores anyway. hook_theme_prepare_node--my_content_type() wouldn't fly.
Proposed resolution
Use underscores across the board. Theme functions, theme suggestions, and template filenames.
Before
node--my_content_type.html.twig
After
node__my_content_type.html.twig
Relevant code from drupal_find_theme_templates():
// Transform - in filenames to _ to match function naming scheme
// for the purposes of searching.
$hook = strtr($template, '-', '_');
Remaining tasks
- Discuss repercussions
- Patch?
User interface changes
n/a
API changes
Theme suggestions would not be converted to hyphens for template files, so template files will use underscores by default.
Comments
Comment #1
star-szrFix error in API change section, add related issue
Comment #2
star-szrUpdating the whole issue after discussing on the Twig call with @Mark Carver and @joelpittet.
Comment #3
star-szrRemoving "Updated: Comment #N" thing because every issue summary update gets a comment now…
Comment #4
mortendk CreditAttribution: mortendk commentedconsistency is one of the many goals for the twig initiative - so its defently a +1 for me
Comment #5
webchickSo I'm definitely +1 from the consistency POV. We could eliminate some silly code like the quoted stuff in the issue summary.
However, I distinctly remember this being done for a reason, although alas I cannot remember the reason, and git blame only got me to #164122: Theme template file discovery does not translate _ into - properly which simply says this is what we do, not why. But IIRC we used - in template names because this was considered best practice something something. Argh. Maybe merlinofchaos remembers?
So I'd love to see more representation from front-end devs in here saying they like this change. It's obvious why theme system maintainers would want this change.
So not ready to pull "Approved API change" on this. Let's dig into why it was done, figure out of those reasons are still valid, and get more representation from other themers first.
Comment #6
ianthomas_ukThis would introduce double underscores into template names. Depending on the font these are not always obvious if you're not expecting them.
node__example.html.twig
This is particularly a problem for people unfamiliar with the platform conventions (as many people tweaking templates will be). It's also not easy to spot, as your shiny new template will just be ignored by Drupal with no error message.
Comment #7
star-szr@ianthomas_uk - that's a very good point. We have made it easier to spot though, because twig_debug shows you which template is in use and which templates you can use: https://drupal.org/node/1922666
Comment #8
joelpittetShould we bump this to D9 @Cottser?
Comment #9
star-szrYes, thanks @joelpittet.
Comment #10
catchThis could be done during template discovery with a bc layer in 8.x, or we could decide it's won't fix, but I don't think we should break all themes between 8.x and 9.x without a bc layer, so moving back.