Home » Theme developer's guide (v5 and earlier) » Updating your themes

Converting 4.4.x themes to 4.5.x

Note: the theme system changed significantly in 4.5. Make sure you read through this entire guide, as an outdated theme will prevent you from accessing vital parts of your site.

Directory structure

Templates are now seen as themes unto themselves, rather than hiding behind their template engine. Template engines now reside in subdirectories of themes/engines, while templates simply are placed in subdirectories of themes. Template engines compatible with Drupal 4.5 will identify templates based on their filename and send the appropriate listings to the theme system.

For xtemplate templates, your template must be named xtemplate.xtmpl, and your default stylesheet must be named style.css (as mentioned below in the "Styles" section).

For example, the old Xtemplate pushbutton template has moved from themes/xtemplate/pushbutton to themes/pushbutton.

Tabs (a.k.a. Local Tasks)

Drupal now separates out menu items that are "local tasks"; functions to be performed on the current location. By default, these are rendered as a set of tabs. Themes are responsible for printing these. A typical location is below the page title, so that

<?php
if ($title = drupal_get_title()) {
  $output .= theme("breadcrumb", drupal_get_breadcrumb());
  $output .= "<h2>$title</h2>";
}

if ($help = menu_get_active_help()) {
  $output .= "<small>$help</small><hr />";
}
?>

becomes
<?php
if ($title = drupal_get_title()) {
  $output .= theme("breadcrumb", drupal_get_breadcrumb());
  $output .= "<h2>$title</h2>";
}

if ($tabs = theme('menu_local_tasks')) {
  $output .= $tabs;
}

if ($help = menu_get_active_help()) {
  $output .= "<small>$help</small><hr />";
}
?>

For xtemplate templates, Before:
<!-- BEGIN: title -->
{breadcrumb}
<h1 class="title">{title}</h1>
<!-- END: title -->

After:
<!-- BEGIN: title -->
{breadcrumb}
<h1 class="title">{title}</h1>
<!-- BEGIN: tabs -->
<div class="tabs">{tabs}</div>
<!-- END: tabs -->
<!-- END: title -->

Status Messages

The theme_page function is no longer responsible for rendering each status message. Instead, we now use the theme_status_messages() function. Before:

<?php
  foreach (drupal_get_messages() as $message) {
    list($message, $type) = $message;
    $output .= "<strong>". t("Status") ."</strong>: $message<hr />";
  }
?>

After:
<?php
  $output .= theme_status_messages();
?>

Static vs. Sticky

In Drupal 4.5, "static" posts have been renamed as "sticky" posts. If your theme uses special styling for this type of post, you'll want to change any references from "static" to "sticky".

Avatar vs. User Picture

In Drupal 4.5, "avatars" have been renamed to "user pictures". Additionally, the method by which themes display avatars has changed. Themes now call theme_user_picture, which returns the appropriate image and link HTML. Before:

<?php
  if (module_exist("profile") && variable_get("theme_avatar_node", 0)) {
    $avatar = $node->profile_avatar;
    if (empty($avatar) || !file_exists($avatar)) {
      $avatar = variable_get("theme_avatar_default", "");
    }
    else {
      $avatar = file_create_url($avatar);
    }
    if ($avatar) {
      $avatar = "<img src=\"$avatar\" alt=\"" . t("%user's avatar", array("%user" => $node->name ? $node->name : t(variable_get("anonymous", "Anonymous")))) . "\" />";
      if ($node->uid) {
        $avatar = l($avatar, "user/view/$node->uid", array("title" => t("View user profile.")));
      }
      $output .= $avatar;
    }
  }
?>

After:
<?php
  $output .= theme('user_picture', $node);
?>

For xtemplate templates, simply replace:
<!-- BEGIN: avatar -->
<div class="avatar">{avatar}</div>
<!-- END: avatar -->

with:
<!-- BEGIN: picture -->
{picture}
<!-- END: picture -->

Theme Screenshots

The new theme selector looks for a screenshot of each theme with the filename screenshot.png in each directory. Screenshots are optional and themes without screenshots will simply display "no screenshot" on theme selection pages. To create a screenshot which matches those in core, follow these instructions:

  1. Log in as administrator user.
  2. Enable the following modules, for some extra menu items:
    aggregator, blog, node, page, story, tracker
  3. Create the following story node:
    • title: Donec felis eros, blandit non.
    • body: Morbi id lacus. Etiam malesuada diam ut libero. Sed blandit, justo nec euismod laoreet, nunc nulla iaculis elit, vitae. Donec dolor. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos. Vivamus vestibulum felis <a href="#">nec libero. Duis lobortis</a>. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nunc venenatis pretium magna. Donec dictum ultrices massa. Donec vestibulum porttitor purus. Mauris nibh ligula, porta non, porttitor sed, fermentum id, dolor. Donec eu lectus et elit porttitor rutrum. Aenean justo. Phasellus augue tortor, mattis nonummy, aliquam euismod, cursus eget, ipsum. Sed ultricies bibendum ante. Maecenas rhoncus tincidunt eros.
  4. Look at the node, and make sure the tabs are visible. Take a screenshot.
  5. Cut out a piece about 420x254 resized to 150x90 (35% zoom). Try to show useful page elements (menu, tabs, title, links).
  6. Applied a plain 'sharpen' filter to the thumbnail.
  7. Save as "screenshot.png" in theme (or style) directory.

