A Guide to Drupal eCommerce and Site Development

A Theme is Drupal’s name for the collection of PHP, CSS, templates, images, and related files that collectively drive the logic for rendering a Drupal web page. Creating a theme is a large and complex topic. However, creating and modifying a sub-theme is ridiculously simple. In this sub-tutorial I will show you step by step how to create a sub-theme, install it, and activate it.

Let’s begin with a simple situation to get our feet wet: this web site. Www.MissingUbercartManual.com is a minimal modification of the standard Garland theme that comes with a standard Drupal install. I wanted a web site theme that said “Drupal”, and most people familiar with Drupal recognize the Garland theme. However, I wanted to have crisper text, and a few other minor changes.

Using one of the standard themes presents a special situation for the frowned upon practice of going into a theme’s files and making changes. Why is that frowned upon? Because themes (and modules as well) are open source projects that are evolving, they are receiving bug, security, and feature enhancements. If you go into the files and make changes, you cannot easily get a newer release. If you did, you would loose your customizations when copying the newer files over the ones you modified. You could hand merge your changes into the new version, but now you are just making work for yourself.

I mentioned that using one of the standard themes is a special situation… Well designed themes provide a “local.css” file for CSS customizations. When making CSS changes, put them in the “local.css” file, and they will override the CSS of the theme. However, the standard pre-installed themes do not provide a “local.css” file for you to use. Plus, using “local.css” is really not that much different from changing the theme’s files directly. However, such considerations do not matter, because we can just sub-theme to get the same result.

Step One: Creating your Sub-Theme Directories
First a little bit of information about where to locate your sub-theme directory. There are two situations that may determine where you put your sub-theme directory. The most common situation is when your Drupal installation is hosting a single web site. If this is your situation, place your sub-theme directory inside the “site/all/themes” directory like this:

sites/
    all/
        modules/
        themes/
            your-sub-theme-directory/

It is also possible to have a single Drupal installation host more than one web site. In that situation, your Drupal sites directory structure may look similar to this:

sites/
    all/
        modules/
        themes/
    default/
        files/
        modules/
        themes/
    www.secondSite.com/
        files/
        modules/
        themes/
    www.thirdSite.com/
        files/
        modules/
        themes/

In a multiple site installation, seeing all these directories may confuse you. In such a situation, the modules and themes inside the “all” directory are available for all the web sites to use. This is where you put modules and themes common to all the web sites run by that Drupal installation. Inside the “default” directory you may also find a “modules” and “themes” directory – those modules and themes are only available to the default web site hosted by this installation. Likewise, the www.secondSite.com directory could have “modules” and “themes” directories as well, and those are only available to the www.secondSite.com web site.

You should be starting to see how the modules and themes directories work in Drupal. When you visit the admin/build/themes page of your Drupal site, you are given a list of available themes for use on your site. In order to build this list, first all the standard modules and themes from the html root directory of your site are loaded. Next, all the modules and themes from the sites/all directory are loaded. Finally, all the modules and themes from your specific site are loaded. If Drupal does not find a “modules” or “themes” directory in one of these places inside your “sites” directory, no big deal, that simply means there are no additional modules or themes to be loaded from that location - you still have the standard “modules” and “themes” that came with your Drupal installation in the modules and themes subdirectories of your html root.

If you want to make your sub-theme available to all the web sites, make your sub-theme directory inside “sites/all/themes”. If you want your sub-theme to only be available to one of the sites, make your sub-theme directory inside the “themes” directory of that site. If you only have one web site within your Drupal installation, that directory is named “default”. If you have more than one web site within your Drupal installation, put your “themes” directory inside the directory of the site that is going to use the sub-theme.

What to name your sub-theme directory? It needs to have the same name as your sub-theme, and that name needs to be unique between all the themes available in your Drupal installation. Additionally, this name is going to be used within Drupal’s internal logic as a variable, so it needs to conform to the rules of a valid PHP variable: it needs to begin with an underscore or a letter, followed by any number of letters, numbers and underscores. No other characters are allowed.

In my situation for this web site, I wanted to create a variation of Garland, so I named my sub-theme “GarlandSub”. Also, because this web site actually hosts two web sites – this one and my online resume site at www.BlakeSenftner.com, my directory structure looks like this:

sites/
    all/
    default/
    www.missingubercartmanual.com/
        files/
        modules/
        themes/
            GarlandSub/

At this time, go ahead and make your sub-theme’s directory.

Step Two: Creating your Sub-Theme Files
Inside your sub-theme’s directory, you need to create at least two more files. The first file is your sub-theme’s “.info” file. It needs to have the same name as your sub-theme directory and end with a “.info” extension. The second essential file is a CSS file where you will put your overriding font, color, layout and image specifications. You can name this file anything you want, but I prefer to reuse your sub-theme’s directory name, ending with a “.css” extension.

The additional files you may need will be copies of certain files from your base theme, depending upon a few factors I’ll outline below.

Now open up your sub-theme’s “.info” file with a text editor. We’re going to build your sub-theme’s “.info” file in steps, so begin by copying the following into your sub-theme’s empty “.info” file, making changes where I’ve placed italics:

