Essential Theming Hooks in Drupal 9 with Examples

Theming in Drupal 9 allows you to control the visual presentation of your website. It's a powerful aspect of Drupal's flexibility, enabling you to customize the look and feel of your site to meet specific design and branding requirements. In this blog post, we'll explore some essential theming hooks in Drupal 9, along with practical examples to demonstrate how to leverage them for your site's theming needs.

Prerequisites

Before diving into Drupal 9 theming hooks, you should have:

1. A Drupal 9 website up and running.
2. Basic knowledge of HTML, CSS, and PHP.
3. Familiarity with Drupal theming concepts.

1. hook_theme()

The hook_theme() function allows you to define and register theme functions and templates for your module. You can define the structure of your theme functions and the templates they use.

Example:

/**
 * Implements hook_theme().
 */
function mymodule_theme() {
  return [
    'custom_template' => [
      'variables' => ['content' => NULL],
      'template' => 'custom-template',
    ],
  ];
}

In this example, we define a theme hook called custom_template and specify the template file it uses, along with the variables it receives.

2. hook_preprocess_HOOK()

hook_preprocess_HOOK() functions allow you to preprocess and modify variables before they are used in a template file.

Example:

/**
 * Implements hook_preprocess_HOOK() for block templates.
 */
function mytheme_preprocess_block(&$variables) {
  $variables['my_custom_variable'] = 'This is a custom variable for this block';
}

In this example, we add a custom variable to a block template to use in the corresponding template file.

3. hook_theme_suggestions_HOOK_alter()

This hook allows you to add or modify theme suggestions for templates.

Example:

/**
 * Implements hook_theme_suggestions_HOOK_alter() for block templates.
 */
function mytheme_theme_suggestions_block_alter(array &$suggestions, array $variables) {
  $suggestions[] = 'block__my_custom_block';
}

In this example, we add a custom template suggestion for a block with the machine name my_custom_block.

4. hook_preprocess_HOOK() for Form Elements

You can preprocess and modify form elements using hook_preprocess_HOOK() for specific form elements. This is especially useful for customizing form elements' appearance and behavior.

Example:

/**
 * Implements hook_preprocess_HOOK() for the form element 'textfield'.
 */
function mytheme_preprocess_textfield(&$variables) {
  $variables['element']['#attributes']['class'][] = 'custom-textfield';
}

In this example, we add a custom class to all textfields in form elements.

5. hook_theme_suggestions_HOOK()

This hook allows you to provide theme suggestions based on various criteria, including the content type, field name, or any other aspect of your site's content.

Example:

/**
 * Implements hook_theme_suggestions_HOOK() for node templates.
 */
function mytheme_theme_suggestions_node(array $variables) {
  $suggestions[] = 'node__' . $variables['elements']['#node']->getType();
  return $suggestions;
}

In this example, we create custom template suggestions for nodes based on their content types.

6. hook_theme_registry_alter()

You can use this hook to modify the theme registry, which contains information about theme hooks, templates, and more.

Example:

/**
 * Implements hook_theme_registry_alter().
 */
function mytheme_theme_registry_alter(array &$theme_registry) {
  // Remove a theme function.
  unset($theme_registry['menu_tree']);
}

In this example, we remove a theme function from the theme registry, preventing it from being used.

Conclusion

Theming is a fundamental part of customizing the look and feel of your Drupal 9 website. These essential theming hooks, along with countless others, provide you with the tools to create visually appealing and user-friendly web experiences. By understanding and utilizing these hooks, you can effectively control the presentation of your site and tailor it to your specific design and branding requirements.