function TwigExtension::suggestThemeHook

Same name and namespace in other branches
  1. 11.x core/lib/Drupal/Core/Template/TwigExtension.php \Drupal\Core\Template\TwigExtension::suggestThemeHook()

Adds a theme suggestion to the element.

Parameters

array|null $element: A theme element render array.

string|\Stringable $suggestion: The theme suggestion part to append to the existing theme hook(s).

Return value

array|null The element with the full theme suggestion added as the highest priority.

File

core/lib/Drupal/Core/Template/TwigExtension.php, line 679

Class

TwigExtension
A class providing Drupal Twig extensions.

Namespace

Drupal\Core\Template

Code

public function suggestThemeHook(?array $element, string|\Stringable $suggestion) : ?array {
  // Make sure we have a valid theme element render array.
  if (empty($element['#theme'])) {
    // Throw assertion for render arrays that contain more than just metadata
    // (e.g., don't assert on empty field content).
    assert(array_diff_key($element ?? [], [
      '#cache' => TRUE,
      '#weight' => TRUE,
      '#attached' => TRUE,
    ]) === [], 'Invalid target for the "|add_suggestion" Twig filter; element does not have a "#theme" key.');
    return $element;
  }
  // Replace dashes with underscores to support suggestions that match the
  // target template name rather than the underlying theme hook.
  $suggestion = str_replace('-', '_', $suggestion);
  // Transform the theme hook to a format that supports multiple suggestions.
  if (!is_iterable($element['#theme'])) {
    $element['#theme'] = [
      $element['#theme'],
    ];
  }
  // Add _new_ suggestions for each existing theme hook. Simply modifying the
  // existing items (appending to each theme hook instead of adding new ones)
  // would cause the original hooks to be unavailable as fallbacks.
  //
  // Start with the lowest priority theme hook.
  foreach (array_reverse($element['#theme']) as $theme_hook) {
    // Add new suggestions to the front (highest priority).
    array_unshift($element['#theme'], $theme_hook . '__' . $suggestion);
  }
  // Reset the "#printed" flag to make sure the content gets rendered with the
  // new suggestion in place.
  unset($element['#printed']);
  // Add a cache key to prevent using render cache from before the suggestion
  // was added. If there are no cache keys already set, don't add one, as that
  // would enable caching on this element where there wasn't any before.
  if (isset($element['#cache']['keys'])) {
    $element['#cache']['keys'][] = $suggestion;
  }
  return $element;
}

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.