Drupal Theming

David Mercer

September 2010

(For more resources on Drupal, see here.)


The use of themes makes Drupal exceptionally flexible when it comes to working with the site's interface. Because the functionality of the site is by and large decoupled from the presentation of the site, it is quite easy to chop and change the look, without having to worry about affecting the functionality. This is obviously a very useful feature because it frees you up to experiment, knowing that if worst comes to worst, you can reset the default settings and start from scratch.

You can think of a theme as a mask for your site that can be modified in order to achieve virtually any design criteria. Of course, different themes have widely varying attributes, so it is important to find the theme that most closely resembles what you are looking for in order to reduce the amount of work needed to match it to your envisaged design.

It is also important to understand that not all downloadable themes are of the same quality. Some are designed better than others. This article utilizes Zen, which is one of the cleanest and most flexible around.

Different themes are implemented differently. Some themes use fixed layouts with tables (avoid these because web design should not rely on tables), while others use div tags and CSS (favor these as they are far more flexible and powerful)—you should play around with a variety of themes in order to familiarize yourself with a few different ways of creating a web page. As mentioned, we only have space to cover Zen here, but the lessons learned are easily transferred to other themes with a bit of time and practice.

Before we go ahead and look at an actual example, it is important to get an overview of how themes are put together in general.

Theme anatomy

Drupal themes consist of a set of files that define and control the features of Drupal's web pages (ranging from what functionality to include within a page to how individual page elements will be presented) using PHP, HTML, CSS, and images.

Different Drupal 7 template files control different regions of a page, as shown in the following diagram:

Looking at how theme files are set up within Drupal hints at the overall process and structure of that theme. Bear in mind that there are several ways to create a working theme, and not all themes make use of template files. However, in the case of the Drupal's default theme setup, we have the following:

The left-hand column shows the folders contained within the themes directory. There are a number of standard themes, accompanied by the engines folder that houses a phptemplate.engine file, to handle the integration of templates into Drupal's theming system.

Looking at the files present in the garland folder, notice that there are a number of PHP Template files suffixed by tpl.php. These files make use of HTML and PHP code to modify Drupal's appearance. The default versions of these files, which are the ones that would be used in the event a theme had not implemented on its own, can be found in the relevant modules directory. For example, the default comment.tpl.php file is found in modules | comment, and the default page.tpl.php file is located, along with others, in the modules | system folder.

Each template file focuses on its specific page element or page, with the noted exception of template.php that is used to override non-standard theme functions—that is, not block, box, comment, node, or page.

The themes folder also houses the stylesheets along with images, and in the case of the default theme, colors. Of special interest is the .info file that contains information about the theme to allow Drupal to find and set a host of different parameters.

A theme's .info file holds the basic information about a theme that Drupal needs to know, namely, its name, description, features, template regions, CSS files, and JavaScript.

Here's Garland's .info file:

; $Id: garland.info,v 1.9 2009/12/01 15:57:40 webchick Exp $
name = Garland
description = A multi-column theme which can be configured to modify
colors and switch between fixed and fluid width layouts.
package = Core
version = VERSION
core = 7.x
engine = phptemplate
stylesheets[all][] = style.css
stylesheets[print][] = print.css
settings[garland_width] = fluid

; Information added by drupal.org packaging script on 2010-05-23
version = "7.0-alpha5"
project = "drupal"
datestamp = "1274628610"

Note that this file holds, amongst other things:

  • Name—A human-readable theme name
  • Description—A description of the theme
  • Core—The major version of Drupal that the theme is compatible with
  • Stylesheets—Stipulate which stylesheets are to be used by the theme

These are not the only types of information that can be held by .info files. As we'll see a bit later on, when it's time to add scripts to a theme, they can be added to the .info file too.

To quickly see one way in which .info files can be put to work, look closely at the .info file in the update_test_subtheme theme folder in tests (Below garland):

