Converting 6.x themes to 7.x

Overview of Drupal Theme changes in 7.x

1. Blocks have new, more meaningful CSS IDs
2. Primary and secondary links are now Main and Secondary menu
3. Unrendered taxonomy links are no longer available as a separate variable in node.tpl.php files
4. RDFa requires some changes at the begining of page.tpl.php
5. The clear-block class has been renamed to clearfix
6. The box.tpl.php template has been removed
7. $help became a region
8. Mission statement removed, 'highlight' region suggested
9. Footer message removed
10. Content region is now mandatory, main page content became a block
11. Second phase variable process functions
12. HTML classes generated through a variable
13. HTML attributes generated through a variable
14. Variable process functions can now be used for all theming hooks
15. All theme functions now take a single argument, $variables
16. Function names must match theme name
17. All CSS and JavaScript files must be specified in the theme's .info file
18. Renamed $block->content in block.tpl.php
19. Granular rendering in node and user templates
20. Added jQuery UI (1.7) to core
21. Attached JS/CSS for elements
22. $closure becomes $page_bottom, new $page_top and hidden regions
23. $left and $right variables are now $sidebar_first and $sidebar_second; CSS IDs also changed
24. $picture changes to $user_picture, and the CSS class 'picture' to 'user-picture'
25. New classes available to hide content in an accessible manner
26. JavaScript variable Drupal.jsEnabled has been removed
27. PHPTemplate suggestion wildcard
28. Include theme definition explicitly on element when using system_elements()
29. Added markup to make installation task progress perceivable with screen-reader and CSS disabled.
30. Added an invisible heading to theme_breadcrumb().
31. Changes to alt and title attribute for the RSS feed icon
32. Search box moved from theme layer to blocks
33. Changes to menu tree, link and tab rendering functions
34. theme_links() has a new parameter $heading for accessibility
35. theme_get_setting() and THEME_settings() have been improved
36. Added a theme_form_required_marker() function
37. Added a theme_link() function
38. Skip to main content links in core themes

Blocks have new, more meaningful CSS IDs

Many of the CSS IDs for blocks defined by Drupal core have changed so that they more clearly indicate the purpose of the block:

Block
Old CSS ID (Drupal 6)
New CSS ID (Drupal 7)

Recent blog posts
block-blog-0
block-blog-recent

Book navigation
block-book-0
block-book-navigation

Recent comments
block-comment-0
block-comment-recent

Active forum topics
block-forum-0
block-forum-active

New forum topics
block-forum-1
block-forum-new

Language switcher
block-locale-0
block-locale-language-switcher

Syndicate
block-node-0
block-node-syndicate

Most recent poll
block-poll-0
block-poll-recent

Author information
block-profile-0
block-profile-author-information

Search form
block-search-0
block-search-form

Popular content
block-statistics-0
block-statistics-popular

Powered by Drupal
block-system-0
block-system-powered-by

User login
block-user-0
block-user-login

Navigation
block-user-1
block-system-navigation

Who's new
block-user-2
block-user-new

Who's online
block-user-3
block-user-online

For example, a Drupal 6 CSS style declaration such as:

should become (in Drupal 7):

Primary and secondary links are now Main and Secondary menu

Primary and Secondary links have been renamed to Main and Secondary menu. Themes which support these options will need to be updated to use the new variable names:

6.x

7.x

Unrendered taxonomy links are no longer available as a separate variable in node.tpl.php files

Previously, node.tpl.php files could use the $taxonomy variable if they needed access to an array of unrendered taxonomy links associated with the current node.

In Drupal 7, this is no longer the case. Instead, all links have been moved into the $node object. The array of unrendered taxonomy links can now be found in $node->content['links']['terms']['#value'] instead. (Note that this array should be used with caution, since the text contained within it has not been escaped to prevent XSS attacks.)

Rendered taxonomy links are not affected; node.tpl.php files can continue to access these via the $terms variable, as before. In many cases, the $terms variable is what you want to use in your theme anyway, and you might be able to replace references to $taxonomy with it, as in the following example:

6.x

7.x

RDFa requires some changes at the begining of page.tpl.php

Drupal 7 is able to output RDFa which requires the following changes in page.tpl.php.

• The DOCTYPE must be changed to XHTML+RDFa 1.0.
• The old lang attribute should be removed for compatibility with XHTML 1.1, only xml:lang should remain.
• The RDF namespace prefixes used throughout the HTML document need to be serialized in the html tag and are contained in the $rdf_namespaces variable.
• The GRDDL profile should be specified in the <head> tag.

6.x

7.x

The clear-block class has been renamed to clearfix

