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.
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
Looking Back, Looking Forward
Blog postLast year was a year of waiting for Drupal 8 and working on big changes at Drupalize.Me. Now that we’re into 2016, I want to take a break to reflect on 2015 and take a look at where we’re headed next.
In 2015, we released a series called What's New In Drupal 8, which gives an overview of the different things that have changed in the upcoming version of Drupal. We've added a "Notify me" button to these particular lessons so members can get added to a notification list for that topic.
PHP developers are pretty darn excited because Drupal 8 has a new object-oriented framework with some Symfony components. Are you ready to learn how to leverage these Symfony components in your Drupal 8 module? Then check out this new set of tutorials from our friends at KnpUniversity: Module Development Essentials.