#788900: Deprecate and remove usages of arg() reminded me that we still generate theme and template suggestions based on path, for example page--node--1.tpl.php

The problem

Now that most code in core is based on routes, someone could change /node/% to /content/% and your theme would break. This makes those suggestions impossible to use in contrib themes since they can't work generically.

Additionally HTML head is one of the least-cacheable parts of the page in 8.x, and per-path suggestions will make it harder to cache that HTML.

Also these suggestions are a bit broken in D8 in the first place, they include a suggestion with a percent character:

<!-- THEME DEBUG -->
<!-- THEME HOOK: 'html' -->
<!-- FILE NAME SUGGESTIONS:
   * html--node--2.html.twig
   * html--node--%.html.twig
   * html--node.html.twig
   x html.html.twig
-->
<!-- THEME DEBUG -->
<!-- THEME HOOK: 'page' -->
<!-- FILE NAME SUGGESTIONS:
   * page--node--2.html.twig
   * page--node--%.html.twig
   * page--node.html.twig
   x page.html.twig
-->

Proposed solution

Remove the automatic theme suggestions based on path parts.

Why this should be an RC target

1. This is code removal only.

2. In general, contrib themes never use the per-page suggestions (and if they do they're fragile), they're sometimes used by custom themes (and often incorrectly when block configuration, page manager or similar would be a better choice). So the disruption in terms of number of themes using the feature should be low.

3. New theme developers sometimes use this 'by mistake' instead of the better options in #2, which can lead to custom themes with 10-15 page templates all with minro variations, this is one of the worst maintenance issues with custom themes in the wild.

4. Also themes can add back the suggestions by copying the removed code to template.php.

5. While templates using the suggestions won't be picked up, there's no other disruption to actual sites from the change in terms of errors etc. even if they're using the feature, which 99.9% won't be.

Comments

Crell’s picture

I can't say I've used that functionality since Drupal 4.7 or so. Routes, view modes, etc. are far more robust. I'm +1 on removing the path-based suggestions.

andypost’s picture

The case in current project: I got a "/home" page that uses different layouts depending on user role,
and at the same time I need one of the same page--home-single.twig.html for other pages.

So hook_preprocess_page() is checking route object and current user.

Once we remove path based suggestions we need to introduce a clean way to use route name

davidhernandez’s picture

How much functionality would we lose? Would we lose page--front?

dawehner’s picture

@davidhernandez
We talk about this lines of code:

  if (\Drupal::service('path.matcher')->isFrontPage()) {
    $path_args = [''];
  }
  else {
    $path_args = explode('/', Url::fromRoute('<current>')->getInternalPath());
  }
  return theme_get_suggestions($path_args, 'page');

so this does not remove the page--front suggestion.

davidhernandez’s picture

Issue tags: +Needs change record

We are currently talking about this on the Twig group call, and no one seems to care if it goes. :)

mortendk’s picture

Yeah well - let me have an opinion on this;

Using a nid for a template is a common "mistake" that people do only cause its there, and D7 is such a pita to theme.
its an epic pita to take over a theme where theres page-nid-1.tpl, page-nid-9874.tpl, page-taxonmi-999. tpl - So killing the nodeid/termid - im fine with that

What would be sad was to not more have the path, as it do have some value (page-sectionname.html.twig / page-front.html.twig), cause thats a very common usecase.
else we would have to write that stuff ourself in foo.theme (so that would need some documentation + handholding)

andypost’s picture

change record should describe a way to use page templates, #2 is not answered

catch’s picture

@Morten so you mean keep the first part of the path like 'node', 'user', 'admin'?

That would still help with the cacheability part of this quite a lot.

mortendk’s picture

@catch yup at least keeping the first part :)

page--section.html.twig would be a common usecase where a theme would probably do an {% extend page.html.twig %} and then modify it that way.

i havent looked yet in how complicated it is to add new template suggestion to the theme in .theme, if its dead easy, this could just be a documentation issue

joelpittet’s picture

Status: Active » Needs review
StatusFileSize
new1.09 KB

Here is a patch to start the ball rolling on this.

davidhernandez’s picture

StatusFileSize
new1.1 KB

I think we should decide whether we're going to do this, and to what degree.

#11 needed rerolling.

catch’s picture

Issue tags: +D8 cacheability, +rc deadline

Tagging.

joelpittet’s picture

Version: 8.0.x-dev » 8.1.x-dev
Status: Needs review » Postponed

Missed the deadline on this one, bumping to 8.1.x

