Upgrading subthemes

A dev version of Fusion for Drupal 7 was first committed to drupal.org in mid-2010. Got a subtheme to upgrade? Below is a file-by-file list of the changes needed to use the new Drupal 7 version of Fusion and convert a D6 Fusion subtheme to D7.

There are a lot more changes that actually happened in converting Fusion Core from D6 to D7 (see release notes), but this list below is generally limited to those which have a direct impact on subtheming.

INFO FILE

1. Change core value to 7.x
2. Change sidebar_last region to sidebar_second and the Sidebar last value to Sidebar second (http://drupal.org/update/theme/6/7#sidebars-renamed)
3. Add the new help/Help (http://drupal.org/update/theme/6/7#help-region), and page_top/Page top and page_bottom/Page bottom regions (http://drupal.org/update/theme/6/7#closure)
4. Remove content-top and content-bottom regions, since content is now a required region and users can now just add blocks and position them above and below the content itself (http://drupal.org/update/theme/6/7#content-region)
5. Remove Skinr screenshot preview style from D6 version. These can be added into Fusion Apply when the feature becomes available. (http://drupal.org/node/1329838)
6. Copy all default theme settings from Fusion Core’s .info file. Change as needed (as soon as http://drupal.org/node/563708#comment-2738844 is committed all settings will be inherited from base themes and you’ll only need to add changed settings)
7. Copy all Grid layout settings for nested region adjusting system from Fusion Core’s .info file. This should rarely need to be changed (as soon as http://drupal.org/node/563708#comment-2738844 is committed all settings will be inherited from base themes and you’ll only need to add changed settings).
8. Remove features[]=search

The grid layout structure has changed in Drupal 7 in order to be able to completely change the page layout and region nesting without having to change anything in template.php. The only things that need to be changed are the subtheme’s page.tpl.php and .info files. 

THEME-SETTINGS.PHP

There’s nothing you need to change here, but there are some important things to note.

1. The IE 31 stylesheet limit theme setting is gone because that functionality is now in core. To make sure it counts stylesheets correctly, make sure to add any css files using either the .info file or the drupal_add_css() function, which we’ve done (http://drupal.org/update/theme/6/7#css-ie-31-tag-limit-workaround).
2. The username “unverified” theme setting is gone. It’s now a global setting under admin/appearance/settings: “User verification status in comments.”
3. With the new way theme settings are done, you can add new theme settings directly in a subtheme simply by adding another theme-settings.php file for the subtheme (http://drupal.org/update/theme/6/7#theme-settings).

TEMPLATE.PHP

Again, there shouldn’t be much to change in a subtheme, unless it overrides something from the base theme’s template.php file or it uses a function that is no longer present in D7. But here are some important changes to keep in mind.

1. The way body classes are sent to templates from template.php has become standardized. Now we add classes to $vars['classes_array'] in the preprocess function for any template (http://drupal.org/update/theme/6/7#html-class-variable).
2. Regions are the new “rows.” Fusion rows were always the same thing as a region, conceptually speaking, but we didn’t have any way to deal with regions directly. Now we have a region.tpl.php template and preprocess functions, so the functionality previously found in the theme('grid_row') function is now taken care of by the region template and functions. Instead of calling theme('grid_row') to output a grid row in a page.tpl.php file now we just use render($page['region']).
3. Grid layout settings are now read from the .info file rather than being hardcoded into template.php.
4. Now that Drupal has contextual links, Fusion’s code for block edit links has been removed.
5. Removed the fusion_core_preprocess_comment_wrapper() function which set up some constants because those constants are no longer used.
6. Removed the code that pre-rendered Ubercart elements so they could be positioned easier in the node-product.tpl.php template. Going forward, we hope to take advantage of the new granular rendering in node templates for Drupal Commerce. See the related note for node.tpl.php below.

HTML.TPL.PHP

1. This is a new standard Drupal 7 template file that abstracts out the head and body markup. It’s in Fusion Core so we can add a body id, but you shouldn’t need to add it to a subtheme.
2. The “skip” id (previously in page.tpl.php but now in html.tpl.php) is now “skip-link.”
3. Internet Explorer conditional styling has been moved to html.tpl.php. Fusion now implements the styling suggested here: http://paulirish.com/2008/conditional-stylesheets-vs-css-hacks-answer-ne…. Once you have updated Fusion core, you can remove the ie6-fixes-rtl.css, ie6-fixes.css, ie7-fixes-rtl.css, ie7-fixes.css, ie8-fixes.css files from your theme’s css directory, if present. Themes should inherit the style settings from Fusion core.

PAGE.TPL.PHP

1. As noted above, the head and body markup has been moved to html.tpl.php, so your page.tpl.php should only include the <div id=”page”> tag and what’s inside it. Refer to Fusion Core’s page.tpl.php.
2. Remove the code that provides a default search box in page.tpl.php. This functionality has now been replaced by letting the user put a search block in the region of their choice (http://drupal.org/update/theme/6/7#search_box).
3. The closure region is no longer used and should be removed (http://drupal.org/update/theme/6/7#closure).
4. Change print theme('grid_row') statements to print render($page['region']). The grid theming is added by the region.tpl.php template and preprocess function (http://drupal.org/update/theme/6/7#granular).
5. A few other non-region elements in page.tpl.php (e.g., $tabs, $action_links) are now output with the new render() function (http://drupal.org/update/theme/6/7#granular).
6. Use the new style for outputting the main menu (previously primary links) and secondary menu (previously seondary links). Both menus are pre-themed as $primary_menu_themed and $secondary_menu_themed respectively, though $primary_menu and $secondary_menu are still available in page.tpl.php if needed (http://drupal.org/update/theme/6/7#menu_tree).
7. Use the new theme function format for the theme('grid_block') function. Now, after the function name, you have to pass in an array of named options, which is longer but actually makes the operation more clear, in my opinion (http://drupal.org/update/theme/6/7#function-argument-variables). For example:
   D6: 
   <?php
   print theme(‘grid_block’, $breadcrumb, ‘breadcrumbs’); 
   ?>
   D7:
   <?php
   print theme(‘grid_block’, array(‘content’ => $breadcrumb, ‘id’ => ‘breadcrumbs’)); 
   ?>
8. Now that content is a region, feed icons can be added as a block and positioned, so you can remove the $feed_icons variable.
9. Update maintenance-page.tpl.php if needed. See Fusion Core’s version for reference.
10. Note the following changes in class names:
    row -> region
    primary -> main
    sidebar-last -> sidebar-second
    layout-main-last -> layout-main-second
    layout-first-main-last -> layout-first-main-second

REGION.TPL.PHP

1. This is a new template file in Fusion Core. It’s been modified in order to serve the same function as the grid_row in the D6 version of Fusion.

BLOCK.TPL.PHP

1. Change $block->content to $content in block.tpl.php, otherwise you won’t get any block content (http://drupal.org/update/theme/6/7#block-content)!
2. Note the new style of block css ids (http://drupal.org/update/theme/6/7#blocks). In Fusion Core, this only involved changing “block-user-0” to “block-user-login,” but you may use some additional block ids in your subtheme that will need to be changed.

NODE.TPL.PHP

1. Change “Submitted by” to now be formatted in the node.tpl.php file, rather than relying on formatting from template.php (which has been removed).
2. For now, we’ve removed node-product.tpl.php & node.tpl.php from Fusion Starter Our intention is to add them back and use the new granular render() function in node-product.tpl.php to position product elements for particular subthemes (http://drupal.org/update/theme/6/7#granular).
3. Note the following changes in node class names:
   teaser -> node-teaser
   node-type-x -> node-x (e.g., node-type-story to node-story)
   sticky -> node-sticky

BOX.TPL.PHP

1. This template file is no longer used in D7 themes, so it needs to be removed (http://drupal.org/update/theme/6/7#box).

COMMENT.TPL.PHP

1. Like node.tpl.php, you’ll need to add the “Submitted by” formatting to the template.
2. Any reference in css to div.links in this template should be changed to ul.links.
3. Note the following changes in comment class names:
   comment-by-anon -> comment-by-anonymous
   comment-mine -> comment-by-viewer
   comment-by-author -> comment-by-node-author
   signature -> user-signature

SEARCH_THEME_FORM.TPL.PHP

1. Since there is no longer a default search box in page.tpl.php, this template no longer exists in D7 and its functionality is in a new template: search_block_form.tpl.php since users will now need to add a search block to a region of their choice (http://drupal.org/update/theme/6/7#search_box).

ALL TEMPLATES

1. All templates need to be updated with the new markup for classes and attributes. Use the templates in Fusion Core as a reference (http://drupal.org/update/theme/6/7#html-class-variable & http://drupal.org/update/theme/6/7#html-attributes-variable).
2. Fusion now uses Fusion Accelerator’s Fusion Apply module for skins, so all explicit references to printed Skinr classes in templates should be removed.

CSS

1. Change any css class names affected by the changes noted above for each template file.
2. Change any references to the grid “row” class to “region.” But be careful, since the class name “row” is sometimes used for other things as well (e.g., tables, views).
3. If you are overriding Fusion’s grid gutters in a subtheme, you will have previously used .inner. Now all structural .inner classes have been renamed to .gutter to make it clearer. .inner is only used as an inner wrapper div for people to do styling of so they don’t break the grid – not structural.
4. Remove any Skinr screenshot preview styles from themename-style.css (see related item for Info file above and check the Fusion Accelerator queue for updates to this feature).
5. Several core css files need to be renamed to help prevent stylesheet collisions in subthemes. In Fusion core, these are now pre-pended with ‘fusion’:
   1. style.css should be renamed to fusion-style.css
   2. style-rtl.css to fusion-style-rtl.css
   3. typography.css to fusion-typography.css
6. Rename local-sample.css to local.css.sample to be more in line with current Drupal naming conventions.

JAVASCRIPT

1. Screenshot.js has been removed (see related item for Info file above and http://drupal.org/node/691302).
2. There is a new way to add Drupal behaviors using the “attach” method (http://drupal.org/node/224333#drupal_behaviors). We’ve modified the existing behaviors in script.js, but you’ll need to modify any subtheme-specific js accordingly.

MENUS

Menus are now their own region(s), instead of being part of other regions. These will need to be defined in your .info file in the regions section. As an example:

regions[main_menu] = Main menu

SUPERFISH

Superfish has been removed from Fusion core entirely and is now its own module, available at http://www.drupal.org/project/superfish . All of the configuration data has been removed from Fusion as a result. Remove the following data from your .info files:

1. ’Superfish menu styles’ section
2. CSS references – the defaults are:
   1. stylesheets[all][] = css/superfish.css
   2. stylesheets[all][] = css/superfish-navbar.css
   3. stylesheets[all][] = css/superfish-vertical.css
3. Remove scripts[] = js/superfish.js

Once Superfish is installed and enabled, it is configurable from admin/structure/blocks. You get four potential blocks by default (superfish 1-4, changeable under Superfish config), which can be placed and configured like other blocks. Fusion now uses blocks for all menus instead of printing special case menu variables in the theme. This is the way Drupal core is headed and enables much more flexibility with content you can put into regions and how they can be styled.

Using the new Superfish will also give the flexibility to use any menu option or dropdown script that may be desired, and can allow for menus provided by other modules. Main menu blocks may also be configurable based on different pages and contexts.

FUSION ACCELERATOR

Skinr has been replaced by Fusion Accelerator in Drupal 7. Skin formats are completely different, and you will need to rewrite your skins. They are now PHP arrays in .inc files that can live in either your subtheme or a module. Check out the skins in fusion_core or this issue on Drupal.org to learn more about the new format.

To update for Fusion Accelerator – to the .info files of Fusion Starter and Starter lite, add:

1. fusion[api] = 2
2. fusion[directory] = skins

Fusion themes list this under [stylesheets[all][] = css/fusion-starter-style.css

OTHER RESOURCES

Some other resources to come up to speed on D7 theming in general:

• http://drupal.org/update/theme/6/7 - This should be your first reference for new features/changes. A must read.
• http://drupal.org/node/224333 - This is more for javascript and php/api changes. Still helpful for certain things.
• http://pingvision.com/blog/al-steffen/2009/drupal-7-theme-changes - A great overview of changes, though a little out of date.