Drupal theme hacking - the basics

So you have this Drupal theme project you're working on, and you wonder where to start. This blog post tries to assist you in this endeavor. It assumes you're working with the default template engine: PHPTemplate.

First, let's zoom into how Drupal processes a theme. Most theme related information is stored in files in the theme directory. Usually, the my_theme theme files will reside in sites/all/themes/my_theme. An overview of typical files you will encounter in the theme directory:

• my_theme.info contains basic information about your theme: the name of your theme, version information, the parent theme if applicable, custom CSS and JavaScript files, theme engine (phptemplate), regions that your theme offers, a screenshot, custom logo, favicon… The format of this file is “key = value” lines, no PHP.
• template.php contains theme-specific PHP code snippets that override or extend basic functionality offered by Drupal core and contributed modules. This is where you can enrich the features of your theme, or rewrite things so they better suit your needs (e.g., render taxonomy terms differently).
• theme-settings.php provides the configuration for your theme. This file can be rather overwhelming, due to the very verbose form description that is embedded in it. This form describes the user interface by hiding most of the HTML to the programmer. It also defines the theme-specific configuration parameters and their default values.
• Various .tpl.php files define the structure and layout of your content, sometimes even at the level of a single field. These files consist of HTML snippets and PHP code snippets that are needed to correctly lay out the data at the right place, in the right format. Typically a lot of classes are assigned to HTML entities (e.g., <div id="page" class="<?php print $page_class ?>">), which moves styling to the cascading stylesheets (CSS files).
  • page.tpl.php defines the basic page template for your theme. It is a HTML page skeleton with PHP directives that tell which content goes where (regions) on a page. For a region named 'footer' the PHP code snippets you will see, are like:
    <?php if ($footer): ?>
<div class="footer"><?php print $footer; ?></div>
<?php endif; ?>
  • node.tpl.php defines the basic node template for your theme. It is a HTML fragment skeleton (that will be pasted somewhere in a page or in other places) with PHP directives that tell which node data goes where.
  • Specific node types can also have their own template: for example my_content can have a template with the name my_content.tpl.php; it obeys the same logic as node.tpl.php. When you create a new content type but don't provide a custom template file for it in your theme, then it will be rendered like in node.tpl.php.
  • Similarly the layout of a generic block is described in a file named block.tpl.php.

The basic principle of Drupal theme processing is simple:

• When enabling a theme, Drupal will process the ‘.info’ file to understand what the theme offers in terms of artifacts (regions, stylesheets…). Next, Drupal will read the content of the theme directory and look for template files (ending in ‘.tpl.php’), parse and cache them for speedy operation afterwards. This entire process is also called theme registration.
• If your theme builds on top of a parent theme, then first the parent theme is read, and after this the overrides of your derived theme are applied.
• When a page is built, the code in template.php is executed, then the page template (page.tpl.php) is parsed, and the content is gradually written in the template: page title, blocks with menus, node lists, you name it.
• When you want to configure your theme via the Drupal administration interface (admin/build/themes/settings/my_theme), nothing will happen. Unless you have written it in theme-settings.php.
• When you have written your settings interface (in theme-settings.php), still nothing will happen, unless you use the settings in your template files. A good place for this is in template.php.

The Drupal theme registry process is a very powerful feature. It optimizes the time needed to render content on your website by preprocessing and caching most of the template. However, when developing and tweaking your Drupal theme, you don't want Drupal to serve your browser a cached version of a stale theme since you're editing it. To disable this automatic caching, there are 2 options:

1. Force Drupal to rebuild its theme registry upon every page load by adding drupal_rebuild_theme_registry() to template.php. This is no longer the preferred way:
2. Install the devel module, and then enable the devel block (admin/build/block). On the devel block, click ‘Devel settings’ (admin/settings/devel) and tick ‘Rebuild the theme registry on every page load’. Save and you're done.

Please note that enabling this feature is a very expensive operation. Hence it should never be enabled on a live server. Don't forget to disable this setting afterwards!

In another post we'll dig a little deeper