The most important consideration when converting themes to Backdrop is the concept that your theme is no longer responsible for the layout of a site. This is because of the introduction of Layout module, Backdrop's drag-and-drop page layout builder.
Layout module now provides ten responsive layout templates including a multi-region stacked layout similar to what was provided in the Bartik theme for Drupal 7. In the Layouts interface, blocks are provided to place the site header, main navigation, search box, and so on. All these elements can be rearranged by dragging and dropping these blocks into the regions provided by the layout template.
Porting a theme mainly now consists of the application of the old theme's style to the new theme. Once this is understood, the conversion itself should be reasonably straightforward.
Before you begin
Before you start porting a contributed theme, please create the two recommended issues stated on the Communicating section of the Converting to Drupal page.
Organization of Files
The organization of files within the theme directory is similar to that of Drupal, but there are some differences. For reference, see the developer documentation for Backdrop themes. You can also download a sample theme template to use for reference.
Convert the .info file
See https://api.backdropcms.org/themes for info file recommendations. The main change is that the version string needs to be updated to backdrop = 1.x rather than core = 7.x. If you are planning on contributing this theme back, a new line type = theme will also need to be added. All region information can be removed as regions are now managed by Layout module.
Convert template files
Move the Drupal 7 page.tpl.php out of the way
We're going to deal with the code inside the page.tpl.php file later on, but we don't want the Backdrop theme using this file. We recommend renaming this file to page--old.tpl.php so that it will not be used by your backdrop site.
Convert node.tpl.php first
Next, open the node.tpl.php file and make the following changes:
Convert un-processed arrays
The process layer was removed in Backdrop, so now some arrays which were previously translated to strings in process need to be flattened in your templates.
<?php print $classes; ?> now becomes <?php print implode(' ', $classes); ?>
<?php print $attributes; ?> now becomes <?php print backdrop_attributes($attributes); ?>
<?php print $content_attributes; ?> now becomes <?php print backdrop_attributes($content_attributes); ?>
The comments have new renderable
Previously comment information was stored in $content['comments'].
Now comments are in $comments, as in:
$comments['comments']: Rendered comments for this node.
$comments['comment_form']: Form for adding a new comment.
See the documentation for all the available variables in node.tpl.php.
Repeat these conversions for any additional node templates, or files named node--X.tpl.php.
Rename html.tpl.php to page.tpl.php
In Backdrop, there is no html.tpl.php file. The HTML, HEAD, and BODY tags are rendered in a file named page.tpl.php more similar to how it was done in Drupal 6 themes.
If your Drupal 7 theme had a html.tpl.php file, you will need to change the way the HEAD tag, CSS and JS assets are added to the page in page.tpl.php.
See the change record for converting the html.tpl.php file.
Enable the theme
At this point it may be reasonable to try to see if this theme can be enabled. It is likely that incompatible code in other template files may lead to PHP warnings. These warnings can be addressed one at a time. If there are too many warnings to address at once, we recommend temporarily renaming these files too (add the --old at the end) then introducing them one at a time until all .tpl.php files have been converted.
Convert more template files
Customize header markup
In Drupal 7, customizations to the header area of a site were made directly in the page template. In Backdrop, because the site header is now a block, customizations to the header are done in a file named header.tpl.php.
If your Drupal 7 theme had a custom site header, then copy the default header.tpl.php file from core/modules/system/templates/header.tpl.php into your theme. Then copy any customizations from page--old.tpl.php into the new header template file.
Customize layout markup
If the old page--old.tpl.php file contains markup changes beyond the site header that you would like to preserve, you will first need to decide how many layout templates you will be using for your Backdrop site, and move these additional customizations into the .tpl.php file for each layout template.
Moving customizations from a Drupal 7 page template into a Backdrop layout template can be done in two ways:
Create a custom layout template
If the layout of your Drupal 7 theme is significantly different from all Backdrop core layout templates, or if it does not have the same number of regions, you will need to create a custom layout template in addition to the theme. See how to create a custom layout template.
Override a core layout template
If the layout of your Drupal 7 theme closely matches one of the Backdrop core layout templates (it would need to have exactly the same number of regions) then the .tpl.php file for that core layout can be overridden in the theme.
To override the tpl.php file for the core layout template, locate the layout template and its tpl.php file in the core/layouts directory, and copy the tpl.php file into the theme. Edit the tpl.php file, adjusting the markup to match page--old.tpl.php. The region names will need to match.
When this is done, page.tpl.php is no longer necessary. Some other templates may require a similar mapping process before they are deleted. At all points, the changes can be confirmed by refreshing the page in your browser. Once page layout is satisfactory, other templates can be adjusted.
Modify other templates
Other templates will likely require conversion of $classes and $attributes arrays as described previously in the node template conversion example.
Update CSS selectors
Update the CSS to target HTML elements that are consistent across all core layouts
In Drupal 7 themes, the CSS often targets layout-specific elements that were defined in the page.tpl.php file.
In Backdrop, we identify layout-specific elements across all core layouts by using consistent classes that begin with l-.
For example: Here was your custom page.tpl.php
<div id="page">
<div class="header">...</div>
</div>And here was your custom CSS...
#page { width: 100%; }
.header { width: 960px; }A Backdrop layout provides the following page HTML structure:
<div class="layout--moscone-flipped layout">
<header class="l-header" role="banner" aria-label="Site header">...</header>
....
</div>There are two ways to tackle this conversion: update the selectors in the old CSS file, or add the old identifiers into all possible layout template files. We find that the updating CSS selectors is usually less work than updating the template files.
From the example above, CSS previously targeting the ID #page could be switched to target the class .layout, and CSS previously targeting the class .header could be switched to target the <header> element instead.
.layout { width: 100%; }
header { width: 960px; }The end result would be the same. Similar conversions need to apply to all page--old.tpl.php elements such as footer, sidebar, highlights and so on. The details of this operation would obviously vary based on the complexity of the theme.
Update template.php
If your theme has overrides of theme functions, preprocess functions, or alter functions, they are probably in a template.php file. This file will likely need very few changes to work for Backdrop.
Adjust CSS selectors
Some CSS selectors may be missing, or may have changed from Drupal to Backdrop. If you would prefer to add back the selectors rather than update your CSS files, you can add the selectors you used in Drupal 7 to the $variables['classes'] array for nearly any template file. See the example below.
If your Drupal 7 theme made use of the not-front or the not-logged-in classes, you might want to add them back as follows:
/**
* Override or insert variables into the page template.
*/
function MYTHEME_preprocess_page(&$variables) {
if (!backdrop_is_front_page()) {
$variables['classes'][] = 'not-front';
}
if (!user_is_logged_in()) {
$variables['classes'][] = 'not-logged-in';
}
}Alternatively, you may replace all instances of the not-front class in your CSS with :not(.front), and all instances of not-logged-in with :not(.logged-in).
Update JavaScript
If your theme previously provided JavaScript for sliders or drop-down menus, these could (optionally) be removed. The combination of Views module and Layout module now allows for swappable sliders, menus, and more, without requiring that the JavaScript for these elements exist in the theme. If, however, you would like to retain the JavaScript for these items in the theme, you will also want to check the CSS selectors in the JavaScript.