; $Id: update_test_subtheme.info,v 1.1 2009/10/08 15:40:34 dries Exp $
name = Update test subtheme
description = Test theme which uses update_test_basetheme as the base
core = 7.x
engine = phptemplate
base theme = update_test_basetheme
hidden = TRUE

; Information added by drupal.org packaging script on 2010-05-23
version = "7.0-alpha5"
project = "drupal"
datestamp = "1274628610"

Notice that this contains a base theme directive that is used to specify the parent, or base, theme.

A sub-theme shares its parents' code, but modifies parts of it to produce a new look, new functionality, or both.

Drupal allows us to create new sub-themes by creating a new folder within the themes directory and specifying the base theme directive in the new theme's .info file—just as we saw in update_test_subtheme.

In a nutshell, Drupal provides a range of default themeable functions that expose Drupal's underlying data: such as content and information about that content. Themes can pick and choose which snippets of rendered content they want to override—the most popular method being through the use of PHP template files in conjunction with stylesheets and a .info file. Themes and sub-themes are easily created and modified, provided that you have some knowledge of CSS and HTML—PHP helps if you want to do something more complicated.

I should make it clear that this system makes building a new theme fairly easy, provided one knows a bit about PHP. Here's the process:

  • Create a new themes folder in the sites | all folder, and add your new theme folder in there—call it whatever you want (provided it is a unique name)
  • Copy the default template files (or files from any other theme you want to modify) across to the new theme directory, along with any other files that are applicable (such as CSS files)
  • Rewrite the .info file to reflect the attributes and requirements of the new theme, including specifying the base theme directive
  • Modify the layout (this is where your PHP and HTML skills come in handy) and add some flavor with your own stylesheet (included into the new theme through the .info file)

Before moving on, there's one small issue of practicality that must be addressed. When it is time for you to begin doing a bit of theme development, bear in mind that there are many types of browser and not all of them are created equal. What this means is that a page that is rendered nicely on one browser might look bad, or worse, not even function properly on another. For this reason, you should:

Test your site using several different browsers.

The Drupal help site has this to say about browsers:

It is recommended you use the Firefox browser with a developer toolbar and view the formatted sources' extensions.

I wholeheartedly agree. You can obtain a copy of the Firefox browser at www.mozilla.com/firefox. Firefox should also be extended with Firebug, which is an extremely useful tool for client-side web debugging: https://addons.mozilla.org/en-US/firefox/addon/1843/.

Choosing a base theme

As discussed, Drupal ships with a few default themes, and there are quite a few more available in the Downloads section of the Drupal site. Looking at how Drupal presents its core Themes page under Appearance in the toolbar menu, we can see the following:

Any new themes that are added to the site will be used to enable, disable, configure, or set as a default from this page.

Be aware that some themes might not implement functionality that is important to your site. Ensure that you test each theme thoroughly before allowing users to select it.

Enabling the Stark theme, and setting it as the default theme, causes the site, which has been presented in the standard Garland theme up until now, to look something like this:

This is a vast change from the previous look. Notice too that the entire layout of the site has changed—there are no well defined columns, no visually defined header section, and so on. In addition, the previous fonts and colors have also been demolished.

Take the time to view each theme that is available by default in order to get a feel for how different themes can produce wildly differing looks and layouts.

That is not the end of the story, because the Drupal site also has a whole bunch of themes for us to explore. So head on over to the themes page at http://drupal.org/project/themes and select the relevant version tab to bring up the themes that are available.

You have already seen how to download and install other modules, and the process for installing themes is no different—download and extract the contents of the desired theme to the themes folder in sites | default or sites | all. For example, the Zen theme was downloaded and extracted, and provides us with a new option in the list of themes (some downloads will provide a number of sub-themes too), as shown in the following screenshot:

Enable and set default causes the site to look like the next screenshot:

Notice that while the color scheme is effectively non-existent, the page has retained its overall structure in that it has defined sidebars, a header region, and a central content region. Before we begin customizing this, let's take a look at the configuration settings for this theme.

Read more about this book

(For more resources on Drupal, see here.)

Theme settings