The “clear-block” class was a Drupalism for functionality that was better known by the CSS Community as the “clearfix” class. Also, using “block” in the old name was confusing to Drupal users more familiar with Drupal’s block system than with the properites inside that CSS ruleset. New themers and designers to the Drupal community will no longer be confused by the old class name.

If you had a <div class="clear-block"> in your D6 theme, simply change it to <div class="clearfix">.

The box.tpl.php template has been removed

The amorphous box.tpl.php template has been removed. Those pieces of content that were using the box.tpl.php now have their own theme function.

The search results listings are now themed with a theme_search_results_listing() theme function and the comment form box is themed with a theme_comment_form_box() theme function.

$help became a region

(issue) In Drupal 7, a new region was added to the defaults (left, right, content, header, footer) called help. By default, the textual content of this region is the same as the $help variable was in page.tpl.php for Drupal 6.

Themes in Drupal 7 need to ensure that the $help variable is printed in page.tpl.php and, if the theme overrode the default regions, that the following line is added to its .info file:

The help text is now surrounded by the block.tpl.php template’s <div> tags and classes, so the CSS used to style the help likely needs changing.

Mission statement removed, 'highlight' region suggested

(issue) In Drupal 6, the page template received a special variable called $mission, which contained the mission statement setting of the website when on the front page. Drupal 6 themes also had an option on the theme settings page to toggle this functionality. Drupal 7 removes the mission setting and the option toggle in favor of the more general custom block placement in regions.

Drupal 7 core themes now include a region named 'highlight' which uses the same display as the mission statement area in Drupal 6. Whether this region has content now depends on administrators setting block placement, and is not limited to the front page only. Content in the highlight region will be surrounded by the block.tpl.php template’s <div> tags and classes, so the CSS used to style this area might need changing.

If your theme ships without a highlight region, you should override the list of regions in your .info file. Such as if you only support content, help and left regions:

Footer message removed

(issue) In Drupal 6, the page template received a special variable called $footer_message, which contained the footer message setting of the website. This was usually output before the footer region ($footer) by the template. Drupal 7 recognizes, that the footer message was just a special type of user defined block. Those who had this setting in Drupal 6 will get a user defined block in the update, positioned in the $footer region.

To update your themes, just remove the $footer_message variable from them.

If you happened to output the $footer_message in your page template, but did not yet support the $footer region, now might be the time to start supporting this region. If you don't override any regions, the footer region will be predefined for you. If you do override regions, please output the $footer content in your page template and include the footer region in your .info file:

Support for the footer region is just suggested but not required by Drupal. Those upgrading from Drupal 6 with a theme lacking support for the footer region will be able to reposition their block to another region.

Content region is now mandatory, main page content became a block

(issue) In Drupal 6 and before the $content variable in page.tpl.php contained the main page content appended with the blocks positioned into the content region (if you had that region defined).

In Drupal 7, $content became a full region and is now mandatory in all themes. This new requirement was set up so that when enabling new themes, Drupal knows where to put the main page content by default.

In Drupal 6, it was only possible to put blocks after the main page content in this region. The only way to put blocks before the main page content was to define a specific region for that purpose. Drupal 7 now makes the main page content its own block. This makes it possible to put blocks before or after the main page content in the region without hacking in a new region.

If you relied on the fact that blocks were only put in the sidebars and therefore got their styling via just a .block class selector or something similar, now you might need to revisit your CSS files. Because the main page content is wrapped by markup from block.tpl.php, the .block selector will match that too, so you need to limit your blocks styling to certain regions by making the selectors more specific, such as #left-sidebar .block.

Second phase variable process functions

There are now two sets of variables process functions. The first are the existing "preprocess" functions. The second are "process" functions which are run after preprocessors. All the various prefixes and suffixes apply to this second phase in the exact same way. This is useful when certain variables need to be worked on in two phases.

For example, adding classes into an array for the "preprocess" phase then flattening them into a string in the "process" phase so it's ready to print within a template. See next section.

HTML classes generated through a variable

All templates can now print out $classes from a template to render dynamic classes built from variable process functions. The way to add these dynamic classes is by feeding the variable key labeled "classes_array" like so:

The default "template_process" (second phase processor) will take care of flattening the array into a flat string making it ready to print from your template. Dynamic classes are generated for common templates by default but due to the way it's set-up, any template can have a $classes variable.

Example:

HTML attributes generated through a variable

All templates can now print out $attributes, $title_attributes, and $content_attributes from a template to render dynamic attributes built from variable process functions. The RDF module and other modules add important information to these variables, so it is important for themes to ensure that these variables are printed correctly within all overridden template files. These three variables contain attributes for the overall element being rendered by the template, and its primary title and content elements, respectively. The way to add attributes to these variables is by feeding the variable keys labeled "attributes_array", "title_attributes_array", and "content_attributes_array" like so:

