Read more about this book

(For more resources on Drupal, see here.)

Introduction

One of the more prevalent adages with respect to Drupal development and theming is:
Do not hack core!
Modules, themes, and other files which come with a stock Drupal installation should never be edited directly. In other words, we really should not need to modify anything outside the sites folder which is designed to contain all our changes and customizations. The reasoning behind this is that most, if not all, aspects of core are accessible and modifiable through a clean and non-invasive process using Drupal’s APIs. Therefore, hacking core modules and themes to get things done is almost always unnecessary and ill-advised.

Another reason why directly editing core modules and themes, or for that matter, even contributed modules and themes, is that whenever an upgrade of Drupal or said modules and themes takes place, we will very likely be overwriting the changes we have made, or at the very least, make the upgrade a trying exercise.

With respect to themes, let us take the example of a core theme such as Garland. As previously mentioned, it is a poor practice to edit the theme directly. The Drupal way is to extend the existing core theme using a sub-theme which, by default, is more or less an identical copy. This sub-theme can then be extended further and customized by overriding elements of the base theme,such as its stylesheets, template files, template variables, and so on.

In this article, we will look at the building blocks of a basic theme and then familiarize ourselves with the concept of the sub-theme and the various techniques available to extend, override and modify it according to our requirements.

Understanding the anatomy of a theme

Drupal themes can consist of a multitude of files each with its own purpose, format, and syntax. This recipe will introduce each of these types with an explanation of what they do.

Getting ready

It will be useful to navigate to the Garland folder at themes/garland to browse and view the files inside a typical, fully featured theme. Garland also uses the PHPTemplate theming engine which is the most commonly used and recommended engine across Drupal’s core and contributed themes.

How to do it…

The following table outlines the types of files typically found inside a theme’s folder and the naming conventions to be followed for some of them.

Type	Mandatory?	Description
mytheme.info	Yes	Configuration file which provides information to Drupal about a theme named mytheme.
page.tpl.php	Yes	A template file which determines the layout of all Drupal pages.
node.tpl.php	No	A template file which determines the layout of a node inside a Drupal page.
block.tpl.php	No	A template file which determines the layout of a block.
*.tpl.php	No	Other template files which allow the customization and styling of themable aspects of Drupal.
style.css	No	CSS stylesheet-if this file exists, it will be automatically included in the theme.
script.js	No	Javascript file-if this file exists, it will be automatically included in the theme.
*.js	No	Other Javascript files which will need to be explicitly included in the .info file.
favicon.ico	No	Shortcut icon-if this file exists, it will be automatically included in the theme unless overridden from within Drupal.
logo.png	No	Site logo-if this file exists, it will be automatically included in the theme unless overridden from within Drupal.
screenshot.png	No	Theme preview image-if this file exists, it will be automatically included in the theme.
template.php	No	PHPTemplate master file where some of the more complicated and powerful tweaks and overrides occur.

Perusing the contents of each of the available files will prove very useful as we go along developing our theme.

How it works…

When a theme is added, Drupal first parses its .info file. This file, as its extension suggests, provides information about the theme such as its name, Drupal version compatibility, regions declared, CSS stylesheets used, JavaScript files included, and so on. In other words, Drupal uses it to find out the configuration and features of a theme.

The .info file also specifies the theming engine being used by the theme which, by default, is PHPTemplate. Theme engines allow theme developers to communicate with Drupal using a simpler and more convenient interface commonly via template files. A number of them also introduce their own language formats for use in these template files.

Template files in PHPTemplate themes are those that use the .tpl.php extension. Unlike other engines, these files just use PHP and HTML and do not rely on any special markup languages.

There’s more…

Other theme engines besides PHPTemplate are also available. However, only a handful of themes in Drupal’s contribution repository rely on them.

Other theme engine types

The PHPTemplate engine is the most widely prevalent theming engine used in the Drupal ecosystem and is a part of the Drupal core package. Themes using other engines such as Smarty or Xtemplate are rare and will be structured quite differently. A list of engines can be found at http://drupal.org/project/Theme+engines.

Engine-less theme
The Chameleon theme which is a part of core is a theme which does not use a templating engine and relies on straight PHP to get things done.

Creating a sub-theme based on a core theme

This recipe details the steps involved in creating a sub-theme of an existing core theme.

Getting ready

Create a folder named mytheme inside sites/all/themes. This name is usually also the name of the new theme and it is best to keep things uncomplicated by not using spaces and special characters. While mytheme is suitable for the purpose of this recipe, it will be a good idea to give the theme a unique and pertinent name based on its design and use. It is also important to ensure that there are no name-conflicts with other existing core or contributed themes.

How to do it…

A sub-theme of a core theme can be created through the following procedure:

1. Create a file named mytheme.info inside the mytheme folder.
2. Edit this new file and add the following code inside it:

   name = Mytheme
   description = My new sub-theme (CSS, phptemplate, 3-col)
   base theme = garland
   core = 6.x
   engine = phptemplate
   stylesheets[all][] = mytheme.css

   It is useful to add an informative description field as it will be visible in the theme administration page. Specifying the key characteristics of the theme can save time and effort as the administrator gets a quick overview of the design.

3. Save the file.
4. Create an empty CSS file named mytheme.css inside the mytheme folder.
5. Next, visit admin/build/themes (Home | Administer | Site building | Themes) to check if our new theme is available.

As the preceding screenshot attests, the theme administration page should now include our new theme—Mytheme. Enabling it should confirm that it is more or less identical to Garland and can now be extended further as per our requirements.

How it works…

Drupal uses the .info file to learn about our new sub-theme. The name and description variables, rather unsurprisingly, represent the name of the theme and a description that customarily includes details about the layout of the theme.

The base theme variable denotes the parent theme which our sub-theme is based on. By using this variable, we are informing Drupal that it should use the layout and styling of the base theme—in this case Garland—unless we indicate otherwise. This process is commonly referred to as overriding the base theme.

Finally, the core variable denotes the compatibility of our theme with Drupal 6, while engine indicates that the theme uses PHPTemplate as its templating engine. PHPTemplate is the most widely used system. Other engines, which include Smarty, PHPTal, and Xtemplate, are seldom used and themes using them are few and far between.

The stylesheets variable declares the CSS stylesheets to be included with the theme. When it comes to sub-themes, the stylesheets of base themes are automatically included unless explicitly overridden. However, due to a quirk in Drupal’s theming system, base theme stylesheets are not inherited by the sub-theme unless the latter declares at least one stylesheet of its own. We have worked around this by including an empty stylesheet named mytheme.css.

There’s more…

Drupal core provides an excellent example of a sub-theme based on a core theme.

Garland and Minnelli

Garland already has a sub-theme named Minnelli which is in a folder titled minnelli inside themes/garland. The difference between the two is that Garland uses a fluid layout while Minnelli is a fixed-width version of the same theme.

Chaining

Sub-themes can be chained, if necessary. For example, our mytheme could have used Minnelli as the base theme even though it is a sub-theme itself.