Clicking on the Settings tab at the top of the Appearance overlay brings up the global theme options that will influence each theme, regardless of which one is being used. This is useful if you always want certain features enabled (it's also easy enough to navigate between global and theme-specific settings using the links given at the top of the page):

The Global settings page is fairly representative of all the theme configuration pages. Note that the settings made here can be overridden by the Settings of each specific theme.

Along with a selection of page elements to be hidden or displayed, each individual theme might provide a number of different options. In the case of the Garland theme, we are able to set the Color scheme and Content width options, as shown in the following screenshot:

Next, we can specify which page elements should or shouldn't be displayed in the TOGGLE DISPLAY section.

Then, we can either use the default logo supplied with the theme, or alternatively, specify a path to another logo or upload a new logo to the site, as shown below.

In the case of the demo site, we will be making use of a background image to display the logo and name, so this option can be unchecked. If you have a site logo, or plan to have one, then this is where you'll come (for whichever theme you are using—most likely a Zen sub-theme).

The final section deals with favicons (an icon that will be displayed in the site's address bar and in any bookmarks). Once again, what you use here is really up to you, but favicons can be a bit of a pain to create. Internet Explorer looks for icons in the ICO format, whereas Firefox will happily include .png files. There are a couple of online icon creation websites that can make or convert favicons—www.html-kit.com/favicon is one such example.

Customizing themes

Up until now, any settings or changes made have been fairly generic. Things are about to change as we begin to implement some more radical modifications that will require amendments to the stylesheet in order to get things just right. In the case of the demo site, I have chosen to work with the Zen theme, as it is clean and well designed and demonstrates the use of sub-themes really nicely.

If you haven't already, now is the time to find a fairly good code editor, as you will be looking at code files of one sort or another from here on out.


Zen is designed to work through sub-themes—we don't want to modify the base theme at all. This should make sense because we would have a hard time upgrading the theme if we spent all our time working on it directly. Follow this process to create your new Zen sub-theme:

  1. Copy the STARTERKIT folder to your themes directory and give it a name (lowercase, no special characters). For this example, I am using drupalbook.
  2. Open the new drupalbook sub-theme directory and rename STARTERKIT.info.txt to drupalbook.info. The .info file should always have the same name as its theme.
  3. Open the drupalbook.info file and change the name and description fields to something more suitable such as:

    name = drupalbook
    description = This is the Drupal 7 book's Zen subtheme.

  4. Edit template.php and theme-settings.php by doing a search for all occurrences of STARTERKIT and replacing it with the name of the sub-theme—drupalbook. Save the changes.

That's it. You can now access and use this new sub-theme just like any other theme on the Drupal site. Go to the Appearance overlay:

and enable and set this new sub-theme as the default. Note that the name and description information that we supplied to the drupalbook.info file is displayed with the theme. Once this is done, you should notice that your site looks exactly the same as it did when we enabled the Zen theme itself. That's because they are exactly the same.

The Zen theme is a starting point from which we can create any type of look we want through sub-themes.

If you have any trouble, refer to the README.txt file that comes in the STARTERKIT folder within the Zen theme.

Working with the Sub-theme

Now that we have a fully operational drupalbook theme, it's time to start making changes. You are completely free to change anything you want in any way you can imagine—there are literally limitless possibilities. The important thing to know is how everything is organized within this theme so that you understand where changes need to be made in order to achieve your theming requirements.

The drupalbook sub-theme has the following structure:

By and large, the vast majority of changes you will implement will be carried out in the CSS files contained in the css folder. We've already had a brief overview of how CSS works, and looking at the contents of the css folder, we can see that each CSS file pertains to specific elements of the page:

This is fantastic, because it means that everything is really logically and intuitively organized and this will save you a lot of time. In lesser themes, combing through large CSS files or trying to locate the correct files to modify can be an ever present source of irritation.

Open the blocks.css file for editing and modify the following:

.block /* Block wrapper */ {
margin-bottom: 1em;

By adding a background attribute, as shown here:

.block /* Block wrapper */ {
margin-bottom: 1em;
background: #C00000;

Save the changes, and refresh your browser. You should now see that all the block regions on the site have a healthy red glow about them:

All the block settings you could want to make, are sitting in the blocks.css file. Note that, by default, the CSS declarations are mostly empty, which is why the site currently looks so plain. Your job is to make changes to the regions and classes in order to get things looking the way you want them to.

In the same way, you can work on styling pages, nodes, comments, and forms and anything else you can think of—it's all there, nicely organized, and waiting for you. It might seem like a huge amount of work, but you'll be surprised by how much you can get done in a relatively short amount of time. For example, adding a nice background image to the body tag and setting the fonts goes a long way in giving the site an identity and that's only two small changes.

Moving down the list, the next folder, images, houses any and all images that you use as part of your theme. Save them here and reference them from your CSS files—nothing too complicated, and we have already discussed images earlier in this article.

The js directory holds any additional script files that you might need in order for your site to function.

Finally, the templates folder holds any and all template files that we wish to override ourselves. Even if you are not familiar with PHP, Drupal's modular design and template system makes it really easy to fiddle around with the internals of Drupal. Let's take a look at the process of overriding a template file.

Zen gives us a head start in the form of the README.txt file that is included in the templates directory. Here's a snippet:


Drupal 6 contains the following template files which you can override
and modify by copying them to your sub-theme. The Zen theme overrides
a handful of Drupal's templates. In order to override those templates,
you should copy them from the zen/templates folder to your sub-theme's
templates folder.

As always, when adding a new template file to your sub-theme, you will
need to rebuild the "theme registry"
in order for Drupal to see it.
For more info, see: http://drupal.org/node/173880#theme-registry

Located in zen/templates:

Located in /modules/aggregator:

Located in /modules/block:

This code directs us to the location of the template files that we can use to override specific aspects of the site. In particular, notice that I have highlighted the Zen template files in the previous snippet that are available for us to override. There is also a sentence in the comments that is very important:

When overriding a file, the theme registry has to be rebuilt before Drupal will pick up the changes.

Before we try overriding a template file, head over to the Settings page for drupalbook, and ensure that the Theme registry setting is checked:

This causes the theme registry to be rebuilt every time we refresh the page. It's great for development, but you must switch it off for production sites as it is very costly in terms of performance. With that setting saved, we can be sure that any changes we make to the template files will be picked up each time a new page is loaded.

To override a template file:

  1. Copy the default file to the templates
  2. directory in the sub-theme. For example, you might want to copy block.tpl.php from zen | templates to drupalbook | templates.
  3. Open the file for editing, implement and save the changes.
  4. Refresh your browser page to view the results.

By way of example, I made a trivial, but visible, change to the block.tpl.php file saved to the sub-theme's templates folder:

<div class="content"<?php print $content_attributes; ?>>
print 'you can see this change in every block in the drupalbook

print $content;

While this is not a particularly useful change—it does serve to demonstrate the fact that changes to this template file do affect the way in which the theme displays the relevant element on the site, as evidenced by refreshing the page:

As expected, each block now displays the additional message before it prints out the block content. While this example is fairly trivial, users who have experience with Drupal can make more complex and fundamental changes by accessing the underlying PHP data. Each template file helps developers out in this regard by telling them what is and isn't available in the comments at the top of each template page.

Knowing how to combine CSS with PHP and HTML templating puts you in complete control over the look and feel of your website. You can use any combination of CSS, HTML, JavaScript, or PHP to implement any and all changes you like.


In this article we took a look at the theme anatomy, how to choose a base theme, how to apply theme settings and customizing themes.

One of the most important aspects of customizing a site's look is understanding how Drupal is set up, in order to leverage the power of themes. As we saw, themes provide a kind of template from which you can work to create your own unique site. This saves a lot of time and effort because we no longer need to work from scratch.

Further resources on this subject:

You've been reading an excerpt of:

Drupal 7

Explore Title