Last updated September 16, 2011. Created by Steven on January 26, 2004.
Edited by xenophyle, abraham, bekasu, puregin. Log in to edit this page.

Note: this page describes Drupal's theming from the code side of things.

Drupal's theme system is very powerful. You can accommodate rather major changes in overall appearance and significant structural changes. Moreover, you control all aspects of your drupal site in terms of colors, mark-up, layout and even the position of most blocks (or boxes). You can leave blocks out, move them from right to left, up and down until it fits your needs.

At the basis of this are Drupal's theme functions. Each theme function takes a particular piece of data and outputs it as HTML. The default theme functions are all named theme_something() or theme_module_something(), thus allowing any module to add themeable parts to the default set provided by Drupal. Some of the basic theme functions include: theme_error() and theme_table() which as their name suggest return HTML code for an error message and a table respectively. Theme functions defined by modules include theme_forum_display() and theme_node_list().

Custom themes can implement their own version of these theme functions by defining mytheme_something() (if the theme is named mytheme). For example, functions named: mytheme_error(), mytheme_table(), mytheme_forum_display(), mytheme_node_list(), etc. corresponding to the default theme functions described above.

Drupal invokes these functions indirectly using the theme() function. For example:

<?php
$node
= node_load(array('nid' => $nid));
$output .= theme("node", $node);
?>

By default, this will call theme_node($node). However, if the currently active theme is "mytheme", and this theme has defined a function mytheme_node(), then mytheme_node($node) will be invoked instead.

This simple and straight-forward approach has proven to be both flexible and fast.

However, because direct PHP theming is not ideal for everyone, we have implemented mechanisms on top of this: so-called template engines can act as intermediaries between Drupal and the template/theme. The template engine will override the theme_functions() and stick the appropriate content into user defined (X)HTML templates.
This way, no PHP knowledge is required and a lot of the complexity is hidden away. More information about this can be found in the Theme developer's guide, specifically the Theming overview.

More complete and up-to-date docs

If you are looking for documentation on how to write a themable module, have a look at following article from the developers guide: http://drupal.org/node/165706

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.