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:
template.phpcontains 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.phpprovides 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.
.tpl.phpfiles 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.phpdefines 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.phpdefines 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_contentcan 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
- Similarly the layout of a generic block is described in a file named
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.phpis 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
- 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
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:
- Force Drupal to rebuild its theme registry upon every page load by adding
template.php. This is no longer the preferred way:
- 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