We have a convention in Drupal to allow for more specific tpl file implementations of a given theme hook. We do this by having one of the preprocess functions for the theme hook add options to $variables['template_files'], and by convention, we encourage these options to follow the format of the theme hook name followed by hyphen followed by some kind of additional specifier. For example, because of the code in template_preprocess_node(), a themer can have a node-TYPE.tpl.php file be used instead of node.tpl.php when theming a node of the specified type.
A hyphen is also used as a delimiter for template files corresponding to a multi-word theme hook. So, for example, a themer can decide to override the implementation of theme_node_list() by creating a node-list.tpl.php file in the theme's folder.
This presents us with 3 problems:
- Lack of clarity: if 'node-list.tpl.php' exists in the theme's folder, is it meant to be the template file for the 'node_list' theme hook or the template file for the 'node' theme hook for nodes of type 'list'?
- Undocumented restriction on what node types can be named: Effectively, the above means that I can't name a node type 'list' (or any other word for which a node_* theme hook exists) and be able to theme it with a node-TYPE.tpl.php file, because that same tpl file will also be used for theming the node_list theme hook.
- Bugs: On the flip side of the above, if I have a node-list.tpl.php file and intend it as an implementation for the node_list theme hook, then if I also have a node of type 'list', even if I don't need to theme it in a special way, it will still get themed with the node-list.tpl.php file, which almost certainly will result in the inability to view that node.
My suggestion is that we change the convention for $variables['template_files'] to use either triple hyphen ('---') or dot ('.') to separate the hook name from the specifier. So, in the above example, 'node-list.tpl.php' would be the implementation of the node_list theme hook and 'node---list.tpl.php' or 'node.list.tpl.php' would be the implementation of the node theme hook for nodes of type list.
Note, we can't use double hyphen ('--') since we're already using that as our convention of creating sub-hooks of a hook with a 'pattern'.
Any thoughts on this? I'll be happy to work on the patch file for this if we can get community agreement on what's desired.
Comments
Comment #1
effulgentsia commentedNo chance it's happening for D7. Maybe D8?
Comment #2
effulgentsia commentedYay, fields in core, which provided a use-case for this being fixed in #678714: Unify use of theme hook / template suggestions, fix clobbering problems, and improve suggestion discovery performance!