Drupal 6: Theme Engines and Sub-themes

Exclusive offer: get 50% off this eBook here
Drupal 6 Theming Cookbook

Drupal 6 Theming Cookbook — Save 50%

Over 100 clear step-by-step recipes to create powerful, great-looking Drupal themes

£16.99    £8.50
by Karthik Kumar | November 2010 | Content Management Drupal Open Source

Themes are among the most powerful and flexible features available when it comes to the presentation of a website. The greatest strength of Drupal lies in its design which, when done correctly, allows developers and designers to customize and micromanage each and every aspect of the site.

In this article by Karthik Kumar, author of the book Drupal 6 Theming Cookbook , we will cover the following recipes:

  • Understanding the anatomy of a theme
  • Creating a sub-theme based on a core theme
  • Overriding base theme elements in a sub-theme
  • Changing the screenshot image of a theme

 

Drupal 6 Theming Cookbook

Drupal 6 Theming Cookbook

Over 100 clear step-by-step recipes to create powerful, great-looking Drupal themes

  • Take control of the look and feel of your Drupal website
  • Tips and tricks to get the most out of Drupal's theming system
  • Learn how to customize existing themes and create unique themes from scratch
  • Part of Packt's Cookbook series: Each recipe is a carefully organized sequence of instructions to complete the task as efficiently as possible
        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.

Drupal 6 Theming Cookbook Over 100 clear step-by-step recipes to create powerful, great-looking Drupal themes
Published: November 2010
eBook Price: £16.99
Book Price: £27.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on Drupal, see here.)

Overriding base theme elements in a sub-theme

This recipe details the steps involved in overriding a base theme template file. We will be restructuring the layout of a Drupal node by modifying the node.tpl.php template.

Getting ready

We will be using the mytheme sub-theme which was created in the previous recipe.

How to do it...

As we are dealing with a sub-theme here, it is by default relying on the template files of its base theme. To override the base file used to theme the layout of a node, copy the node. tpl.php file from the base theme's folder—themes/garland—to the sites/themes/ mytheme folder. Opening the new file in an editor should bring up something similar to the following:

