How to create a Drupal 6 theme from scratch

Drupal theming can seem complicated and overwhelming. Even basic starter themes are filled with confusing PHP and convoluted CSS. What's a designer to do? Never fear, there is a simple way to create your own theme from scratch. This article will demonstrate a step-by-step process for creating your own Drupal theme, including a .info file, page template, regions, and CSS.

This article will assume that you have a design created with an HTML template, CSS file(s), and images. It will also assume that you have some basic knowledge of Drupal setup and theming. 

As an example, we will be creating a theme for Chezbardon.com. This was an existing static site that we are converting to Drupal. This is a fairly basic, mostly static site. It will have a contact form and booking form (using the webform module), but no commenting or other interactivity (although we will be adding an online booking system once the site is up and running). 

Why create a theme from scratch?

Instructions for creating a Drupal theme usually tell you to start with an existing theme and customize it for your needs. The first problem with this is that existing themes are usually very generic. They often include options to have left or right columns (or both), lots of regions, and all the CSS that makes it work. This is fine if that's what you need, but it also results in very convoluted template files and CSS that can be difficult to understand. Much of the CSS may not actually be used on your site, but you can't remove it if you aren't sure where it might be in use. Customizing a theme like this for your own site can be frustrating.

The other problem with this is that it doesn't help you to understand how Drupal theming really works. Working from scratch will help you to gain a better understanding of the theming system.

You may believe – as I did – that creating a Drupal theme is so complicated that it would be too difficult to make one from scratch. This really isn't the case. Once you have your html template created, all you need to do is add in a few variables to make a Drupal page template. Add in a few other simple files you have a theme!

Creating your theme

1. Create the folder structure

First you need to create a folder for your new theme. This should go in sites/all/themes or sites/yoursite/themes depending on whether this theme should be available to all sites on your installation or just one site. Give the folder a unique name that describes your theme (no spaces).

I find that it’s also useful to include sub-folders for images and CSS files. This helps to keep things organized.

2. Create the .info file

In Drupal 6 and above, all themes have a .info file that provide some basic information about the theme. Some of this information is used on the administer themes page. This is a simple text file with a .info extension. The name you give this file will be used by Drupal internally (e.g. if you call the file yourtheme.info, the internal label will be "yourtheme").

Inside the .info file, we’ll need to enter information about our theme in key-value pairs. These include:

name - a human-readable name of your theme

description - a description of the theme

core - the version of Drupal this is designed for

engine - the templating engine your theme will use (probably phptemplate)

regions - the block regions available. The name of the region is included in square brackets (e.g. regions[right]). It is a good idea to use the standard Drupal names for sidebar ("left" and "right" in Drupal 6). This will enable Drupal to add classes to the $body_classes variable to indicate which sidebars are in use (no-sidebars, sidebar-right, sidebar-left).

features - theming options that should be available in the Drupal admin interface (e.g. option to specify a site name, mission statement, logo etc. that is pulled into the theme). If you want to clear all features, leave it blank.

stylesheets - your CSS files (Drupal 6 automatically looks for style.css; if that’s what your file is called you don’t need to specify it here). The media type is included in square brackets (e.g. stylesheets[all] or stylesheets[print])

