Release Day: Theme Hook Suggestions
Blog postWe just added 2 new tutorials about Theme Hook Suggestions! First learn the concept behind this topic in our tutorial Discover Existing Theme Hook Suggestions. Then learn how to add them in our tutorial Add New Theme Hook Suggestions.
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.
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
Drupal 6 was released in February of 2008 and on February 26th, 2016, after 7 years, Drupal 6 was retired, in accordance with the Drupal community’s policy of only providing active support for two major versions of Drupal at any given time. While it is possible to migrate a Drupal 6 (or 7) site to Drupal 8, the tools are still in flux. While simple sites make for simple migrations—since most sites are not simple and require considerable research, planning, and effort to migrate—migration remains a complex process. Continue reading to find out more about how Drupal 6's end-of-life impacts Drupal site owners and what options you have if you still run a Drupal 6 site.
Release Day: Our Drupal 8 Theming Guide
Blog postToday, we're super excited to publish our Drupal 8 Theming guide, a collection of tutorials that will teach you everything you need to know to create amazing Drupal 8 themes. We've put hundreds of hours into researching, digesting and understanding the Drupal 8 theme system. We've poured over the existing documentation and helped to update it whenever we could. We've read the code that makes it all possible, we've dissected core and contributed themes, and talked with front-end developers at Lullabot about their experiences, in order to learn about best practices and unique challenges. And then we boiled it all down into the ultimate Drupal 8 theming guide.
What Is a Theme?
FreeThemes are the part of Drupal that you, and anyone else visiting your Drupal powered application, see when they view any page in their browser. You can think of a theme as a layer, kind of like a screen, that exists between your Drupal content and the users of your site. Whenever a page is requested Drupal does the work of assembling the content to display into structured data which is then handed off to the presentation layer to determine how to visually represent the data provided.
Drupal themes are created by front-end developer. Frequently referred to as themers, or theme developers. Themes consist of standard web assets like CSS, JavaScript, and images, combined with Drupal-specific templates for generating HTML markup, and YAML files for telling Drupal about the file and features that make up each individual theme.
In this tutorial we'll:
- Explain what a Drupal theme is.
- Explain the role of a Drupal themer in the process of building a Drupal site.
- Get a high level overview of the types of files/code that themes are made of.
By the end of this tutorial you should be able to explain what a Drupal theme is, and the kind of work a Drupal theme developer will be expected to do.
Template files are responsible for the HTML markup of every page generated by Drupal. Any file ending with the .html.twig extension is a template file. These files are composed of standard HTML markup as well as tokens used by the Twig template engine to represent dynamic content that will be substituted into the HTML markup when the template is used. As a theme developer, you'll work with this a lot.
In this tutorial we’re going to learn about:
- What template files are, and how they fit into the big picture of creating a theme
- How template files are used in order to allow theme developers to modify the HTML markup output by Drupal
- Naming conventions for, and specificity of, template files
Twig is the default template engine for Drupal. If you want to make changes to the markup that Drupal outputs you're going to need to know at least some Twig. In this tutorial, we will outline the role that Twig now plays in Drupal, how Twig impacts the theming experience, and where to find additional resources for learning Twig.
At the end of this lesson, you'll be able to:
- Describe the role that Twig plays in creating Drupal themes
- Explain how Twig impacts the theming experience in Drupal
- Locate additional resources for learning Twig
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.