function theme_get_suggestions in Drupal 9

Same name and namespace in other branches

1. 8 core/includes/theme.inc \theme_get_suggestions()
2. 7 includes/theme.inc \theme_get_suggestions()

Generate an array of suggestions from path arguments.

This is typically called for adding to the suggestions in hook_theme_suggestions_HOOK_alter() or adding to 'attributes' class key variables from within preprocess functions, when wanting to base the additional suggestions or classes on the path of the current page.

Parameters

$args: An array of path arguments.

$base: A string identifying the base 'thing' from which more specific suggestions are derived. For example, 'page' or 'html'.

$delimiter: The string used to delimit increasingly specific information. The default of '__' is appropriate for theme hook suggestions. '-' is appropriate for extra classes.

Return value

An array of suggestions, suitable for adding to hook_theme_suggestions_HOOK_alter() or to $variables['attributes']['class'] if the suggestions represent extra CSS classes.

5 calls to theme_get_suggestions()

seven_preprocess_html in core/themes/seven/seven.theme

Implements hook_preprocess_HOOK() for HTML document templates.

system_theme_suggestions_html in core/modules/system/system.module

Implements hook_theme_suggestions_HOOK().

system_theme_suggestions_page in core/modules/system/system.module

Implements hook_theme_suggestions_HOOK().

ThemeTest::testFrontPageThemeSuggestion in core/modules/system/tests/src/Functional/Theme/ThemeTest.php

Ensure page-front template suggestion is added when on front page.

ThemeTest::testThemeSuggestions in core/modules/system/tests/src/Kernel/Theme/ThemeTest.php

Tests function theme_get_suggestions() for SA-CORE-2009-003.

File

core/includes/theme.inc, line 1464

The theme system, which controls the output of Drupal.

Code

function theme_get_suggestions($args, $base, $delimiter = '__') {

  // Build a list of suggested theme hooks in order of
  // specificity. One suggestion is made for every element of the current path,
  // though numeric elements are not carried to subsequent suggestions. For
  // example, for $base='page', http://www.example.com/node/1/edit would result
  // in the following suggestions:
  //
  // page__node
  // page__node__%
  // page__node__1
  // page__node__edit
  $suggestions = [];
  $prefix = $base;
  foreach ($args as $arg) {

    // Remove slashes or null per SA-CORE-2009-003 and change - (hyphen) to _
    // (underscore).
    //
    // When we discover templates in @see drupal_find_theme_templates,
    // hyphens (-) are converted to underscores (_) before the theme hook
    // is registered. We do this because the hyphens used for delimiters
    // in hook suggestions cannot be used in the function names of the
    // associated preprocess functions. Any page templates designed to be used
    // on paths that contain a hyphen are also registered with these hyphens
    // converted to underscores so here we must convert any hyphens in path
    // arguments to underscores here before fetching theme hook suggestions
    // to ensure the templates are appropriately recognized.
    $arg = str_replace([
      "/",
      "\\",
      "\0",
      '-',
    ], [
      '',
      '',
      '',
      '_',
    ], $arg);

    // The percent acts as a wildcard for numeric arguments since
    // asterisks are not valid filename characters on many filesystems.
    if (is_numeric($arg)) {
      $suggestions[] = $prefix . $delimiter . '%';
    }
    $suggestions[] = $prefix . $delimiter . $arg;
    if (!is_numeric($arg)) {
      $prefix .= $delimiter . $arg;
    }
  }
  if (\Drupal::service('path.matcher')
    ->isFrontPage()) {

    // Front templates should be based on root only, not prefixed arguments.
    $suggestions[] = $base . $delimiter . 'front';
  }
  return $suggestions;
}