How to create a simple Drupal 7 theme from scratch
by Megan McDermott, 21 September 2011 – 11:30am
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, it is completely possible 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 some basic knowledge of Drupal setup, theming, and terminology. It will also assume that you know all the HTML and CSS you need to build your design. This article will only cover Drupal-specific coding techniques.
The previous version of this article can be found at How to create a Drupal 6 theme from scratch. As the title suggests, that article covers the same techniques for Drupal 6.
Why create a theme from scratch?
Instructions for creating a Drupal theme usually tell you to start with an existing theme or base 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 actually 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 build one on your own. As I hope you ll find in this tutorial, that really isn t the case.
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. A folder structure for a simple theme could look like this:
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, and it also determines which features are available in the theme settings.
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 machine name of the region is included in square brackets (e.g. regions[sidebar_first] ). This will be used to insert the region into your template files. The label you assign to it will be used in the admin interface when assigning blocks to your regions.
In Drupal 7 you must include the content region in addition to any custom regions you need for your theme. It is a good idea to use the standard Drupal names for sidebar regions ( sidebar_first and sidebar_second in Drupal 7). This will enable Drupal to add classes to the body tag to indicate which sidebars are in use (no-sidebars, sidebar-right, sidebar-left).
features – theme components that can be turned on or off in in the Drupal admin interface (e.g. option to specify a site name, mission statement, logo etc.). Only the features listed in your .info file will be available on the admin page and as variables in your page template (more on that later). If you want to clear all features, leave it blank. To include all features, omit the features item entirely.
Using custom theme settings (features)
Some of these elements specified in the features key may not be necessary for your theme. By default, blocks are available for the standard navigation menus (main menu and secondary menu). The theme will pick up the shortcut icon (favicon.ico) file in your theme directory. If you re like me, you may prefer to code your logo image in your page template rather than uploading one through the admin interface.
Specifying these options is only necessary if you want to:
- code the variables into your template file and/or
- allow users to turn them on or off in the theme admin settings
In the case of the logo and the shortcut icon, upload forms will be made available in the admin page, which is only useful if you want to be able to change them easily.
Some of these options make much more sense for themes that will be used by a variety of different sites (e.g. the default Bartik and Garland themes). For a custom theme for an individual site they may not be as useful.
stylesheets – your CSS files. The media type is included in the first set of square brackets (e.g. stylesheets[all] or stylesheets[print] )
scripts – any scripts required by your template (remember that Drupal comes with jQuery, so 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.
Here is a sample .info file:
description = Custom theme for my site
regions[sidebar_first] = Right sidebar
More information about .info options, including default values and some additional optional keys, is available at drupal.org.
3. Understanding Drupal template files
Drupal themes are based on template files, defined with the extension .tpl.php . These files contain the html for your theme, as well as some variables that tell Drupal where to put things.
If you want to create a very simple theme, you actually don t need to have any template files at all. Your theme could be just CSS. Drupal comes with default template files for all of the code it outputs. These defaults are included with the module that generates the content for a particular element. For example, the html mark-up for a node is included with the node module as node.tpl.php. The html code for a block is included with the block module in the block.tpl.php file.
You only need to create your own version of a template file if there is something you want to change from the defaults. Otherwise, Drupal will simply use the default file. It is never a good idea to make changes to the default ( core ) files in Drupal. Always use the proper method for overriding code in your theme.
To create your own version of a template file, copy the default version from the module folder that created it, and place it in your theme folder. Sometimes it could be difficult to determine which module created a particular piece of code. If you re really having trouble, try the theme developer module.
The most important template file, and the one you will most likely want to change, is the page.tpl.php. This template file contains the code for the body of the page. The default page.tpl.php file is contained in the system module. The default does contain a lot of extra options that you might not need, so for this tutorial, we will write our own page.tpl.php from scratch.
In Drupal 7 there is also an html.tpl.php template, which includes code for the overall structure of the document (the doctype, the head section, and opening and closing body and html tags). We won t look at this file because there s not very much to worry about there. As always, if you want to change something you can simply copy the default from the module that created it (in this case, the system module) to your theme folder.
3.1 Create the page.tpl.php
To begin building your theme files, start by creating a new, empty text file called page.tpl.php. In here will go all the code for the main body section of your theme. This file consists of three elements:
- The HTML mark-up for your theme (containing div s, and any other major structural elements)
- Region definitions
- Variables for other content items (e.g. title, navigation tabs)
Start by creating the basic HTML structure for your page. This would include any containing div s or sections you need to create your site. For our sample theme, we ll start with a very basic structure with header, content area, sidebar, and footer: