Category: CMS

Categories
CMS PHP Websites

Convert a Drupal 5 theme to version 6

So you fell in love with a Drupal theme, but it just wasn’t ready for Drupal 6. What now?

This is a step by step procedure for bringing your old theme into the new Drupal format.

What’s New

  1. Themes now have .info files
  2. Theme registry
  3. Theming through template files
  4. Template management
  5. New template files (.tpl.php)
  6. New template naming suggestions
  7. Defining block regions
  8. Block region variables name change
  9. Custom theme settings
  10. New $signature variable
  11. $body_classes variable
  12. $language is now an object
  13. Themes can override core- and module-defined CSS files
  14. Right to left CSS override files supported
  15. Submitted by user on date/time is themable
  16. jQuery updated to 1.2.6
  17. Default JavaScript file
  18. JavaScript themeing

Themes now have .info files

In 5.x, Drupal modules saw the introduction of .info files to store meta data about the module (for example, the name, description, version, dependencies, etc.). Starting in 6.x, Drupal themes also have a .info file. See the complete guide to writing .info files for themes for more information.

Example themeName.info (partial list.):

name = Theme Name
description = One sentence description of theme.
core = 6.x
engine = phptemplate

Theme registry

All theme functions must now be registered. In Drupal 5, they were all discovered on the fly. New in 6.x, hook_theme() is used to register all themable output. PHPTemplate engine takes care of registering on behalf of the theme so in most situations you will not have to register manually.

  • There is one exception to this. Forms that do not have a default theme implementation will not be registered.
  • See the example in the theming handbooks for more details on theming forms.
  • Important note! Whenever you add a new theme function or template inside your theme the registry must be cleared!

Theming through template files

In 5.x, themable functions could be overridden with themeEngine_hook() or themeName_hook(). All the markup was placed inside the template.php file and returned with the data. Or, to use a separate template file (.tpl.php), _phptemplate_callback() could be used in 5.x.

In 6.x, _phptemplate_callback() is no longer supported, because it has been rolled in to the main theme() function. But you don’t need it: As long as the hook is registered as a theme function (see above), you can override the default theming by either creating a function with the right name “themeName_hook()”, or a file with the right name “hook.tpl.php”. For example, the hook menu_tree is themable. So, to override it, create a function in template.php called “theme_name_menu_tree()”, or a template file inside your theme named menu-tree.tpl.php. Note the underscore being changed into a hyphen in the file name. Clear the registry and your theme function or template file will take over theming for menu trees.

In 5.x, using _phptemplate_callback() also allowed the hook to manipulate the variables with the following. The following is no longer supported:

<?php
function _phptemplate_variables($hook, $variables) {
switch ($hook) {
case 'page':
// process variables for page hook.
break;
case 'node':
// process variables for node hook.
break;
}
return $variables;
}
?>

To replicate addition of variables in Drupal 6.x, look into the preprocess documentation.

  • More details on the overriding behavior is available.
  • You can take a look at the underlying changes between 5 and 6. –links to pdfs

Template management

Template files (.tpl.php) can now be managed more easily by organizing them through sub-directories. PHPTemplate engine will find all files in the theme and register their locations. There is no limit on its depth either.

New template files (.tpl.php)

In 5.x the following templates are implemented by phptemplate.engine (inside the theme engines folder):

  • page.tpl.php
  • node.tpl.php
  • comment.tpl.php
  • block.tpl.php
  • box.tpl.php

With the new changes under the hood, more default templates are provided and more will be available in future releases. The ones from PHPTemplate in 5.x were also moved. Read the comments inside these files to see where they are used and the available variables.

In order to override these templates, all you need to do is copy them into your theme folder and clear the theme registry.

See the complete list of new templates in the theming handbook.

The seldom used default core functions for the above templates are no longer present. For example, theme_page no longer exists. This affects all themable output converted into templates. Due to the nature of the change, they are no longer necessary. This change should not affect anyone. Do not confuse the removed functions with how they are called. theme('page') still works. It is the default implementation that has changed.

New template naming suggestions

Template suggestions existed for page.tpl.php -based on path, node.tpl.php -based on node type and block.tpl.php -based on regions and modules. With the template conversions mentioned above, new suggestions are also provided.

See the complete list of new template suggestions in the theming handbook.

Defining block regions

hook_regions has been deprecated. Regions are now defined through .info files. More details available in the main handbook page.

regions[left] = Left sidebar
regions[right] = Right sidebar
regions[content] = Content
regions[header] = Header
regions[footer] = Footer

Block regions variable name change

The variable names for side bar block regions and footer has been changed.

In 5.x the regions “left”, “right” and “footer” used the variables $sidebar_left, $sidebar_right and $footer_message inside page.tpl.php. This was ancient cruft that was needed in 4.6 and below.

To make it cleaner and more straight forward, the three regions create variables of $left, $right and $footer just like any other region. $footer_message is still used but it’s for the footer message set from site information administration page.

Custom theme settings

Theme authors can now make their theme easily customizable by site administrators.

In the Drupal administration section, each theme has its own settings page at admin/build/themes/settings/themeName. And this page has a form with standard settings like “Logo image settings” and “Shortcut icon settings”. To add additional settings to the form, simply create a theme-settings.php file in the theme’s directory and add a themeName_settings() or themeEngineName_settings() function. The function should use the Forms API to create the additional form widgets.