catch’s picture

Version: 8.1.x-dev » 8.0.x-dev
Status: Postponed » Needs review
Issue tags: +rc target triage

We missed the deadline but AFAIK this already doesn't work in head. So tagging for triage during rc

xjm’s picture

Status: Needs review » Needs work
Issue tags: -rc deadline +Needs issue summary update

To have committers consider it for inclusion in RC, we should add a statement to the issue summary of why we need to make this change during RC, including what happens if we do not make the change and what any disruptions from it are. You can add a section <h3>Why this should be an RC target</h3> to the summary.

catch’s picture

Issue summary: View changes

Fleshed out the issue summary a bit.

catch’s picture

Status: Needs work » Needs review
frob’s picture

Status: Needs review » Reviewed & tested by the community

#11 Worked for me.

catch’s picture

Issue summary: View changes
alexpott’s picture

Reading the issue summary and #6 makes me think this is a very good thing to do.

Is there anyway we can detect such templates and warn existing sites that they are now broken?

alexpott’s picture

Status: Reviewed & tested by the community » Needs work

Marking needs work for getting the CR written.

xjm’s picture

Issue tags: -rc target triage
berdir’s picture

I think this is an API change at this point, so no longer an option for 8.x? We could deprecate it or something but given that no IDE will show you that, I'm not sure how useful that really is?

catch’s picture

Version: 8.0.x-dev » 8.2.x-dev

The chance of a base theme or contributed theme using this is very slim.

That leaves custom themes for specific sites mostly. For those I think there are options:

- put it behind a setting, enabled for new sites but not existing ones
- put it in a new optional module, enabled for new sites but not existing ones

Or enabled for all sites by default then individual sites could disable it.

Since we have hook_theme_suggestions_alter(), there's no actual guarantee that this is available to all themes on all sites all the time already.

Arnion’s picture

StatusFileSize
new1.1 KB

Patch rerolled.

Arnion’s picture

Status: Needs work » Needs review
lokapujya’s picture

Status: Needs review » Needs work

Maybe an exception could be made to allow a BC break. But still Needs change record.

davidhernandez’s picture

- put it behind a setting, enabled for new sites but not existing ones
- put it in a new optional module, enabled for new sites but not existing ones

Is that backwards? Shouldn't it be enabled for existing sites but not new ones?

Regarding the BC module idea, has this been done yet for anything else? What is the plan for that exactly? Will there be multiple BC modules for different fixes, or one that covers everything as core progresses?

catch’s picture

We haven't so far needed a backwards compatibility layer in the same way that this issue might.

Generally changes we're making are either covered by the @internal policy (so we don't provide bc since it's not part of the API), or we just add @deprecated notices.

#2042165: Add a 'deprecated' module that includes deprecated functions only when enabled was the issue I first proposed the bc module. If we decide that 1. it's worth doing this issue at all 2. we need to provide bc, then this would be the first time it'd genuinely come up.

Another way might be to move the preprocess to 'Stable' - then all themes get it except those that have explicitly opted out of backwards compatibility, but that means slightly broadening the scope of stable then.

davidhernandez’s picture

Yeah, I thought about Stable but I don't like that idea. It essentially makes it permanent for most people since we aren't encouraging people to not use Stable. Being in preprocess you couldn't even undo it, could you?

star-szr’s picture

Issue summary: View changes

They could remove the suggestions from Stable in their own theme suggestion alter hook.

Looking at some of the basic suggestions that this code is creating out of the box (added to the issue summary) I don't think it's a problem to remove the node--2 and node--% (ha) but I worry that a non-trivial amount of folks will be using page--node/html--node suggestions. If we do add BC to Stable maybe we can limit it to the first path component?

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

smustgrave’s picture

Status: Needs work » Postponed (maintainer needs more info)
Issue tags: +stale-issue-cleanup

Thank you for creating this issue to improve Drupal.

We are working to decide if this task is still relevant to a currently supported version of Drupal. There hasn't been any discussion here for over 8 years which suggests that this has either been implemented or is no longer relevant. Your thoughts on this will allow a decision to be made.

Since we need more information to move forward with this issue, the status is now Postponed (maintainer needs more info). If we don't receive additional information to help with the issue, it may be closed after three months.

Thanks!

berdir’s picture

Status: Postponed (maintainer needs more info) » Needs work

Lets keep this for now.

We're close to add support for theme hook suggestions. That said, not sure this is worth the trouble. This is discouraged but there are going to be so, so many such templates out there

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.