The default "template_process" (second phase processor) takes care of flattening the arrays into strings ready to print within the template file. The flattening process results in either empty strings (if no dynamic attributes were set) or strings that have a leading space followed by attribute names and values. Because of this, the attributes variables should be printed directly next to what precedes it in the template, with no leading space.

Example:

As is shown in the example, the convention is for the "id" and "class" attributes to be printed explicitly within the template, and for the attributes variables to be used for all other attributes. Therefore, to ensure that no attribute gets printed twice within the same element, the following rules should be followed:

• Preprocess functions within modules must not add "id" or "class" to the attributes arrays.
• Preprocess functions within themes may add "id" and/or "class" to the attributes arrays, but if they do so, the theme must also override the corresponding template file and ensure that the same attribute isn't being printed explicitly.
• Templates must not print any attribute other than "id" or "class" explicitly on any element for which an attributes variable is also being printed. Instead, the theme must use a preprocess function, as shown above.

Variable process functions can now be used for all theming hooks

(issue) In Drupal 6, preprocess functions could only be used for theming hooks rendered by templates. In Drupal 7, hook-specific preprocess and process functions can be used for all theming hooks, whether rendered by templates or functions. For example, a theme can make all menu links that start with "http:" or "https:" (as opposed to ones that refer to an internal drupal path) to open in a new browser tab:

Every preprocess function adds to the time it takes to theme the item, so especially for theme functions that get called a lot, keep an eye on performance when adding preprocess functions.

To minimize performance overhead, the non-hook-specific preprocess and process functions are called for templates only. See the API documentation for theme() for the full list of hook-specific and non-hook-specific preprocess and process functions.

All theme functions now take a single argument, $variables

(issue) In Drupal 6, theme functions registered their function arguments in hook_theme(). In Drupal 7, all theme functions take a single argument, $variables, an array of keyed variables, and register the expected keys within this array in hook_theme().

6.x

7.x

Function names must match theme name

Function names in the file template.php must now use the relevant theme's name. You may no longer use phptemplate_function. This change was made in the following patch: Die, themeEngineName_ prefix, die!. To update your theme ensure there are no functions that begin with the template engine name (phptemplate) in the file template.php or any related template files.

All CSS and JavaScript files must be specified in the theme's .info file

In Drupal 6 style.css and script.js would be included in your theme automatically, even if they weren't present in the theme's .info file. In Drupal 7, themes must specify these files in the .info file to include them. More information about this change can be seen at #351487: Remove default values for stylesheet and scripts includes from system module. If your theme doesn't use these files, or if they are all ready specified in your theme's info file, no changes are required.

Renamed $block->content to $content in block.tpl.php

See this issue for the whole story.

Granular rendering in node and user templates.

Issue. Template authors may now finally print out bits of node and profile content as they see fit and still maintain forward compatibility with new modules that might add new content. To do so, template authors should use 2 new functions - render() and hide(). Example taken from node.tpl.php:

render() returns all the items that are in $content. So, print render($content) is equivalent to the D6 print $content. When a templater wants to print out part of the $content array, she may do so with something like print render(content['links']). If the printing of links comes after the printing of all the rest of $content, then templater should call hide($content['links']) before calling print render($content). Then, the links can be printed further down in the template with print render($content['links']).

Added jQuery UI (1.7) to core

(issue) jQuery UI 1.7 was added to core. You can find the jQuery UI files in misc/ui and can add Javascript and CSS files from there to your pages with the regular drupal_add_js() and drupal_add_css() calls, no special function calls required. If you are migrating a theme which was previously dependent on the jquery_ui contributed module, see the module update guide on the topic, which provides examples.

Attached JavaScript and CSS for drupal_render

(issue) Individual elements now have the ability to define what JavaScript and cascading stylesheets are associated with them. This is stated in the #attached_js and #attached_css property.

Drupal 6.x:

Drupal 7.x:

$closure becomes $page_bottom, new $page_top and hidden regions

(issue 1), (issue 2) Drupal 6 provides a special variable called $closure which should be put at the bottom of the HTML body output and can be themed via theme_footer() (which calls out to implementations of hook_footer() in modules). To generalize on one way to put output to the different page areas, Drupal 7 standardizes on regions and introduced the page_bottom region in place of the $closure special variable. Also, page_top is added as a pair of page_bottom. In Drupal 7 you need to output $page_top at the top of the HTML body output and $page_bottom at the bottom.

