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 afor
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
In order to ensure that all user interface strings in your application can be translated using Drupal's localization system, any text you add to templates needs to use either the t
filter or the {% trans %}
tag. Anyone creating themes or editing template files associated with a theme or a module should know how to use these two utilities.
In this tutorial we'll look at:
- How to use the
t
filter and{% trans %}
tag in a Twig template - The differences between the two, and how to determine which one to use
- How to translate strings assigned to variables in preprocess functions using the PHP
t()
function
This tutorial demonstrates how to locate the template file that is currently being used to render an element and override it in your own theme. This is an important skill for anyone who wants to make changes to Drupal's default HTML markup.
In this tutorial we'll:
- Override the node.html.twig template in our theme
- Make changes to the markup
- Create a content-type-specific template override like node--CONTENT_TYPE.html.twig
By the end of this tutorial you should be able to modify the HTML markup used to display a node, or any other element of the page generated using a template file.
The ability to loop over an array of values in a Twig template and print out each value individually is an important skill for anyone developing themes for Drupal. Common scenarios include: loop over the values of a multiple value field; iterate through a list of links; and display error messages at the top of forms. This tutorial will provide an example of using the Twig for
function to iterate over a list, or a subset of a list.
In this tutorial we'll cover how to:
- Output values from a multi-value field in an unordered list.
- Add first and last classes to the first and last items in a list by using the Twig
loop
variable.
By the end of this tutorial you should be able to print out the values of an array as individual list items using a loop in Twig.
Themes define the regions that are available for site administrators to place blocks in, creating a layout framework within which the components that compose a page can be placed. As a theme developer you'll need to determine what regions are necessary to accommodate your design's layout, while also ensuring it'll work with the way Drupal uses blocks to place content onto the page. Deciding what regions to create requires knowledge of how Drupal works and a clear vision of the design you're trying to achieve.
In this tutorial we'll:
- Explain what regions are and how they relate to themes
- Describe how regions are handled internally within Drupal
- Demonstrate things to keep in mind when planning the regions for your custom theme
By the end of this tutorial you should be able to describe what a region is, explain how Drupal themes use regions to place content, and get started dissecting your own designs into regions.
Before you can create a path or link to another page on your site, you'll need to know the route (unless there is already a variable available for the URL you need). Finding a route can be a tricky task unless you have the right tools. In this tutorial, we'll show how tools like Webprofiler, Drush, and Grep can be used to get route information for a page, so that you can use functions that need a route as a function parameter.
In this tutorial we'll:
- Learn how to determine the route or path of an internal page.
Each theme is a collection of files that define a presentation layer for Drupal. While only a THEMENAME.info.yml file is required, most themes will contain other files as well. Some are Drupal-specific, and need to follow a strict naming convention and be placed in the appropriate place for Drupal to find them. Others are standard front-end web assets like CSS, JavaScript, and image files that can be placed anywhere within the theme's code.
In this tutorial we'll learn about:
- The various types of files you can expect to find in a theme directory
- Where in the Drupal code base your theme directory should live
- Keeping the directory and all the files within organized
By the end of this tutorial you should be able to explain where a Drupal theme should be placed in a project's code base, and the types of files one can expect to find in a theme.
Custom themes in Drupal must be configured to inherit settings, templates, and other assets from a parent theme. Which base theme you use is configurable. This allows theme developers to use a different set of markup as the starting point for their theme, organize various theme assets into a more maintainable structure, and more. All of this is made possible because of how Drupal's theme layer uses a chain of inheritance when assembling all the parts of a theme.
Base themes are also a powerful way to encapsulate standards and best practices into a reusable code base. You'll find dozens of contributed base themes on Drupal.org that can serve as a great starting point, especially if you're planning to work with an existing design framework like Bootstrap or Susy Grids. Or if you want to leverage modern JavaScript bundling without setting up Webpack on your own.
In this tutorial we'll:
- Learn what base themes and subthemes are
- Look at a few examples of template inheritance and how that works
- Discuss some use cases for theme inheritance
By the end of this tutorial you'll know how to declare the base theme that your theme builds upon.
In Twig, you can modify variables using functions or filters. Twig has a bunch of built-in functions and filters. Drupal extends Twig to provide a few handy Drupal-specific functions and filters as well.
In this tutorial, we'll look at:
- What are functions and filters?
- How to use functions and filters in Twig
- Detailed information about the Drupal-specific functions and filters and their use case
To read a Twig template file, you'll need to recognize Twig's syntax delimiters. Twig has three syntax delimiters: one for printing out variables, another for performing actions or logic, and lastly, one for comments, also used for docblocks.
In this tutorial we'll:
- Explore each of Twig's 3 syntax delimiters.
- Show examples of each from Drupal's core template files.
By the end of this tutorial you should be able to recognize each of Twig's syntax delimiters and understand what the engine will do when it encounters them.
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.