Active
Project:
Drupal core
Version:
main
Component:
theme system
Priority:
Normal
Category:
Task
Assigned:
Unassigned
Issue tags:
Reporter:
Created:
14 Nov 2017 at 20:02 UTC
Updated:
5 Nov 2021 at 08:39 UTC
Jump to comment: Most recent
Problem/Motivation
#2118743: Twig debug output does not display all suggestions when an array of theme hooks is passed to #theme brought to light a severe symptom of using the "array of theme hooks" feature in the theme system.
In D6, #141730: Allow theming system to use wildcards introduced this "array of theme hooks" feature (for Views). It was, essentially, the first iteration of theme hook "suggestions" in core.
In D7 (#653622: Make the '__' pattern for theme suggestions easier to use, #678714: Unify use of theme hook / template suggestions, fix clobbering problems, and improve suggestion discovery performance), it was realized that passing array() each time and duplicating the same theme hook prefix was completely unnecessary and simply added more unnecessary technical debt:
But, if we're gonna use this in core, and if in core, we're settling on the '__' convention, let's make it easier to use. Instead of code having to call
theme(array('links__comment', 'links'), ...), how about lettingtheme('links__comment', ...)work.
It also moved to a more "internal" way of providing actual theme hook "suggestions" via $variables['theme_hook_suggestions'] in the preprocess phase.
In D8, dedicated hooks (#1751194: Introduce hook_theme_suggestions[_HOOK]() and hook_theme_suggestions[_HOOK]_alter()) were introduced for providing proper theme hook suggestions. These hooks removed the internal preprocess suggestions, but never removed the original "theme hook array" way of providing suggestions.
This wildly redundant, unnecessary, and antiquated technique for providing theme hooks suggestions should be deprecated and then ultimately removed in a future release.
Proposed resolution
- Migrate all existing code to utilize hook_theme_suggestions_HOOK:
- #2923634: [PP-1] Use hook_theme_suggestions in views
- Regexp shows about 31 uses in core currently (including Views):
['"]#theme['"]\]? =>? (?:array|\[)|['"]#theme['"]\]\[\] =|\$themes\[\]
- Deprecate the use of passing an array of theme hooks to
#themeand log a warning when it is used.
Remaining tasks
- Create a patch
- Modify existing tests
User interface changes
None
API changes
Deprecates and logs a warning when an array of theme hooks is passed to #theme.
Data model changes
None
Comments
Comment #2
markhalliwellComment #3
markhalliwellComment #4
markhalliwellComment #5
markhalliwellComment #13
johnalbinJust to complicate this further:
By default, all forms set
#themeto an array containing the form ID and don't implement that as a theme hook. And thenDrupal\Core\Theme\ThemeManager::render()checks if#themeis NOT an array before it logs a warning for 'Theme hook %hook not found.' Meaning unimplemented form id theme hooks never log a warning because they are passed as an array instead of a string.That means if we simply remove the ability for
#themeto be an array, all form rendering on all Drupal pages will log a warning.We'd need to add a way to tell core that a theme hook is expected to be unimplemented. Or to refactor how forms use form IDs as theme hooks.
Comment #14
marcvangendI would prefer a more strict situation where theme hooks must be implemented. If the theme system needs the form ID for whatever logic down the line, isn't that where #2511548: Add a "context" array variable to all theme hooks and "#context" array property to all elements to provide optional contextual data comes in?