Tutorial: Changing the Base Theme on an Existing Custom Drupal Theme

If you were watching the Drupal security feed at the end of January, you might have been a little surprised (as I was) by the bombardment by “unsupported project” notifications. One such came for the Cog base theme. This was a bit of an oh shit moment for me, because GovCon still used Cog as the base theme. And while I didn’t have to “scramble” to remove the theme (because technically, the project page had been marked unsupported for some time) I wanted to be proactive because:

• I really dislike having projects in my projects that show red (either for security vulnerabilities or unsupported issues)

• I knew I’d write this article and having an example and experience would be useful. Because I’d never tried to change base themes before.

This post is a tutorial specifically for removing Cog, but it could be used for any base theme change in Drupal 8+.

Steps to Change a Base theme

What is a Base Theme?

A base theme as a foundation allows for faster and easier Drupal theming. These themes lack CSS styling, but provide theme regions and sometimes advanced features. Base themes were made to enable faster theme creation, allowing the designer to focus on building code from concept.

https://www.drupal.org/node/980434

If your theme has a base, it is defined in your custom theme’s .info.yml file.

See in Govcon repo.

The interesting thing about Cog (and the reason it is so easy to remove) is that it is itself a sub theme of the Drupal core stable theme. So, it’s easy enough to just change out the base theme setting in your custom theme from cog to something else (in this case, I would recommend changing it to stable since that is what Cog itself uses).

My experience in attempting this was a broken website. Oops!

As I scrambled to figure out why, I realized that Cog had some Twig templates and style sheets that I hadn’t explicitly pulled into my theme. Why would I, I hadn’t needed to change them! So, I had two choices:

1. Restyle my theme and fix the broken issues

2. Move the Twig templates and Base styles from Cog that I was missing into my theme

I opted for the second option given that the theme for Govcon is pretty simplistic (and I didn’t want to have to do a ton of restyling). For me this ended up being just a few missing template files, which you can see in the pull request. Essentially, I just copied the files from Cog into my theme and then used Git to review the diffs.

Thankfully, the GovCon site has both (simple) visual regression and accessibility testing so once I was relatively certain I had all the right pieces in place, I just had to open the pull request and wait for some confirmation.

The final consideration in the theme itself is if you have any build tools that are interacting with Cog directly. I didn’t, but you might. Just make sure that all of your build tools point at your custom theme (not the base) and ensure that any processing you are running on templates, styles, etc. are inclusive of the newly added files. For me, all of my processing was directory based already, so tossing the additional files in was no big deal (they got processed without additional changes).

Configuration and Base Theme Removal

Aside from the actual theme changes, the other two things to consider have to do with Drupal configuration and the removal of the theme itself.

First, on the configuration front, a base theme should be enabled. So if you are actively managing configuration, I would anticipate that you will need to disable the theme in core.extension.yml and delete any of the block config files related to cog.

Second, you will eventually need to composer remove drupal/cog. However, you cannot do this step yet. Remember, you cannot uninstall something from Drupal after you’ve removed it from the codebase. So, you need to make the theme changes (as described above) and delete the configuration. Then you need to STOP and completely deploy these changes out through to your production environment. Then, and only then (once Cog is completely uninstalled) can you safely remove it from composer and pull it from the codebase.

In the end, this ended up being a much easier swap than I anticipated it would. The basic steps where:

1. Change out the base theme in the .info.yml file

2. Disable Cog and delete its configuration

3. Add any base templates and/or styles out of the old base theme and/or restyle

4. Flush the caches

5. Thoroughly test and review (and tweak minor styling issues as needed)

6. Deploy through to production

7. composer remove drupal/cog

Photo by Andrew Branch on StockSnap

Related Content