<?php
// $Id: node.tpl.php,v 1.5 2007/10/11 09:51:29 goba Exp $
?>
<div id="node-<?php print $node->nid; ?>" class="node<?php if
($sticky) { print ' sticky'; } ?><?php if (!$status) { print ' node-
unpublished'; } ?>">
<?php print $picture ?>
<?php if ($page == 0): ?>
<h2><a href="<?php print $node_url ?>" title="<?php print $title
?>"><?php print $title ?></a></h2>
<?php endif; ?>
<?php if ($submitted): ?>
<span class="submitted"><?php print $submitted; ?></span>
<?php endif; ?>
<div class="content clear-block">
<?php print $content ?>
</div>
<div class="clear-block">
<div class="meta">
<?php if ($taxonomy): ?>
<div class="terms"><?php print $terms ?></div>
<?php endif;?>
</div>
<?php if ($links): ?>
<div class="links"><?php print $links; ?></div>
<?php endif; ?>
</div>
</div>

The highlighted lines in the preceding code excerpt indicate the code we are looking to modify. To elaborate, we are going to move the taxonomy terms DIV from the bottom to a position further above, right next to the submitted DIV. Doing so will result in the node.tpl.php file now looking like this:

<?php
// $Id: node.tpl.php,v 1.5 2007/10/11 09:51:29 goba Exp $
?>
<div id="node-<?php print $node->nid; ?>" class="node<?php if
($sticky) { print ' sticky'; } ?><?php if (!$status) { print ' node-
unpublished'; } ?>">
<?php print $picture ?>
<?php if ($page == 0): ?>
<h2><a href="<?php print $node_url ?>" title="<?php print $title
?>"><?php print $title ?></a></h2>
<?php endif; ?>
<?php if ($submitted): ?>
<span class="submitted"><?php print $submitted; ?></span>
<?php endif; ?>
<?php if ($taxonomy): ?>
<div class="terms"><?php print $terms ?></div>
<?php endif;?>
<div class="content clear-block">
<?php print $content ?>
</div>
<div class="clear-block">
<?php if ($links): ?>
<div class="links"><?php print $links; ?></div>
<?php endif; ?>
</div>
</div>

Once this has been done, save the file and exit the editor. As we have made changes to the template system, we will need to rebuild the theme registry, or simply clear the entire Drupal cache.

How it works...

For performance purposes, Drupal maintains a registry of all the stylesheets which have been included, the template files which are available, the theme functions which have been declared, and so on. As our theme initially had no node.tpl.php file in the mytheme folder, Drupal fell back to the node.tpl.php file of the base theme which, in this case, is Garland. However, once we added one to the mytheme folder, we needed to rebuild this registry so that Drupal became aware of our changes. Once this was done, Drupal used the updated node.tpl.php file the next time a node was displayed.

The following screenshots provide a before and after comparison of an example node:

In the following screenshot, we can see our modified template file in action as the position of the taxonomy term Category 1 has moved from the bottom to the top of the node.

There's more...

The non-invasive technique of extending base themes using sub-themes allows for smooth upgrades.

Clean upgrades

If we had modified the node.tpl.php file inside Garland, the next time our Drupal installation is upgraded, we would have very likely forgotten about our changes and overwritten them during the upgrade process. By using a sub-theme, we can now upgrade Drupal without any fear of losing any changes we have made.

Another positive is that if bugs have been fixed in Garland, they will seamlessly propagate downriver to our sub-theme.

Changing the screenshot image of a theme

This recipe details the steps involved in changing the screenshot image associated with a theme. This image provides the user with a preview of what the site will look like when the theme is enabled. This is normally only required when we are working with a sub-theme or a custom theme.

Getting ready

Once the theme is just about ready to go, visit the front page of the site to take the screenshot. Since we are providing a snapshot of the theme, temporarily swap the name of the site with the name of the theme. It might also be useful to prepare some example content for display on the front page to obtain an accurate representation of the style and layout of our theme.

How to do it...

Adding a screenshot for our theme can be done via the following steps:

  1. On the front page, press ALT + Print Screen to take a screenshot of the active window.

    Mac users can use Command + Shift + 3 while Linux users should be able to bring up the screenshot utility relevant to their distribution by pressing Print Screen.

  2. Open up a graphics editor and paste the screenshot within.
  3. Make a wide selection of the theme incorporating different elements such as the position of the logo, breadcrumb, fonts, node styles, and so on.
  4. Crop and resize to 150x90 pixels which is the standard size for theme screenshots.
  5. Save the image as a PNG file named screenshot.png.
  6. Finally, copy the file to the theme's folder.

Visiting admin/build/themes (Home | Administer | Site building | Themes) should confirm that screenshot.png is being used to represent our theme.

How it works...

Drupal automatically looks for a file named screenshot.png in the theme's folder and, if found, includes that image as a preview of the theme on the theme management page.

There's more...

Each theme's .info file provides the syntax required to specify many of the theme's configuration settings. This also includes nominating the screenshot file to be used.

Using the .info file

The screenshot image can also be specified in the theme's .info file using the following syntax:

screenshot = mytheme.png

where mytheme.png is the name of the screenshot file.

 

Summary

This article explained the concept of theme engines and sub-themes.


Further resources on this subject:


Drupal 6 Theming Cookbook Over 100 clear step-by-step recipes to create powerful, great-looking Drupal themes
Published: November 2010
eBook Price: £16.99
Book Price: £27.99
See more
Select your format and quantity:

About the Author :


Karthik Kumar

Karthik Kumar is a Drupal developer residing in Chennai, India. He first came across Drupal in late 2004 and has been a fan ever since. He maintains a number of modules on http://drupal.org under the moniker Zen – http://drupal.org/user/21209.

Books From Packt


Drupal 7
Drupal 7

Drupal 6 Attachment Views
Drupal 6 Attachment Views

Drupal 6 Search Engine Optimization
Drupal 6 Search Engine Optimization

Drupal 6 Performance Tips
Drupal 6 Performance Tips

Drupal 6 Panels Cookbook
Drupal 6 Panels Cookbook

Drupal E-commerce with Ubercart 2.x
Drupal E-commerce with Ubercart 2.x

Flash with Drupal
Flash with Drupal

Drupal 6   Content Administration
Drupal 6 Content Administration


Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software