A theme is a collection of files which define the presentation layer of a Backdrop site. The theme determines the appearance of a site. You can also create one or more "sub-themes" or variations on a theme. Only the .info file is required, but most themes and sub-themes will use other files as well.
In Backdrop, the layout of a site is determined by the Layouts module, which is a drag and drop editor for arranging content and other page components on the page.
Contents of a theme
Themes are comprised of a theme directory, usually named after the theme, containing files and directories. Core theme directories are found in the BACKDROP_ROOT/core/themes directory; contributed themes in the BACKDROP_ROOT/themes directory. A theme directory may have the following example structure (although not all of these are required, as explained below):
BACKDROP_ROOT/themes
my_bartik
my_bartik.info
template.php
theme-settings.php
screenshot.png
templates (directory)
node.tpl.php
comment.tpl.php
maintenance-page.tpl.php
css (directory)
colors.css
(other css files)
images (directory)
add.png
(other image files)
color (directory)
base.png
(other color module files)Details of these components follow.
The theme .info file (required)
All that is required for Backdrop to see your theme is a ".info" file. Should the theme require them, meta data, style sheets, javascripts, block regions and more can be defined here. Everything else is optional. The internal name of the theme is also derived from this file. For example, if it is named "drop.info", then Backdrop will see the name of the theme as "drop".
template files (.tpl.php)
These templates are used for the (x)HTML markup and PHP variables. In some situations they may output other types of data --xml rss for example. Each .tpl.php file handles the output of a specific themable chunk of data, and in some situations it can handle multiple .tpl.php files through suggestions. They are optional, and if none exists in your theme it will fall back to the default output. Refrain from having complex logic in these files. In most cases, it should be straight (x)HTML tags and PHP variables. A handful of these templates exist in directories where core and contributed modules exist. Copying them to your theme folder will force Backdrop to read your version.
Note: The theme registry caches information about the available theming data. You must reset it when adding or removing template files or theme functions from your theme.
The template.php file
For all the conditional logic and data processing of the output, there is the template.php file. It is not required, but to keep the .tpl.php files tidy it can be used to hold preprocessors for generating variables before they are merged with the markup inside .tpl.php files. Custom functions, overriding theme functions or any other customization of the raw output should also be done here. This file must start with a PHP opening tag
Sub-themes
On the surface, sub-themes behave just like any other theme. The only difference is that they inherit the resources from their parent themes. To create one, a "base theme" entry inside the .info file is needed. From there it will inherit the resources from its parent theme. There can be multiple levels of inheritance; i.e., a sub-theme can declare another sub-theme as its base. There are no hard set limits to this.
The screenshot.png file
The screenshot is not absolutely necessary for the theme to function, but is recommended, especially if you are contributing your theme to the Backdrop repository. Screenshots will show inside the theme administration page and the user account settings for selecting themes when the appropriate permissions are set.
The theme-settings.php
To supply administrative UI settings or "features", a "theme-settings.php" file can be used.
The "color" directory
For color module support, a "color" directory with a "color.inc" file is needed along with various support files.
Sub-theme, don't copy
If you want to base your work on a core theme, use a sub-theme , or as a last resort, make a copy and rename the theme. Directly modifying core themes is strongly discouraged, since they are used for the install and upgrade process.
Writing theme .info files
The .info file is a static text file for defining and configuring a theme. Each line in the .info file is a key-value pair with the key on the left and the value on the right, with an "equals sign" between them (e.g. name = my_theme). Semicolons are used to comment out a line. Some keys use a special syntax with square brackets for building a list of associated values, referred to as an "array". If you are unfamiliar with arrays, have a look at the default .info files that come with Backdrop and read the explanations of the examples that follow. Even though the .info file extension is not natively opened by an Application, you can use TextEdit on a Mac or Notepad on a Windows computer in order to view, edit, and save your changes.
The following example shows the .info file for the Bartik theme:
name = Bartik
description = The default front-end theme for Backdrop CMS.
package = Core
type = theme
version = BACKDROP_VERSION
backdrop = 1.x
stylesheets[all][] = css/style.css
stylesheets[all][] = css/colors.css
stylesheets[print][] = css/print.css
ckeditor_stylesheets[] = css/ckeditor-iframe.css
settings[color] = trueTheme name requirements
The name should start with an alphabetic character, can contain numbers and underscores, but not hyphens, spaces or punctuation. The name will be used by Backdrop in forming various functions in PHP and therefore it has the same limitations. Warning! Do not choose the same name as a module, as all installed components must have unique names. For locally created themes using a prefix that is likely to be unique is good for theme naming. A site example.com might call its themes ex_themename. Because the .info file is cached, you must clear the cache before any changes are displayed in your site.
The .info file can also specify which theme settings should be accessed from the Backdrop administration interface, as you will soon see.
Encoding
The file must be saved as UTF-8 without a Byte Order Mark (BOM).
Contents
Backdrop understands the keys listed below. Backdrop will use default values for the optional keys not present in the .info file.
name (required)
name = A fantasy name
The human readable name.
description (recommended)
description = Tableless multi-column theme designed for blogs.
A short description of the theme. This description is displayed on the theme select page at "Administer > Site building > themes".
screenshot
screenshot = screenshot.png
The optional screenshot key tells Backdrop where to find the theme's thumbnail image, used on the theme selection page (admin/build/themes). If this key is omitted from the .info file, Backdrop uses the "screenshot.png" file in the theme's directory.
Use this key only if your thumbnail file is not called "screenshot.png" or if you want to place it in a directory outside of your theme's base directory (e.g. screenshot = images/screenshot.png).
theme version
version = 1.0
You can give your theme whatever version string makes sense.
backdrop version (required)
backdrop = 1.x
All .info files for modules and themes must indicate what major version of Backdrop core they are compatible with. The value set here is compared with the BACKDROP_CORE_COMPATIBILITY constant. If it does not match, the theme will be disabled.
type (Required)
type = theme
The type of project. For a theme, this will always be "theme". Other available types are "module" or "layout". Although this property is not required to enable the theme, it is required to properly package the theme on BackdropCMS.org and thus should always be included.
The theme engine is not necessary for Backdrop since only PHPTemplate is supported.
base theme
base theme = garland
Sub-themes can declare a base theme. This allows for theme inheritance, meaning the resources from the "base theme" will cascade and be reused inside the sub-theme. Sub-themes can declare other sub-themes as their base, allowing multiple levels of inheritance. Use the internal "machine" readable name of the base theme. The following is used in Minnelli, the sub-theme of Garland.
theme settings
settings[color] = true
You can use theme settings placed in .info file, to set the features by default.
stylesheets
stylesheets[all][] = css/style.css
stylesheets[all][] = css/another-stylesheet.css
stylesheets[print][] = css/print.cssStylesheet files to be included, one CSS file per line. The first bracketed key (either "all" or "print" typically), indicates the media type that will be used when including the CSS on the page.
ckeditor_stylesheets
ckeditor_stylesheets[] = css/ckeditor-iframe.cssIf your theme provides specific styling for CKEditor, CSS files may be specified in this section. These files will be loaded into the iframe used within the administrative interface when editing content. This allows you to format the contents within CKEditor to match the front-end of your site.
scripts
scripts[] = myscript.js
JavaScript files to be included, one JavaScript file per line. Any files specified will be loaded on every page of the site when the theme is used.
php
php = 5.3.3
This defines the minimum PHP version the theme will support. The default value is derived from the BACKDROP_MINIMUM_PHP constant, which is the minimum required version for the rest of core. This can be redefined for a newer version if needed. For most themes, this should not be added.
Assigning content to regions
See Layout
Global Settings
Certain global settings apply to all themes but are not managed by the theme system. This is a list of these settings.
- Logo
- Site name
- Site slogan
These are set in the "Site Information" admin page (/admin/config/system/site-information) and can be output in your theme by enabling the "Header block" in Layouts.
Menus (Primary links, Secondary links menus)
Site menus can be output in your theme Layout by adding the "Primary Navigation" block.
Clearing the theme cache
The contents of the .info file is cached in the database, so altering it will not be noticed by Backdrop. Also if you add new tpl.php files or override new theme functions you will need to clear the theme cache before they will be active.
Do not confuse the cache with the theme registry. To clear the cache, do one of the following:
- Click the "Flush all caches" button located under the Admin Bar home icon or "Clear all caches" button under Performance (/admin/config/development/performance). Note that this clears all caches, not only the theme cache. If you have a site with a lot of pages or a lot of traffic you might prefer to clear only the theme cache under the Admin Bar home icon.
- Visiting the theme selection page will also clear the .info file cache (admin/appearance)
Example: Creating a theme
Make Theme Directory and .info File
Create your theme directory in BACKDROP_ROOT/themes/my_theme.
Create a my_theme.info file and add the following to it. This is how you let Backdrop know your theme exists and that it should show it in admin/appearance.
name = My Theme
description = My custom Backdrop theme.
backdrop = 1.xAnd that should be it! This is the minimum requirement for creating a theme. At this point, if you click the Appearance link on the Admin Bar (/admin/appearance), your theme should be visible in the "Disabled Themes section". Click enable and set default to make your theme the active theme on your website.
Backdrop provides page layout options via the Layouts module, so you should be able to place blocks for the site header (logo, site name) and navigation elements, as well as custom and core blocks.
Of course, at this stage, the theme would be unstyled. Further customization can be done by adding CSS styles and modifying core template files if required.
Add your own style
Add the following line to your .info file:
stylesheets[all][] = css/page_style.css
You will also need to create a folder in your theme root called /css and create the page_style.css file there.
Add custom javascript (if needed)
Add the following line to your theme's .info file:
scripts[] = js/bold_script.js
You will also need to create a folder in your theme root called /js and create the bold_script.js file there.
Add your custom code in template.php
Create a template.php file in the root of your theme directory if your wish to add custom code. This includes theme function overrides, preprocess functions and other functions needed to affect your theme's output.
Further details about adding template.php functions to be covered in another instruction file.
Add template files
Create a /templates folder in the root of your theme if you wish to override core template files. Add or copy a template file with the same name in your theme folder to have it override the parent template.
Backdrop provides a large set of files that themes can use to inherit properties. By specifying a particular file name and or structure, this allows the theme to override or inherit a template. For example, if you wish to modify the output of nodes, create a file called node.tpl.php in your /templates folder. It is best to simply copy node.tpl.php from a core theme such as Bartik.
You can add template files with more specificity — for instance, node--blog.tpl.php, building on node.tpl.php.
A single hyphen is used to separate words: for example, "user-picture.tpl.php". A double hyphen indicates a more targeted override of what comes before the "--". For example, "node--long-content-type-name.tpl.php". See Converting 6.x themes to 7.x for more info.
Add your own screenshot
Add a screenshot.png to the root of your theme folder, or add an image file setting in your theme's .info file if you prefer to have your screenshot in a different location.