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.

Make your theme a subtheme of a base theme, allowing it to inherit all the base theme's templates and other properties. When creating Drupal themes it is common to use the Classy theme provided with Drupal core as a base theme to jumpstart your development.

In this tutorial we'll learn how to:

• Use the base theme key in our theme's THEMENAME.info.yml file
• Make our Ice Cream theme inherit from the Classy theme, or any other theme

By the end of this tutorial you should be able to tell Drupal that your theme is a child of another theme and should inherit all of the parent theme's features.

An asset library is a bundle of CSS and/or JavaScript files that work together to provide a style and functionality for a specific component. They are frequently used to isolate the functionality and styling of a specific component, like the tabs displayed at the top of each node, into a reusable library. If you want to include CSS and/or JavaScript in your Drupal theme or module you'll need to declare an asset library that tells Drupal about the existence, and location, of those files. And then attach that library to a page, or specific element, so that it gets loaded when needed.

In this tutorial we’ll:

• Define what an asset library is.
• Explain why asset libraries are used to include JavaScript and CSS files.
• Look at some example asset library definitions.

By the end of this tutorial you should be able to define what asset libraries are, and when you'll need to create one.

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.

Customizing the available regions in your theme is one of the first things you'll do when creating your own themes. Doing so gives you complete control over where content is displayed on the page, and the markup involved. Adding regions to a theme is a two-step process that involves editing your theme's THEMENAME.info.yml file and updating your page.html.twig file.

In this tutorial we'll:

• Declare one or more new regions in our themes THEMENAME.info.yml file.
• Output the content of those regions in our theme via the page.html.twig file.

By the end of this tutorial you should be able to add or edit the regions a theme provides. Also, you'll ensure that blocks placed into regions are displayed by outputting the regions in the page template.

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.

Twig has a special syntax for accessing array keys and objects, also known in Twig as variable attributes. In this tutorial, we'll cover the period or dot (.) operator to access a variable attribute, as well as subscript or square-bracket syntax, useful for when the key of the array contains special characters, like a dash (-) or pound sign (#). We'll also look at the logic Twig uses to find the matching attribute in an array or object.

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.

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.

Theme developers often need to add or remove classes and other attributes from an HTML tag. Template files handle this with a special Attributes object that contains the attributes and their values, as well as a handful of powerful methods to help manage these attributes.

In this tutorial we’ll cover:

• Adding/removing classes from elements in a Twig template
• The attributes object
• Examples of common tasks using various helper methods on the attributes object

Making Drupal fast by default implies having caching layers and CSS and JavaScript aggregation utilities enabled out-of-the-box. As a theme developer this can be annoying, because you must clear these various caches in order to preview any changes. In addition, inspecting variables with debugging tools often produces PHP errors. We'll make some recommendations for PHP settings on your local environment that can prevent these errors from happening so often.

By the end of this tutorial, you should be able to:

• Set up your local Drupal site for theme development
• Prepare your local development environment for working on and debugging themes

New asset libraries can be defined by either modules or themes. In order to define a new asset library you need to create the requisite CSS and JavaScript files, and a new THEMENAME.libraries.yml, or MODULENAME.libraries.yml file that aggregates them together and provides metadata about the library itself and any dependencies.

In this tutorial we’ll:

• Look at the structure of a *.libraries.yml file and demonstrate how to combine a couple of CSS and JS files together into an asset library that can be used in a theme or a module
• Look at how one asset library can declare that it is dependent on another in order to ensure the assets from the dependency are loaded as well

By the end of this tutorial you should know how to define a new asset library in either a module or a theme.

If you want to make changes to the HTML markup of any element on the page you need to first figure out the theme hook or base name of the template file used to generate it. This information is required to override the template in your custom theme.

There are other situations in which knowing the theme hook name of a template file is useful. Including determining which preprocess function affects a template, and which template theme hook suggestions can be used.

In this tutorial we'll learn:

• How to figure out the theme hook name for any template

By the end of this tutorial you should be able to use the output from Twig's debugging mode to determine the theme hook name of any template file.

Drupal core comes with a few base themes: Stable, Stable 9, Classy, and Stark. Each one has a different intended use case. And all of them are useful as a reference for building your own themes.

In this tutorial we'll:

• Learn what each of the base themes included in Drupal core is intended to be used for
• Compare the output from the base themes with a focus on Stable and Classy

By the end of this tutorial you'll be able to explain the use case for each of the base themes included with Drupal core and make an informed decision about which, if any, to use when creating your own custom themes.

Drupal comes with all of its caching features enabled by default. This improves response time, but can be frustrating for themers as it makes it harder to preview the changes you make to template files.

In this tutorial we'll look at:

• Why these features are enabled by default
• How the theme layer leverages Drupal's caches
• Why you should learn to disable them when doing development

Knowing how to inspect the variables available within a template file enables you to discover all of the dynamic content in a Twig file, not just that which is already being used.

In this tutorial, we'll learn how to use {{ dump() }}, kint(), vardumper(), and XDebug to inspect variables in a template file.

Before visitors to your site will see the pages displayed using a theme the theme needs to be installed and set as the default. This is true whether it's a custom theme you wrote yourself, or a contributed theme you downloaded from Drupal.org. Installing themes can be done either via the user interface, or using Drush. Once a theme is installed, users of your site will see all public facing page rendered using that theme. Themes that are no longer being used can safely be uninstalled.

In this tutorial we'll:

• Demonstrate how to install a theme and make it the default using both the UI and Drush.
• Learn to differentiate between installed themes, default themes, and uninstalled themes.
• Configure our site to use an administration theme for the administrative pages.

By the end of this tutorial you should be able to install a theme and make it the one visitors to your site see by default.

JavaScript is used and loaded in special ways within a Drupal site. JavaScript is loaded via asset libraries and Drupal core provides a bunch of different JavaScript libraries that you can load and use in your module or theme. This tutorial provides a brief orientation to some of the JavaScript included in core.

In this tutorial we'll:

• Preview the JavaScript ecosystem in Drupal
• Find pointers to tutorials where you can learn more about adding JavaScript to a theme or module
• Learn about examples of JavaScript in Drupal core that are useful to review for learning purposes

By the end of this tutorial you should have a good overview of how JavaScript is used throughout Drupal core.

Many of the variables that you have access to inside of a Twig template file are arrays. For example a list of values for a multi-value field, or a set of error messages generated when validating a form submission. In order to work with arrays in Twig you'll need to understand how for loops work. This is essential information for anyone creating Drupal themes.

In this tutorial we'll cover:

• Using the for tag to iterate over an array
• Using the loop variable inside of a for loop for additional context

Any text that will be displayed to user as part of your application's user interface should be passed through the t() function, or an equivalent, so that it can be translated into other languages as needed. This tutorial will look at how to use the t() function.

This tutorial contains information that applies to anyone writing modules or themes. And many of the tutorials you read on this site and on the web in general will expect that you understand how basic string translation works.

In this tutorial we'll look at:

• Passing strings through the t() function or equivalent so they are available for translation
• Using placeholders for dynamic content in translatable strings
• Tips for making your code's interface strings easier to translate