How to Make a Drupal Theme

Making a custom Drupal theme is actually quite easy. A Drupal theme is just a few PHP files and a CSS file. I prefer the PHPtemplate theme engine (the default one) but you have several choices. See the bottom of this post for a link to the official Drupal Theme Developer's Guide which has information on other Drupal template engines.

The following information was originally written for Drupal 4.7, but the concepts also work for Drupal 5 and 6 too.

Navigate to your /themes directory. You should have a theme there called /bluemarine. We will use that as an example.

NOTE: before you edit any files you will copy the theme to another directory and rename it. Your custom themes go in the directory /sites/all/themes/. Details about that come later in this tutorial.

Here is a list of the files in the Bluemarine Drupal template:

Bluemarine Drupal tempate directory

The Files of a Drupal Template

page.tpl.php — The main template that defines the content on most of the page.
style.css — The CSS file that sets the CSS rules for the template.
node.tpl.php — This file defines the content of the nodes.
block.tpl.php — Defines the content of the blocks.
comment.tpl.php — Defines the content of the comments.
logo.png — Your logo, if you are using one.
screenshot.png — This is a screenshot of your theme that is used in the admin panel and in the user account settings if you have enabled more than one theme so that visitors can choose which theme they want to use.
box.tpl.php — puts a box around things like comments. See also http://drupal.org/node/11814.

page.tpl.php and style.css

The page.tpl.php and style.css files are the main files for your Drupal theme. The page.tpl.php is a mix of HTML and PHP. Look at the file and notice which snippets of PHP are used where. For example, the following snippet from the page.tpl.php file inserts the site's <head> information. Just copy that snippet into your own custom Drupal template.

<head>
  <title><?php print $head_title ?></title>
  <?php print $head ?>
  <?php print $styles ?>
  <?php print $scripts ?>
  <script type="text/javascript"><?php /* Needed to avoid Flash of Unstyle Content in IE */ ?> </script>
</head>

The following code from the Bluemarine page.tpl.php file use PHP if statements to print out optional information such as primary links, secondary links, and site slogan. You control whether those display in the Drupal control panel. The Bluemarine template uses tables, but you can easily remove the tables and make it a 100% CSS-based template.

<table border="0" cellpadding="0" cellspacing="0" id="header">
  <tr>
    <td id="logo">
      <?php if ($logo) { ?><a href="<?php print $base_path ?>" title="<?php print t('Home') ?>">
<img src="<?php print $logo ?>" alt="<?php print t('Home') ?>" /></a><?php } ?>
      <?php if ($site_name) { ?>
<h1 class='site-name'><a href="<?php print $base_path ?>" 
title="<?php print t('Home') ?>"><?php print $site_name ?></a></h1><?php } ?>
      <?php if ($site_slogan) { ?><div class='site-slogan'><?php print $site_slogan ?></div><?php } ?>
    </td>
    <td id="menu">
      <?php if (isset($secondary_links)) { ?>
<div id="secondary"><?php print theme('links', $secondary_links) ?></div><?php } ?>
      <?php if (isset($primary_links)) { ?>
<div id="primary"><?php print theme('links', $primary_links) ?></div><?php } ?>
      <?php print $search_box ?>
    </td>
  </tr>
  <tr>
    <td colspan="2"><div><?php print $header ?></div></td>
  </tr>
</table>

The Drupal styles.css File

The style.css file is straightforward. I recommend the Firefox Web Developer Toolbar for creating the style.css file. Use the toolbars option Display ID & Class Details in the Information menu to view the CSS classes and ID's that Drupal is generating. Then add your own CSS rules to the style.css file.

Other Drupal Theme Files

Other files in the Drupal theme are block.tpl.php, box.tpl.php, comment.tpl.php, and node.tpl.php. Each one controls the layout of certain parts of the template. The comment.tpl.php defines the comment layout as shown below. It is fairly straightforward PHP: "If there is a user picture, print the user picture, etc.

  <div class="comment<?php if ($comment->status == COMMENT_NOT_PUBLISHED) print ' comment-unpublished'; ?>">
    <?php if ($picture) {
    print $picture;
  } ?>
<h3 class="title"><?php print $title; ?></h3>
<?php if ($new != '') { ?><span class="new"><?php print $new; ?></span><?php } ?>
    <div class="submitted"><?php print $submitted; ?></div>
    <div class="content"><?php print $content; ?></div>
    <div class="links">&raquo; <?php print $links; ?></div>
  </div>

Your First Custom Drupal Theme

Just make a copy of the default Bluemarine template and put it in your Drupal /sites/all/themes/ directory. That directory doesn't exist by default, so you should create it if you haven't already. See the README file in /sites/all/ for more information. Rename the copy of Bluemarine to the name of your new theme. Enable the new theme.

Then strip most of the HTML out of the page.tpl.php file and replace it with the HTML that you would like for your theme. Leave the PHP, modifying it as desired. If you are using Linux for Web development, you can use Quanta Plus as an editor to edit your template files directly on the server. Each time you save the file in Quanta Plus, the remote copy of the file will be updated.

Use the Firefox Web Developer Toolbar's Display ID & Class Details feature to view CSS information on your new template that you are viewing the the browser. Either start a new style.css file from scratch, or modify the existing one to get the template the way you would like. To edit the display of blocks, nodes, and comments, edit the block.tpl.php, node.tpl.php, and comment.tpl.php files respectively.

When you are finished with your template, take a screenshot and resize it to about 150x90 pixels. Upload it to your theme directory as screenshot.png.

Drupal Template Variables

The PHP snippets in the examples above are just printing PHPtemplate variables. A complete list of available PHPtemplate variables that you can use in your template can be found on Drupal.org's PHPtemplate variables page. Below are the available variables from 24 July 2007:

$breadcrumb: HTML for displaying the breadcrumbs at the top of the page.
$closure: Needs to be displayed at the bottom of the page, for any dynamic javascript that needs to be called once the page has already been displayed.
$content: The HTML content generated by Drupal to be displayed.
$directory: The directory the theme is located in , e.g.; themes/box_grey or themes/box_grey/box_cleanslate.
$footer_message: The footer message as defined in the admin settings.
$head: HTML as generated by drupal_get_html_head().
$head_title: The text to be displayed in the page title.
$help: Dynamic help text, mostly for admin pages.
$is_front: True if the front page is currently being displayed. Used to toggle the mission.
$language: The language the site is being displayed in.
$layout: This setting allows you to style different types of layout ('none', 'left', 'right' or 'both') differently, depending on how many sidebars are enabled.
$logo: The path to the logo image, as defined in theme configuration.
$messages: HTML for status and error messages, to be displayed at the top of the page.
$mission: The text of the site mission.
$node: (5.x and after only)If you are in page.tpl.php displaying a node in full page view then $node is available to your template.
$onload_attribute: (4.7 and older only) Onload tags to be added to the head tag, to allow for autoexecution of attached scripts.
$primary_links (array): An array containing the links as they have been defined in the phptemplate specific configuration block.
$scripts: (5.x and after only) HTML to load the JavaScript files and make the JS settings available. Previously, javascript files are hardcoded into the page.tpl.php
$search_box: True(1) if the search box has been enabled.
$search_button_text: (4.7 and older only)Translated text on the search button.
$search_description: (4.7 and older only)Translated description for the search button.
$search_url: (4.7 and older only)URL the search form is submitted to.
$secondary_links (array): An array containing the links as they have been defined in the phptemplate specific configuration block.
$sidebar_left: The HTML for the left sidebar.
$sidebar_right: The HTML for the right sidebar.
$site: The name of the site, always filled in.
$site_name: The site name of the site, to be used in the header, empty when display has been disabled.
$site_slogan: The slogan of the site, empty when display has been disabled.
$styles: Required for stylesheet switching to work. This prints out the style tags required.
$tabs: HTML for displaying tabs at the top of the page.
$title: Title, different from head_title, as this is just the node title most of the time.

There are also other variables available for your Drupal theme. A good list can be found in Chapter 8 of the essential book Pro Drupal Development. I believe that Chapter 8 is a free sample download.

Also check out these two books from Packt Publishing: Drupal 5 Theming and Building powerful and robust websites with Drupal 6.

How to Make a Custom Front Page in Drupal

There are several ways to set a custom front page in Drupal. Four of them are described here.

Custom Front Page with a Node

In Drupal 5 you can set a custom front page on your Site Information page found at http://example.com/admin/settings/site-information. At the bottom of that page you will see the following option:

Setting a custom front page on Drupal's Site Information Page.

To make a custom front page, just create a new node and then enter the path to that new node in the "Default front page" settings.

For example, if you build a front page on a node at http://example.com/new-front-page, then just enter new-front-page into the "Default front page" settings.

The main SEO issue to be aware of when doing this is that it creates a duplicate front page URL: http://example.com/new-front-page will show the same content as http://example.com/. Possible fixes for that problem are either to:

Block off the duplicate URL with robots.txt, e.g., Disallow: /new-front-page$
or install the Global Redirect Module which will automatically 301 redirect your front page node to the actual front page (http://example.com/).

Custom Front Page with the Front Module

For more control over your front page, for example to completely override your theme, you could install the Front Page Module. The Front Page Module allows you to set different front pages by user role, as well as include PHP snippets in the front page.

Use of the module is straightforward and is basically self-documenting. A screenshot of the Advanced Front Page Settings from the Front Module is shown below:

Drupal Front Page Module settings

If you use Drupal's Front Page Module, it will create a duplicate front page located at http://example.com/front_page. To address this issue from an SEO standpoint, add the following line to your robots.txt file:

Disallow: /front_page

Custom Front Page with the Views Module

If you have the Views Module installed, it will create a front page view located at http://example.com/frontpage. You can control the settings for that page at http://example.com/admin/build/views.

Drupal Views, custom front page

To edit the View for this type of custom front page, go to http://example.com/frontpage and click on the "Override" tab. Then create a Drupal View just as you would create any other Drupal View.

If you have the Views Module installed, be sure to block off that duplicate front page with the following robots.txt rule:

Disallow: /frontpage$

Custom Front Page with Drupal Theming

To create a custom front page in Drupal through your theme, just create a file in your theme directory called page-front.tpl.php and add the code for your front page there. Whatever you put in that file will be the front page of your Drupal site.

CSS Poster and Drupal Template Customization

CSS Poster is a free online tool from chami.com. Just upload a CSS file, and CSS Poster will make a chart based on your CSS file.

Here is a cropped example using Drupal's Bluemarine template's CSS file:

CSS Poster used to display Drupal's Bluemarine Template CSS

A potential use for CSS Poster that immediately comes to mind is using it as a reference when customizing Drupal themes, or any kind of CSS file that was created by someone else.

Drupal Theming Tutorials

I've found some great Drupal templating tutorials online.

NickLewis.org has a series about Extreme Drupal Theming with PHPtemplate. Here is one tutorial from that series on how to customize the login form.

Bryght.com has a great introduction to converting a CSS/HTML design to a Drupal theme. Bryght.com also has an interesting tutorial on how to create a contact form in Drupal with the survey module. The survey module can be found here. I haven't tried that method of creating contact forms, but it looks interesting.

The drupal.org phptemplate docs are also very good. The PHPTemplate Theme Snippets section has useful Drupal template recipes.