Centralized Theme Configuration

The theme system now has the ability to store certain common configuration items for each theme. However, some themes may not wish to utilize all of these settings, so a theme_features hook has been introduced. In each theme / theme engine, this function should return an array of settings which the theme supports. To implement each of these functions, themes / theme engines should call the theme_get_setting function, which will return data regarding the administrator's setting for this particluar theme. If there are no settings for the current theme, global values will be returned. Below is a table of values for the _features hook, a description of their function, and a code snippet of the appropriate theme_get_settings call.

_features hook value Description theme_get_settings call
'logo' theme allows customization of site logo
<?php
if ($logo = theme_get_setting('logo')) {
  $output .= "  <a href=\"./\" title=\"Home\"><img src=\"$logo\" alt=\"Home\" /></a>";
}
?>
'toggle_name' theme allows site name to be switched on/off
<?php
if (theme_get_setting('toggle_name')) {
  $output .= "  <h1 class=\"site-name title\">". l(variable_get('site_name', 'drupal'), ""). "</h1>";
}
?>
'toggle_search' theme allows search box to be switched on/off
<?php
if (theme_get_setting('toggle_search')) {
  $output .= search_form();
}
?>
'toggle_slogan' theme allows site slogan to be switched on/off
<?php
if (theme_get_setting('toggle_slogan')) {
  $output .= "  <div class=\"site-slogan\">". variable_get('site_slogan', '') ."</div>";

}
?>
'toggle_mission' theme allows site mission to be switched on/off
<?php
if ($mission = theme_get_setting('mission')) {
  $output .= $mission;
}
?>
'toggle_primary_links' theme allows primary links to be customized
<?php
$output .= theme_get_setting('primary_links');
?>
'toggle_secondary_links' theme allows secondary links to be customized
<?php
$output .= theme_get_setting('secondary_links');
?>
'toggle_node_user_picture' theme allows node user pictures to be switched on/off
<?php
if (theme_get_setting('toggle_node_user_picture') && $picture = theme('user_picture', $node)) {
  $output .= $picture;
}
?>
'toggle_comment_user_picture' theme allows comment user pictures to be switched on/off
<?php
if (theme_get_setting('toggle_comment_user_picture') && $picture = theme('user_picture', $comment)) {
  $output .= $picture;
}
?>
N/A (Global Setting) Allow admin to specify which node types should display "Submitted by..." message
<?php
$output .= theme_get_setting("toggle_node_info_$node->type") ? t("Submitted by %a on %b.", array("%a" => format_name($node), "%b" => format_date($node->created))) : '';
?>

Note that all of these settings are optional, but recommended.

Theme-specific settings are still possible as well. They are still read from the theme_settings, but are now placed in a group on the appropriate theme's tab, rather than on a separate page.

Styles

The theme system now allows for switching between different "styles" for each theme. Each "style" is defined by a style.css file in a subdirectory of the theme. In order to accomplish this style switching, themes should add a call to theme_get_styles() within their <head> block. For example:

<?php
$output .= drupal_get_html_head();
$output .= " &lt;link rel=\"stylesheet\" type=\"text/css\" href=\"themes/chameleon/common.css\" /&gt;\n";
$output .= theme_get_styles();
$output .= "&lt;/head&gt;";
?>

Notice how the reference to common.css is listed before theme_get_styles(). This allows individual styles to override your common CSS rules (if you use any).

The "default" style for each theme (the stylesheet in which you define color scheme and other general presentation items) should be renamed to style.css and placed in your theme directory. You should also remove any references to it from your theme or template. Drupal will reference it in theme_get_styles(). (If the default style is selected)

For xtemplate themes, you need to add the {styles} tag add the end of your <head> section.

_help hook

The theme_help hook is no longer used. It can be removed if desired.

References to comment_referer_load() should be switched to comment_node_url()

‹ Converting 4.5.x themes to 4.6.xupConverting 4.3.x themes to 4.4.x ›
» Login or register to post comments

Additional Change

crackerjackmack - October 21, 2004 - 21:02

use comment_node_url() instead of comment_referer_load()

Login or register to post comments
 
 

Drupal is a registered trademark of Dries Buytaert.