Theming overview

A few handbook pages has been moved to the new theming handbook. A fresh start for Drupal 6 and beyond. This handbook will eventually be part of a sub-section of the new outline after it has been cleansed out. The theme upgrade guide has been moved too.

Note: this page describes the theme system from a themer's perspective. If you are a module coder looking to make your module themable, you should read this page.

As of version 4.5, Drupal's theme system is very flexible. The new structure makes it easy to plug components together to form your theme: templating engines, templates, stylesheets and PHP.

As of Drupal 4.7 the default theme engine that is included with Drupal is PHPTemplate.

Here's how some existing themes are built:

A 'theme' is an abstract thing, which can be formed in several ways:

• Template file (.tpl.php, .xtmpl) for a templating engine (PHPTemplate, XTemplate): e.g. Garland, Bluemarine
• Style sheet for an existing template or theme: e.g. Minelli, Marvin
• PHP .theme file containing overrides for theme_functions: e.g. Chameleon

The directory structure for the example above looks like this:

Themes and templates are placed in their own subdirectory in the themes directory (sites/all/themes for contributed themes). The theme engines will scan every subdirectory for template files (.tpl.php, .xtmpl). If a style.css file is present, it will also be used.

You can also make CSS-only themes by making a subdirectory in any theme directory and placing a new style.css file in it. Drupal will combine the new stylesheet with the template it belongs in, and make it available as a new theme. This is how the Minelli and Marvin themes work.

Finally, if there is a screenshot.png file in the theme directory, Drupal will show it in the theme administration screen.

Creating custom themes

If you want to create a custom theme, you can either customize an existing theme or start from scratch.

To customize an existing theme, just copy it to a new directory in themes, and give it a unique name. Themes should not have a name that is the same as any of the default modules in Drupal or any custom modules you might have enabled or configured. Then modify the copy as much as you want. Depending on whether the theme is template or .theme-file based, you can use PHP or XHTML/CSS to modify it. As explained above, if you only want to alter the CSS of a theme, then just place a new style.css file in a subdirectory of the theme: it will appear as a new theme in Drupal.

If you want to start from scratch, there are several ways to go. If you're not a programmer, then the easiest solution is to use one of the template engines. By default, Drupal 4.6 and previous versions comes with the XTemplate theme engine, which requires you to create an (X)HTML skeleton with special markers. See the XTemplate documentation for more info. As of Drupal 4.7 PHPTemplate changes to the default theme engine and XTemplate becomes a contributed theme engine.

Drupal themes used to be coded directly in PHP. This method is still available, but is harder to use and maintain than template-based themes.