Last updated July 30, 2013. Created by JohnAlbin on August 13, 2012.
Edited by gilonlineltd. Log in to edit this page.

A quick overview of drupal theming

The default HTML for all of Drupal's markup is specified by its modules. For example, the comment.module provides the default HTML markup and CSS styling that is wrapped around each comment. Fortunately, each piece of markup can optionally be overridden by the theme.

Drupal deals with each chunk of content using a "theme hook". The raw content is placed in PHP variables and passed through the theme hook, which can either be a template file (which you should already be familiary with) or a theme function. For example, the "comment" theme hook is implemented with a comment.tpl.php template file, but the "breadcrumb" theme hooks is implemented with a theme_breadcrumb() theme function. Regardless if the theme hook uses a template file or theme function, the template or function does the same kind of work; it takes the PHP variables passed to it and wraps the raw content with the desired HTML markup.

Most theme hooks are implemented with template files. Theme hooks that use theme functions do so for performance reasons - theme_field() is faster than a field.tpl.php - or for legacy reasons - theme_breadcrumb() has "been that way forever."

The variables used by theme functions or template files come from a handful of sources:

  • the contents of other theme hooks that have already been rendered into HTML. For example, the HTML from theme_breadcrumb() is put into the $breadcrumb variable of the page.tpl.php template file.
  • raw data provided directly by a module (often pulled from a database)
  • a "render element" provided directly by a module. A render element is a nested PHP array which contains both content and meta data with hints on how the content should be rendered. If a variable in a template file is a render element, it needs to be rendered with the render() function and then printed using:
    <?php print render($variable); ?>

About the templates and other PHP pages

The documentation pages below list the variables used in those template (.tpl.php files.) Your templates contain mostly HTML markup plus some light PHP code in order to place the content in the markup.

After you've perused the template files, the most important PHP file in your sub-theme is going to be the template.php file.

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