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.API page: https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21...
IMHO the naming of hook functions in the API docs is confusing/misleading, e.g.
hook_theme_suggestions_HOOK_alter
Perhaps I'm being rather slow, but it took me some time before I realised the opening 'hook' was also a placeholder (for the theme name), not just the one in uppercase. I'd tried both of the following (for my 'test' theme) and XDebug (which not everyone will have setup) indicated they were not being matched:
hook_theme_suggestions_node_alter
test_hook_theme_suggestions_node_alter
when I actually needed:
test_theme_suggestions_node_alter
Could:
- the initial 'hook' also be in uppercase (in the explanatory text in the docs, I realise we can't change the code in core)
- OR it be named something else in uppercase, e.g. THEME/MODULE_theme_suggestions_HOOK_alter
- OR just provide example code with a named theme
Comments
Comment #2
wturrell CreditAttribution: wturrell commentedClarify suggested fixes.
Comment #3
eojthebraveI think my vote goes for option x3: "OR just provide example code with a named theme". If the existing documentation is confusing and makes it hard to figure this
hook_theme_suggestions_HOOK_alterpattern out we should fix that for sure. However, I'm somewhat hesitant to see us change the pattern itself in part because there is so much existing documentation both on Drupal.org and elsewhere that already uses this pattern.In fact, it looks like there is already an @todo in the documentation on https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21...
We could also probably add an @see to https://api.drupal.org/api/drupal/core%21core.api.php/group/hooks/8.2.x which explains the generic "hook_" concept a little bit more.