Week 7: Learn about Preprocess Functions

This is Week 7 of the 7-week course Hands-On: Theming. Get started with Drupal theming in 1 hour a week for 7 weeks. Based on our popular Drupal Theming Workshop featured at DrupalCon.

Time to complete: About 1 hour

This week you will learn about preprocess functions and how to utilize them in a Drupal theme. Go through each tutorial and then apply what you've learned in the final hands-on exercise. After you complete the last tutorial listed (Exercise: Preprocess Functions), return to Hands-On: Theming for recommended next steps in the section, "Continue your theming journey".

Goal

  1. Understand the concept of preprocess functions
  2. Understand what kinds of functions and logic you can put in a .theme file
  3. Understand the concept of theme hook suggestions
  4. Understand how you can discover, add, or alter theme hook suggestions
  5. Be able to complete Exercise: Preprocess Functions in which you will:
  • Define a function that implements a preprocess hook
  • Define a new variable using PHP and make it available for use within a specific template file

Sign-up for weekly email reminders

Sign-up for the Hands-On Theming email list and get reminders and tips about each week's exercises!

Subscribe

Own this course

You can also purchase the Practical Drupal Theming course on Thinkific. The course material is the same, but you can access the content without a Drupalize.Me membership and you will own the course forever.

Tutorials in this course
Categories
Drupal 8, 9, and 10
More information

Preprocess functions allow Drupal themes to manipulate the variables that are used in Twig template files by using PHP functions to preprocess data before it is exposed to each template. All of the dynamic content available to theme developers within a Twig template file is exposed through a preprocess function. Understanding how preprocess functions work, and the role they play, is important for both module developers and theme developers.

In this tutorial we'll learn:

  • What preprocess functions are and how they work
  • The use case for preprocess functions
  • The order of execution for preprocess functions

By the end of this tutorial you should be able to explain what preprocess functions are and the role they play in a Drupal theme.

Categories
Drupal 8, 9, and 10
More information

Every theme can contain an optional THEMENAME.theme file. This file contains additional business logic written in PHP and is primarily used for manipulation of the variables available for a template file, and suggesting alternative candidate template file names. Themes can also use this file to implement some, but not all, of the hooks invoked by Drupal modules.

In this tutorial we'll learn:

  • The use case for THEMENAME.theme files, and where to find them
  • The different types of functions and hooks you can implement in a THEMENAME.theme file

By the end of this tutorial you should be able to know how to start adding PHP logic to your custom theme.

More information

Preprocess functions are specially-named PHP functions that allow themes and modules to modify the variables passed to a Twig template file. They are commonly used by themes to alter existing variables before they are passed to the relevant template files. For example; Changing the makeup of render array so that it renders an <ol> list instead of a <ul> list. Or appending data to the label of a node depending on custom logic.

In this tutorial we'll:

  • Define a new preprocess function in our theme's .theme file
  • Use the preprocess functions to modify the content of an existing variable before it's used in Twig

By the end of this tutorial you should be able to define new preprocess functions in a theme (or module) that manipulate the variables for a specific Twig template file.

Categories
Drupal 8, 9, and 10
More information

Preprocess functions are specially-named functions that can be used to add new variables to a Twig template file. They are commonly used by themes to add new variables based on custom PHP logic and simplify accessing the data contained in complex entity structures. For example: adding a variable to all node.html.twig template files that contains the combined content a couple of specific fields under a meaningful name like {{ call_to_action }}. Modules use preprocess functions to expose the dynamic data they manage to Twig template files, or to alter data provided by another module based on custom logic.

In this tutorial we'll learn how to:

  • Use PHP to perform some complex logic in our theme.
  • Store the resulting calculation in a variable.
  • Make that variable available to a Twig template file.

Example use cases for adding variables with preprocess functions include:

  • Anytime calculating the value to output in a template requires logic more complex than an if/else statement.
  • Anytime the desired value requires additional string manipulation beyond what can be easily accomplished using an existing Twig filter or function.

By the end of this tutorial you should be able to expose new variables to a Twig template file by defining a preprocess function in either a module or a theme.

Categories
Drupal 8, 9, and 10
More information

When determining which template file to use to theme an element, Drupal uses the list of theme hook suggestions to look for the best match. This allows for fine-grained control over how things appear based on dynamic state and contextual information in your application. The list of theme hook suggestions varies for each base template, so we need a way to figure out our options.

In this tutorial we'll look at:

  • How to determine the list of valid theme hook suggestions for any template file
  • How theme hook suggestions are added by modules and themes

By the end of this tutorial you should be able to explain how theme hook suggestions are added, and determine the valid suggestions for any template file.

More information

Themes and modules can alter the list of theme hook suggestions in order to add new ones, remove existing ones, or reorder the list. This powerful feature allows for the definition of custom logic in your application that can tell Drupal to use different templates based on your own unique needs. You might for example; use a different page template for authenticated users, or a custom block template for someone's birthday.

In this tutorial we'll cover:

  • Adding new theme hook suggestions from a theme using hook_theme_suggestions_HOOK_alter()
  • Altering the list of theme hook suggestions
  • Removing theme hook suggestions
  • Reordering the list of theme hook suggestions
Categories
Drupal 8, 9, and 10
More information

Once you've defined an asset library you'll need to tell Drupal when you want to add the CSS and JavaScript that it includes to the page. Ideally you'll do so in a way that allows Drupal to only add the corresponding assets on pages where they are needed.

You can attach a library to all pages, a subset of pages, or to elements in a render array. This allows you to have some assets that are global, and others that get loaded on an as-needed basis. To attach a library you'll need to know both its name and prefix, and then use one of the techniques outlined below to let Drupal know when to include it.

In this tutorial, we'll look at attaching asset libraries:

  • Globally, via your THEMENAME.info.yml file
  • Conditionally, via a preprocess function using the #attached render array property
  • Inside of a Twig template file

By the end of this tutorial you should be able to attach asset libraries in various different ways depending on your use case.

Categories
Drupal 8, 9, and 10
More information

Preprocess functions allow you change existing variables, or add new variables, for a template file using PHP code. In this final exercise for the course, you'll define a PHP function that implements a preprocess hook and define a new variable using PHP and make it available for use within a specific template file. Specifically we want to create a new variable named {{ today }} that contains the current date and gets passed to the page.html.twig template file. You should work on the exercise steps below first, and you can refer to the video if you need some help.

If you want to try and accomplish this on your own first you'll need to:

Learning objectives:

  • Create a THEMENAME.theme file.
  • Write a proprocess PHP function that adds variables to a page template file.

Note: At the end of this exercise, you'll find a video walk-through of the solution.

This course appears in the following guides:
Categories
Theming
Drupal 8, 9, and 10