See the Custom theme settings page in the Theme developer’s handbook for full details.

New $signature variable

In Drupal 6, signatures were made dynamic, which means they display when viewing a comment, and are not part of the comment itself. Therefore, a $signature variable needs to be added to comment.tpl.php.

In 5.x:

<div>
<?php print $content; ?>
</div>

In 6.x:

<div>
<?php print $content ?>
<?php if ($signature): ?>
<div>
<?php print $signature ?>
</div>
<?php endif; ?>
</div>

Note: you can use the following to prevent double-display of signatures on old posts:

<div>
<?php print $content ?>
<?php if ($signature && $comment->cid > 1234): // Change "1234" to the last comment ID used before upgrading to Drupal 6 ?>
<div>
<?php print $signature ?>
</div>
<?php endif; ?>
</div>

$body_classes variable

Inside page.tpl.php getting the state of the layout was possible with this:

In 5.x, <?php print $layout; ?> would print left, right, or both depending on the sidebars in use.

In 6.x $body_classes are also available. <?php print $body_classes; ?> may retrieve something like:

front logged-in node-type-page no-sidebars

which offers a set of specialized classes like those seen above. You can learn more at:
http://drupal.org/node/171906

$language is now an object

The $language variable accessible to PHPTemplate themes is now not only a simple string holding the language code of the current page viewed, but an object representing multiple properties of the current language. You can now make your theme right to left compliant, so that your theme can be used by people hosting content in right to left written scripts (like Hebrew, of which http://www.drupal.org.il/ is a good example).

$language has the $language->language property available with the current language code, and $language->direction being an integer (0 or LANGUAGE_LTR for left to right and 1 or LANGUAGE_RTL for right to left). $language->dir would return a string that’s either rtl for right to left or lrt for left to right.
Accordingly, page.tpl.php would use the $language object to do the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php print $language->language ?>" lang="<?php print $language->language ?>" dir="<?php print $language->dir ?>">
<head>
...
</head>
<body dir="<?php print $language->dir ?>">
...
</body>
</html>

If you are only interested in updating your themes, just change every instance of $language to $language->language.

Themes can override core- and module-defined CSS files

Themes may replace module-defined CSS files by adding a stylesheet with the same filename using drupal_add_css(). This allows themes to override complete CSS files, rather than specific selectors, when necessary.

For example, if the following code were placed in Garland’s template.php file, themes/garland/system-menus.css would replace modules/system/system-menus.css:

<?php
drupal_add_css(path_to_theme() .'/system-menus.css', 'theme');
?>

Right to left CSS override files supported

To better support languages that flow right to left, any CSS file added to the page with drupal_add_css() can have a right to left CSS file pair. An example could be style.css, which can have a style-rtl.css file in the same directory. This file can contain overrides for the styles in style.css which should be different in a right to left language. The Drupal core system includes such RTL CSS files for built-in modules as well as some themes. By convention, the overridden rules are marked with an /* LTR */ comment in the original CSS file, so maintainers will notice that the RTL CSS might need modification when modifying the original CSS file later. These CSS files are only loaded when an RTL language is used to display the page.

An excerpt from the modules/system/defaults.css file:

th {
text-align: left; /* LTR */
padding-right: 1em; /* LTR */
border-bottom: 3px solid #ccc;
}

An excerpt from the modules/system/defaults-rtl.css file:

th {
text-align: right;
padding-right: inherit;
padding-left: 1em;
}

Submitted by user on date/time is themable

The “submitted” element in nodes and comments is now themable just like any themable element. This means that you can override what information is included, and how it is presented.

You can add custom id/class, you can include more or less info, or even make the submitted look different for comments or node types.

For an example, in template.php file for the garland theme:

function phptemplate_comment_submitted($comment) {
return t('!datetime — !username',
array(
'!username' => theme('username', $comment),
'!datetime' => format_date($comment->timestamp)
));
}function phptemplate_node_submitted($node) {
return t(‘!datetime — !username’,
array(
‘!username’ => theme(‘username’, $node),
‘!datetime’ => format_date($node->created),
));
}

jQuery updated to 1.2.6

The jQuery JavaScript library included in Drupal was updated to version 1.2.6.

Default JavaScript file

Similarly to style.css, there is a new automatically included file named script.js for adding JavaScript code to a theme. The file should be placed in the theme’s home directory. This file name can be changed and more can be added through the .info file.

JavaScript themeing

There is now a themeing mechanism for JavaScript code. Together with the automatically included script.js, this allows theme developers more freedom in the domain of scripted events on Drupal web pages. Often, JavaScript code produces markup that is inserted into the page. However, this HTML code has usually been hard-coded into the script, which did not allow alteration of the inserted code.

Modules provide default theme functions in the Drupal.theme.prototype namespace. Themes should place their override functions directly in the Drupal.theme namespace. Scripts call Drupal.theme('function_name', ...) which in turn decides whether to call the function provided by the theme (if present) or the default function.

JavaScript theme functions are entirely free in their return value. It can vary from simple strings, up to complex data types like an object containing in turn several jQuery objects which are wrapped around DOM elements. See the original (default) theme function to see what your custom theme function should return.