scripts - any scripts required by your template (remember that Drupal comes with jQuery, so if you’re using that library you don't need to include it here)

The scripts and stylesheet values are relative to the theme directory (i.e. the /sites/yoursite/themes/yourtheme path is automatically included). If you want to specify a file outside this directory you need to enter the path relative to the theme directory. See the comments on the .info documentation page for instructions on including an external script. 

Our .info file looks like this:

name = Chez Bardon theme
description = Custom theme for Chezbardon.com
core = 6.x
engine = phptemplate

regions[right] = Right sidebar
regions[content] = Content
regions[footer] = Footer

stylesheets[all][] = css/basestyle.css
stylesheets[print][] = css/print.css
scripts[] = ../../../all/libraries/colorbox/colorbox/jquery.colorbox-min.js
scripts[] = colorbox.js

features[] = 

More information about .info options, including default values and some additional optional keys, is available at drupal.org.

3. Create the page.tpl.php file

Drupal themes are based on template files, defined with the extension .tpl.php. These files contain the html mark-up for your theme, as well as some variables that tell Drupal where to put things.

The most important of these is the page.tpl.php, which defines the overall page template. If you already have an HTML template created, you can rename your template file to page.tpl.php and work from there.

Reference: all variables available to page.tpl.php (take special note of the general utility variables at the top).

3.1 Set up the <head> section

In this section you'll need to insert some variables for stylesheets, scripts, your site title, and other head content. 

Replace your stylesheet references with the Drupal $styles variable:

  <?php print $styles ?>

This will pull in the stylesheets defined in your .info file, as well as some default stylesheets and additional .css files provided by certain modules (e.g. if you have Views enabled, it provides its own stylesheet which will be inserted by this variable).

Do the same for your scripts:

  <?php print $scripts ?>

Also add the general Drupal head variable, which will insert meta tags (including character set), RSS links, and various other tags that belong in the <head> section:

  <?php print $head; ?>

The final thing we need to do for the <head> section is put the site title defined in drupal into the <title> tag. For this we'll use the $head_title variable, which is a a modified version of the page title, for use in the <title> tag:

<title><?php print $head_title ?></title>

Now our <head> section looks like this:

<head>
  <title><?php print $head_title ?></title>
  <?php print $head; ?>
  <?php print $styles ?>
  <?php print $scripts ?>
 </head>

3.3 Create your regions

Now we need to create regions that will be available for Drupal to put blocks into. These regions are defined by variables, just as we’ve used for the stylesheet and site title in the <head>. However, there is a chance that these variables will be empty (e.g. if there are no blocks placed in a given region). You probably don't want anything to be printed if the regions are empty. These variables need to be surrounded by conditionals, checking to make sure they exist.

Any part of your page that you want to be editable in the Drupal interface (via Blocks) needs to become a region. In our sample site, this includes the right sidebar, a section below the content (content_bottom), and the footer. Don't forget that all of your regions need to be introduced in the .info file first.

The following code creates a conditional to check that the sidebar region has a value, then prints out the contents:

<?php if ($sidebar): ?>
  <?php print $sidebar; ?>
<?php endif; ?>

Repeat this code for each of your regions, replacing the $sidebar variable with the names of your regions.

3.2 Add variables for basic page elements

Your page needs content right? Now we need to add the variables for key page elements, including the content. As described on the Drupal documentation page, there are many variables available to page.tpl.php. What you include depends on what functionality you want your theme to have. If you look at the page.tpl.php file for one of the default themes you’ll notice many other variables, particularly in the content section. Do you want breadcrumbs? If so, put in the $breadcrumbs variable (this one will always have a value, so it doesn't need a conditional).

Some of the most common are:

$site_name

$logo

$search_box

$title

$content

$navigation (the Drupal admin menus and other links placed in this menu)

$primary_links

There are also some variables associated with Drupal administration:

$help

$tabs (menu used for edit/view admin menus, among other things; often used by modules and can be set up for views)

$messages

And some other useful  variables:

$base_path (the path to your site root)

$directory (the path to your theme)

$body_classes (a set of CSS classes for the <body> tag; should be placed inside the class attribute)

Finally, you need to finish off your page.tpl.php by adding the $closure variable, which completes the code created by any modules that have altered the page.

Download the Chez Bardon page.tpl.php file.

A note on primary and secondary links

Blocks for primary and secondary links are provided by default but they are available as variables. You could use either method for inserting the links into the template. If you want to be able to move them around later, they should be blocks. Otherwise they can be hard-coded into the template using variables.

Primary links are returned as an array. When you include this in your page template, you need to expand it by sending it through theme() which will expand the array:

<?php if ($primary_links): ?>
  <?php print theme('links', $primary_links); ?>
 <?php endif; ?>

4. Try it out!

Now that your page template is created, you can enable your theme and see how it works. Before you do this, specify one of the default themes in the Administration Theme settings. That way you can always get back to the admin panel if something is seriously wrong with your theme.

5. Fix your CSS

There are probably some things you’ll need to fix in your CSS to get things to display correctly. Here you can use Firebug to find out what classes and id’s Drupal has applied, and change your selectors accordingly. You may also want to create some new CSS rules for elements created by Drupal (e.g. tabs, navigation menu), particularly if you’re going to use your new theme as your administration theme.

6. Other template files

There are many other template files that you can customize if you don’t like the default output. To customize these, copy the default theme files from their respective modules to your theme and make changes. It can take a bit of detective work to figure out which module is writing some particular code!

Another option is to create your own template files, just as we did above with page.tpl.php. Check the template documentation pages for information on which variables are available.

Alternately, you can re-create the theme or preprocess functions in your template.php file. 

More about overriding defaults can be found in the Drupal theming guide. Just remember not to go overboard - these templates and/or the theming methods used in them could change in the next version and you don't want to give yourself more work than you have to.

7. Create your screenshot

In the Drupal admin interface a screenshot will appear next to your theme name. To make this image, simply create a screenshot of your finished site, resize and crop to 150x90, and place it in your theme directory. It should be named screenshot.png

Drupal does have some guidelines on creating a screenshot file, but these only need to be followed if you intend to contribute your theme to the Drupal theme repository.

What’s next?

This is just the tip of the iceburg as far as Drupal theming goes. There are many, many other things you can do with your theme. 

Discussion

To discuss, ask questions or comment on this article please see the Webmaster Forums discussion on How to create a Drupal 6 theme from scratch.

Resources

Megan McDermott's picture

About the Author

Megan is co-founder and editor of A Padded Cell and administrator at The Webmaster Forums. She has been designing websites since 1997, with expertise in design, information architecture, usability, HTML/CSS, Drupal theming, and more. She is available for short-term or ongoing freelance work in any of those areas. Read her web design blog at MeganMcDermott.com or check out her portfolio.