Drupal 6:

Drupal 7:

If you define custom regions, it is important to remember that you need to include the page_top and page_bottom regions in your set of regions.

theme .info file extract:

The page_top and page_bottom regions are hidden, which means they will not show up on the blocks administration interface. When doing site-specific themes, it might also be useful to add more hidden regions (to provide ways for modules to add output to more places in the theme without defining blocks showing up on the blocks interface), you can do that via the regions_hidden[] .info file array which is new to Drupal 7:

theme .info file extract:

$left and $right variables are now $sidebar_first and $sidebar_second; CSS IDs also changed

(issue) In Drupal 6, the sidebar variable names were $left and $right. In Drupal 7 they are $sidebar_first and $sidebar_second.

6.x

7.x

This means that associated CSS IDs have changed as well:

Old CSS ID (Drupal 6)New CSS ID (Drupal 7)
.sidebar-left.sidebar-first
.sidebar-right.sidebar-second

$picture changes to $user_picture, and the CSS class 'picture' to 'user-picture'

The variable and the CSS class have been renamed to be more descriptive.

Drupal 6 (user-picture.tpl.php):

Drupal 7:

New classes available to hide content in an accessible manner

Two new system classes have been added to be used for the purpose of hiding elements, .element-hidden and .element-invisible. Each class serves its own unique purpose:

.element-hidden

The role of this class is to hide elements from all users. This class should be used for elements which should not be immediately displayed to any user. An example would be a collapsible fieldset that will be expanded with a click from a user. The effect of this class can be toggled with the jQuery show() and hide() functions.

.element-invisible

The role of this class is to hide elements visually, but keep them available for screen-readers. This class should be used for information required for screen-reader users to understand and use the site where visual display is undesirable. Information provided in this manner should be kept concise, to avoid unnecessary burden on the user. This class must not be used for focusable elements (such as links and form elements) as this causes issues for keyboard only or voice recognition users.

JavaScript variable Drupal.jsEnabled has been removed

In previous versions of Drupal, you could do the following in JavaScript code, to verify that JavaScript was enabled and sufficient for Drupal to do its "behaviors":

In Drupal 7, the Drupal.jsEnabled variable is no longer defined, and there is no work-around -- the assumption is that JQuery things will simply not work if they don't work, so there's no reason to check ahead of time. See issue #444352: Kill the killswitch for discussion.

PHPTemplate suggestion wildcard

(issue) PHPTemplate offers suggestions based on the URI integers. In Drupal 6, you have to theme the previous suggestion or the specific one eg.

page-user.tpl.php or page-user-1.tpl.php

This was cumbersome because to theme all the user pages, it meant overriding page-user.tpl.php, which in turn themed the user login page.

The new suggestion wildcard for integer arguments accepts % suggestions page-user-%.tpl.php. Suggestions which have additional arguments like page-user-edit.tpl.php remain the same; this simply differentiates the suggestions with and without integer args.

Include theme definition explicitly on element when using system_elements()

In system_elements(), it is now necessary to include the theme definition explicity on the element, rather than allowing the system to "fallback" and assign it automatically. Refer to issue 127731.

Added markup to make installation task progress perceivable with screen-reader and CSS disabled

(Issue)

In D6 there is no markup to indicate which of the installation tasks ware complete, or which task is active, these differences are only shown with CSS styling.

In Drupal 7 markup has been added to theme_task_list() to:

Add a heading that is only visible to screen-reader users and when CSS is disabled.

<h2 class="element-invisible">Installation tasks</h2>

Append text "(done)" and "(active)" to relevant tasks in the task list, visible only to screen-reader users and when CSS is disabled.

<span class="element-invisible">(done)</span>

Add an invisible heading to theme_breadcrumb()

(Issue)

In D6 there is no markup to indicate the role or purpose of the breadcrumb links to users of screen-readers.

Drupal 7 provides a heading before the list of breadcrumb links, which is visible to screen-reader users and when CSS is disabled. This heading has been added to theme_breadcrumb() and to garland_breadcrumb().

<h2 class="element-invisible">You are here</h2>

Changes to alt and title attribute for the RSS feed icon

In D6 the alt attribute of the RSS feed icon themed by theme_feed_icon() was statically set to "Syndicate content" and the title attribute of the icon was set to the string passed to the function in the $title parameter.

Drupal 7 sets the alt attribute of the image and the title attribute of the anchor for the RSS feed to the same text. The text is comprised of "Subscribe to " + the $title string passed to theme_feed_icon().

Search box moved from theme layer to blocks

In previous versions, the search_box was displayed by the theme using $search_box.

