function hook_theme_suggestions_alter in Drupal 8

Same name and namespace in other branches

1. 9 core/lib/Drupal/Core/Render/theme.api.php \hook_theme_suggestions_alter()
2. 10 core/lib/Drupal/Core/Render/theme.api.php \hook_theme_suggestions_alter()

Alters named suggestions for all theme hooks.

This hook is invoked for all theme hooks, if you are targeting a specific theme hook it's best to use hook_theme_suggestions_HOOK_alter().

The call order is as follows: all existing suggestion alter functions are called for module A, then all for module B, etc., followed by all for any base theme(s), and finally for the active theme. The order is determined by system weight, then by extension (module or theme) name.

Within each module or theme, suggestion alter hooks are called in the following order: first, hook_theme_suggestions_alter(); second, hook_theme_suggestions_HOOK_alter(). So, for each module or theme, the more general hooks are called first followed by the more specific.

In the following example, we provide an alternative template suggestion to node and taxonomy term templates based on the user being logged in.

function MYMODULE_theme_suggestions_alter(array &$suggestions, array $variables, $hook) {
  if (\Drupal::currentUser()
    ->isAuthenticated() && in_array($hook, array(
    'node',
    'taxonomy_term',
  ))) {
    $suggestions[] = $hook . '__' . 'logged_in';
  }
}

Parameters

array $suggestions: An array of alternate, more specific names for template files or theme functions.

array $variables: An array of variables passed to the theme hook. Note that this hook is invoked before any variable preprocessing.

string $hook: The base hook name. For example, if '#theme' => 'node__article' is called, then $hook will be 'node', not 'node__article'. The specific hook called (in this case 'node__article') is available in $variables['theme_hook_original'].

Return value

array An array of theme suggestions.

See also

hook_theme_suggestions_HOOK_alter()

Related topics

4 functions implement hook_theme_suggestions_alter()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

test_theme_theme_suggestions_alter in core/modules/system/tests/themes/test_theme/test_theme.theme

Implements hook_theme_suggestions_alter().

theme_legacy_test_theme_suggestions_alter in core/modules/system/tests/modules/theme_legacy_test/theme_legacy_test.module

Implements hook_theme_suggestions_alter().

theme_suggestions_test_theme_suggestions_alter in core/modules/system/tests/modules/theme_suggestions_test/theme_suggestions_test.module

Implements hook_theme_suggestions_alter().

theme_test_theme_suggestions_alter in core/modules/system/tests/modules/theme_test/theme_test.module

Implements hook_theme_suggestions_alter().

File

core/lib/Drupal/Core/Render/theme.api.php, line 686

Hooks and documentation related to the theme and render system.

Code

function hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook) {

  // Add an interface-language specific suggestion to all theme hooks.
  $suggestions[] = $hook . '__' . \Drupal::languageManager()
    ->getCurrentLanguage()
    ->getId();
}