Converting 5.x themes to 6.x

A new theme developers guide is available specific to Drupal 6.

Module authors, please read the page: Using the theme layer in the module developer's guide.

Overview of Drupal Theme changes in 6.x

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.3
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.):

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 could be placed inside the "template.php" file and returned with the data.

To go even further and allow the theme function to use separate template files (.tpl.php), _phptemplate_callback() could be used. Enabling the callback also allowed the hook to manipulate the variables with the following.

The following is no longer supported:

In 6.x, _phptemplate_callback() is no longer supported. It has been rolled in to the main theme() function. As long as the function is registered as a template, the template file will be used. _phptemplate_variables() has also been deprecated. To replicate addition of variables in Drupal 6.x, look into the preprocess documentation.

Registering as a normal function works just like overridding with "themeEngine_hook()" or "themeName_hook()" without the callback in 5.x.

PHPTemplate automatically registers the hook as a normal function or template. To register the function as a template, all you need to do is create a file named after the hook followed by ".tpl.php". For example, the hook "menu_tree" is themable so, create a template file inside your theme named "menu-tree.tpl.php". Note the underscore being changed into a hyphen. Clear the registry and it will take over.

• 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 organising them through sub-directories. PHPTemplate engine will find all files in the theme and register thier 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.

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:

In 6.x:

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

$body_classes variable

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

In 5.x:

would print left, right, or both depending on the sidebars in use.

In 6.x $body_classes are also available:

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 intereger (0 or LANGUAGE_LTR for left to right and 1 or LANGUAGE_RTL for right to left). 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.

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 stlyes 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 overriden 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:

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

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, see the template.php file for the garland theme.

jQuery updated to 1.2.3

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

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 webpages. Often, JavaScript code produces markup that is inserted into the page. However, this HTML code has usually been hardcoded 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.