name = your_sub-theme_name
description = anything you want, shown on theme selection page
core = 6.x base theme = your_base_theme_name
stylesheets[all][] = your_sub-theme_name.css

About the name declaration: that is the theme’s “human name” as displayed to the user on pages referencing your sub-theme by name. This name is not used as a variable by Drupal’s internals, and can contain spaces and punctuation.

Make sure the line defining your base theme is the directory name of the theme, and not its human name.

You could define more than one style sheet, and they can additionally define styles for different media properties. But that is beyond the scope of this sub-tutorial. For the interested, you can visit here.

The next step requires some knowledge of how the base theme is structured, so now you need to open your base theme’s “.info” file. (Keep your sub-theme’s “.info” file open as well.)

Note that you need to have your base theme installed and enabled as one of the available themes in your Drupal installation. That is how Drupal is able to get all the logic of your base theme for your sub-theme. If your base theme is not one pre-installed, you’ll need to add it to your Drupal installation. Also note that do not really need to have the base theme enabled for a sub-theme to work, but it is a good for two reasons: 1) you’ll need to have the base theme enabled for part of this sub-tutorial; 2) depending upon your version of Drupal, if a base theme is not enabled and that base theme receives a security update, you will not be notified by Drupal’s automated update system. I’ve seen reference that this type of thing is fixed in Drupal 7. Until I learn otherwise for Drupal 6, I recommend enabling your base theme.

Looking at the base theme’s “.info” file, do you see any lines that look like this?

regions[sidebar_first] = sidebar first

Specifically, do you see any lines that begin with the word “regions”? If so, copy them from the base theme’s “.info” file to your sub-theme’s “.info” file. These are defining a set number of regions the theme supports. Your sub-theme needs to define them too, if you want your sub-theme to support those same regions. If you only want some of the regions, only copy across the ones you want. You can also define additional regions and change/modify the existing regions of your base theme, but that is beyond the scope of this tutorial.

If you do not see any region definitions then you have this set by default:

regions[left] = Left sidebar
regions[right] = Right sidebar
regions[content] = Content
regions[header] = Header
regions[footer] = Footer

If you want to continue to have these regions, do nothing and you’ll still have this set by default. If you want fewer regions, just define the ones you want. If you want other regions, implementing them is beyond the scope of this sub-tutorial.

Next, go back to looking at the base theme’s “.info” file and look to see if there are any lines like this:

features[] = logo

Lines that begin with the word “features” are defining the availability of checkboxes to turn off/on the named theme feature. Here are all the possible theme features:

features[] = logo
features[] = name
features[] = slogan
features[] = mission
features[] = node_user_picture
features[] = comment_user_picture
features[] = search
features[] = favicon
features[] = primary_links
features[] = secondary_links

If you do not see any lines defining theme features, then all of them are activated by default. Since we’re creating a sub-theme, you have a few choices:

Your base theme has theme feature definitions:

1. Do not copy any theme feature definitions to your sub-theme’s “.info” file and you will inherit all the theme features defined by the base theme;
2. Copy only those theme feature definitions you want in your sub-theme, and the ones you did not include from your base theme will be deactivated.

Your base theme has no theme feature definitions:

1. Do not create any theme feature definitions, and your sub-theme will continue to support all them by default;
2. Create theme feature definitions, and your sub-theme will only support the ones you specify.

When a feature is activated, checkboxes appear to the user to turn the feature off/on in the sub-theme’s configuration screen, as well as the appropriate widget to specify the text or image associated with that theme feature.

You can now save your sub-theme’s “.info” file. Almost done…

Our next step depends upon your base theme supporting the color module’s interface for changing the colors used by the theme.

The Color Module's interface for changing the color scheme of a theme

If you do not see the above at admin/build/themes/settings/your-base-theme, then your base theme does not support the color module. You can skip down two paragraphs where I say "The final step..."

If you do see the above widget at admin/build/themes/settings/your-base-theme, and you want to support the same in your sub-theme, you need to copy the following from the base directory to your sub-theme directory:

• The color directory
• The image directory
• The style.css file

...And if you are doing this, when you copy the style.css file into your sub-theme directory, you also need to add a reference to it in your sub-theme.s ".info" file. When you add this line, it should appear above your sub-theme's CSS file, like this:

name = your_sub-theme_name
description = anything you want, shown on theme selection page
core = 6.x base theme = your_base_theme_name
stylesheets[all][] = style.css
stylesheets[all][] = your_sub-theme_name.css

Making modifications to color module support is beyond the scope of this sub-tutorial, but the above will give you the same behavior in your sub-theme as in your color-module-supporting base theme. Regardless of wanting to modify the color module's support to your su-theme, it is probably a good idea to read up on what it does so you at least have that understanding.

The final step is to navigate your browser over to admin/build/themes and take a look at the list of available themes. You should see yours! At this point you can enable it, and visit your own sub-theme’s configuration page. It will look and behave just like the base theme at this point. In the next sub-tutorial we’ll be digging into our sub-theme and bending it to our will. Note that readers working with themes supporting local changes will also be joining, so the discussion is a bit more general.