Learning to create a Drupal theme is a bit of a mixed bag right now. A lot has changed--for the better-- since Drupal 8 was released. And there have been some pretty major paradigm shifts in theming best practices. The challenge is that, for a while, the old and new approaches have to coexist. New best practices have to be disseminated. Documentation needs to be updated. Meanwhile, existing projects started before new features were introduced will continue to need work, potentially for years to come. During this sort of middle-era (in which we are currently working), you really have to understand both ways of doing things.
You might be starting a brand new theme, in which case you’ll take the new approach. Or you might be inheriting an existing theme that’s been in use for a few years and is using the older (but still totally relevant) approach.
We’re getting ready to run another iteration of our popular Hands-On Drupal Theming workshop (July 19th, 20th, and 21st), something we haven’t done for over a year as we’ve been focused on teaching Drupal 7 to Drupal 9/10 migrations. In the process of getting ready, I’ve been going through my slides for the workshop and making some updates. Here are the things that jump out to me as important (but work-in-progress) changes in the last year.
Goodbye, Classy. Hello, Starterkit.
For years, every time you started a new theme, the first decision you had to make was which base theme to use. Classy? Stable? Maybe a contributed one from Drupal.org like Omega or Bootstrap? You would start your theme with an info file, and declare the base theme from which you wanted to inherit. Then you'd override the few (who am I kidding...many!) template files whose markup you needed to modify. And inherit the rest.
This approach has served Drupal well for years. But, it has one major flaw. The base theme that you’re inheriting from can never change. At least not without potentially breaking your custom theme that’s built on top of it. There’s no way for a base theme maintainer to know which specific bits of markup, which classes, which logic in an overridden template file, upon which your custom theme relies.
This means that Drupal core was never able to change either the Classy or Stable base themes after the initial release of Drupal 8.0.0. Now years later, they are no longer a reflection of current front-end best practices. If you inherited from a contributed theme, you would be responsible for sorting out any changes if that contributed theme was ever updated. Your custom theme is no longer an info file and a few templates, it also includes a fork of all the other themes that your theme inherited from at the time that you started. And you might not even know it.
As of Drupal 10, Classy has been removed from core, and the practice of relying on a core-provided base theme has been deprecated. Going forward, I think most new themes will start like this:
# Run this command from the root of your Drupal installation.
php core/scripts/drupal generate-theme my_awesome_theme
> Theme generated successfully to themes/my_awesome_theme
You’ll run the command above, and this will result in the generation of new theme scaffolding, ready for you to customize. This theme has dozens of files. It overrides every template in Drupal core, and many of the end-user-facing CSS asset libraries. It’s sort of the equivalent of duplicating the directory that contained the Classy theme, and renaming everything to my_awesome_theme.
I was initially going to title this section “Goodbye, Base Themes. Hello, Starterkit” but I felt that was a little misleading. Base themes, and how they work, isn’t changing. But I do think the use case is swinging away from base themes as a way to scaffold a new theme and toward base themes as a way to encapsulate shared components and other design elements.
Single Directory Components
I first learned about Single Directory Components (SDC) at this DrupalCon Pittsburgh presentation. Immediately convinced that they will become an important part of theming Drupal, I spent the whole sprint day working on documentation and examples for it.
From the docs:
Single Directory Components (often abbreviated as SDC) are Drupal core’s implementation of components. Within SDC, all files necessary to render the component are grouped together in a single directory (hence the name!). This includes Twig, YAML, and optional CSS, JavaScript, etc. SDC will automatically generate a library to load CSS/JS when the template is invoked.
Or put another way: Put your Twig (HTML) templates, CSS, and JavaScript files for a component (like a button, or a card) into a directory and if you follow the conventions, when you use the component in a template later, Drupal will take care of ensuring the appropriate CSS and JavaScript are added to the page on-demand. It’s slick!
The catch for now is that you have to be running the just-released Drupal 10.1.0 (or higher), and, for now, you have to have the experimental Single Directory Components module enabled. If you’re starting a new project today, you might be in a position to use them. But for existing projects you might not be able to use the feature yet. If you’re upgrading to Drupal 10.1+ from a site that was initially created with Drupal 9, you’ve already got a fully functioning theme. That’s not going to change, but you will be able to start porting things to use SDCs.
Eventually the code in the SDC module will likely be broken up and sprinkled into the core codebase, it’ll just be part of how Drupal works, and you won’t have to enable a separate module to use them.
We’ll talk about SDCs in our upcoming workshop. Both to let people know they are coming and to demonstrate how what you’re learning about creating a Drupal theme today will be directly applicable to SDC in the future.
Add new comment