Quick Guide to Drupal Subtheming

Drupal offers a fantastic mechanism for creating a new theme that builds on an existing theme. For example, if a Drupal theme does 99% of what you want, but you want to change the CSS or javascript in it, subtheming is a great answer. You can get started very quickly.

Drupal!Why create a subtheme?

Let's just back up one second and talk about why you would want to use subtheming. If you're already convinced, then just skip below to the list of steps for creating a subtheme.

The site you are looking at right now, monkeysatkeyboards.com, is a subtheme of Zen. 90% of the work in it is CSS and Javascript customizations. So we focus on making the site look good instead of rewriting very similar HTML over and over.

When first encountering Drupal's theming system, you may have an urge to take an existing theme and just modify the files directly. While this works, it is not recommended. The primary reason is keeping your code up to date with the latest bug and security fixes. A good secondary reason is tidiness. It is cleaner to keep your customizations separated from existing themes.

If you just hack up an existing theme and then an issue is discovered in it and fixed by the original developer, how do you now apply that fix? The answer is that you have to find the exact changes in the original theme and apply them back into your own, a tedious and error prone process.

However if you used subtheming, then you can drop in the updated base theme (or really, just use the Drupal automatic update system) and this does not affect your custom code in any way. It keeps things separated and clean and really leverages the work that the original theme author is putting in to the project. For similar reasons you should not modify core or third party Drupal modules, you end up breaking the automatic updates mechanism.

To create a subtheme:

  1. Find a base theme that you want to extend. If you want a plain theme and plan on overriding most of the functionality yourself, Zen or Omega are two fantastic base themes that don't have much in them by default, ready to make something highly custom. Otherwise pick a more rich visual theme for a base.
  2. Create directory sites/all/themes/mytheme
  3. Copy the info file from the base theme to the new theme, example: cp sites/all/themes/zen.info sites/all/themes/mytheme/mytheme.info . It should be named the same as your directory with a .info extension.
  4. Copy screenshot.png from the base theme to your theme (or take an actual screenshot and crop it to that size).
  5. Edit mytheme.info. Change the name and description and project. "project" should have the same name as your directory and the base filename of the .info file. Add line "base theme = [base theme project name]". The original value of "project" from this info file is what you put for the base theme value.
  6. Remove the stylesheets and script lines from mytheme.info, they refer to files in the original theme. Add line "stylesheets[all][] = mytheme.css" and create file mytheme.css .  Leave the list of regions, these are not inherited from the base theme.
  7. Make a "templates" directory and an empty file called "template.php".
  8. Enable your new theme in Drupal admin under "Appearance".

Using your subtheme:

Other theming guides around the web and on drupal.org will tell you to create templates inside the templates subdirectory or put functions into template.php. These files will override their equivelants in the original "base theme" and your "mytheme.css" will be included on every page view that uses your theme.

You can also now almost directly "hack" the files of the original theme. For example, copy sites/all/themes/zen/templates/node.tpl.php into sites/all/themes/mytheme/templates and hack that up. Now you are using your own custom node.tpl.php but everything else from Zen.

It's a good idea to try to minimize the amount of code copied from the original. For example, if you copy all of the templates and template.php from the original base theme, then you are not really leveraging subtheming at all. We want to take advantage of the HTML structure that the theme author has already put considerable time into. So the goal should be "let the base theme take care of as much as possible, only override when it's absolutely necessary." Much of the customization can be done in your subtheme's CSS file without involving a lot of custom HTML.

In a future blog post I will discuss some detailed tips and tricks to help you work with an existing theme, in order to truly leverage the work the the author put in to the base theme.