Drupal 7 removes this. The search form is simply part of the block system. Theme developers will want to remove all references to $search_box in the theme, and may need to change CSS to handle the search box in the block.

Site maintainers upgrading sites from Drupal 6 to Drupal 7 will want to add the search form block to their site.

Changes to menu tree, link and tab rendering functions

(Issue)

function menu_tree_output() now returns a structured array of data that can be rendered to html using drupal_render().

Function theme_menu_item_link() and theme_menu_item() have been removed and are effectively replaced by in terms of rendering a menu tree by theme_menu_link(). This is the default function used to render each link in the tree returned by menu_tree_output().

Function theme_menu_local_task() takes different parameters and has a companion theme_menu_local_action() that did not exist in Drupal 6. Both of these function take as the first parameter a menu link array with 'title', 'href', and 'localized_options' keys. In Drupal 6, the first parameter was a string. The change to array was made in order to allow removal of theme_menu_item_link(). The second parameter theme_menu_local_task() of is still a boolean, $active.

theme_links() has a new parameter $heading for accessibility

Issue: #364219: Navigation menus should be preceded by headings of the appropriate level (usually <h2>).

To meet Web Content Accessibility Guidelines (WCAG) requirements, HTML headings should be used before all content sections, which includes lists of links such as menus. The headers ensure that there is a quick way for assistive technology users to browse through the content; however, most visual users do not need headers on navigation lists, because they can get a sense of the structure by how they are arranged visually on the page. So, the recommendation is to add a header with the "element-invisible" CSS class on it, so that only assistive technology users will notice the header.

It is also important that the header level used (H2, H3, etc.) be appropriately nested in the heading hierarchy. So, it is not recommended to just blindly add an H2 header before each list.

For that reason, the theme_links() function, which is normally called via theme('links', ...), has a new third parameter $heading to add the required heading to a list of links.

For example - Drupal 6 in a typical page.tpl.php file:

Drupal 7:

This will result in a semantically correct and accessible secondary menu in Drupal 7, because an invisible heading has been added:

For more information:

• Accessibility in Drupal
• Theming accessibility guide
• Headings section of theme accessibility guide

theme_get_setting() and THEME_settings() have been improved

In Drupal 6, themes could add custom form elements to their “configure theme settings” page at admin/build/themes/settings/THEMENAME. Themes would need to create a theme-settings.php page in their theme directory and use a function with the following syntax:

In Drupal 7, much more flexibility is given to themes to modify the entire theme settings form. In a theme’s theme-settings.php, themes should now use a THEMENAME_form_system_theme_settings_alter(&$form, $form_state) function. This gives the same power to themes that modules have if they use hook_form_system_theme_settings_alter(). See the “Forms API Quickstart Guide” and “Forms API Reference” on http://api.drupal.org/api/7, as well as the hook_form_FORM_ID_alter() docs to learn the full flexibility of Forms API. Note that themes can no longer use the phptemplate_ prefix to the function; you’ll need to use the actual name of your theme as the prefix.

Here’s an example if you had a “foo” theme and wanted to add a textfield whose default value was “blue bikeshed”:

In order to set the default value for any form element you add, you’ll need to add a simple line to your .info file: settings[SETTING_NAME] = DEFAULT_VALUE. For our foo theme, you’d need to edit the foo.info file and this line:

In any of your theme’s php files, you can retrieve the value the user set by calling:

theme_form_required_marker()

(issue) The markup for generating the marker on required form elements is now handled by a separate function, theme_form_required_marker() instead of just being included as part of the work performed by theme_form_element(). This allows you to reuse this markup in other places or to modify the markup without changing all of theme_form_element()

theme_link()

(issue) The markup for generating a link is now handled by a theme function, theme_link(), instead of being hard-coded into the l() function. This allows you to implement a preprocess function or an override function in order to customize the markup of any link. Doing so may slow down Drupal pages that have many links, so it is recommended to evaluate the benefit vs. the performance trade-off, but the capability exists for sites and themes that need it. This theme function is for customizing the markup of links, generically. Other theme functions exist for customizing links based on context. For example, to customize menu links, override theme_menu_link() instead.

Example of hook_preprocess_link():

Example of overriding theme_link():

Skip to main content links in core themes

(Issue)
To meet Web Content Accessibility Guidelines (WCAG) 2.0 guideline 2.4.1 Bypass Blocks, web pages need to have a link to help keyboard only users and screen readers more easily access the main content of a website.

Garland's implementation is hidden visually, but keep them available for screen-readers. Furthermore, if a keyboard only user tabs through a site the link will become visible as it gains focus.

To hide the skip navigation you can use one the new classes available to hide content in an accessible manner.