This process in which Drupal determines the possible name of the template can be done in theme hook suggestions. Regions,blocks,page, fields, nodes and other components uses a custom template name suggestion: function hook_theme_suggestions_HOOK_alter.
With theme hook suggestions, there's a possibility that Drupal uses the cache, rather than the new templates. For this kind of problem you can clear the cache by choosing some of the following methods:
- Drush - drush cache-rebuild (Drupal 8) or drush cache-clear all/drush cc all for Drupal 7
- Run update.php
- Clearing the specific entries in cache tables
Templates can be added or modified by using the following hooks:
- hook_theme_suggestions_HOOK(array $variables)
- hook_theme_suggestions_alter(array &$suggestions, array $variables, hook)
- hook_theme_suggestions_HOOK_alter(array &$suggestions, array variables)
To further understand each hooks, here's an explanation on each:
- function hook_theme_suggestions_HOOK_alter - This hook will allow any modules or themes that is being provided by hook_theme_suggestions_HOOK() or an earlier invocations. The parameters in the function are: suggestions, variables. First the array of $suggestions is an array of theme suggestions, second array of $variables is the array of variables that is being passed to the theme hook.
- function hook_theme_suggestions_alter() - This hook is targeting a specific theme hook. The parameters being used are suggestions, variables and hooks in which the array of $suggestions means the array of alternate, or the more specific names for template files, on the other hand array of $variables is the array of variables that is being passed to the theme hook. The string hook is the base hook name, say for example $suggestions[] = 'block__' . $variables['elements']['#id']; then $hook will be block. So the return value is the array of suggestions. The only difference for this hook is that it follows a call order in which the existing suggestions alter functions are being called by module followed by the base theme and lastly the active theme. To shorten it, for each module or theme, the general hooks are called first followed by the more specific.
- function hook_theme_suggestions_hook - This hook will allow modules to provide a template name suggestions. The parameter is an array of $variables in which it is an array of variables passed to the theme hook.
When working with theme hook suggestions, Drupal will automatically convert the dashes the underscore and searches for templates in your theme.
Also it is important to take note for theme hook suggestions:
Underscores will be used instead of dashes since drupal will automatically convert it.
File extension will not be present since hooks can be implemented as a theme function or template files.
The suggestions will start with the hook__ say for example the block__, so the hook is block and followed by the most specific template like block--news-list.html.twig.
It is very important to take note that theme hook suggestions are not the same with theme hooks. Example is the block, you can create a preprocess for the block but you cannot create a preprocess for the suggestions that you created.
