Last updated September 21, 2011. Created by O Govinda on February 22, 2008.
Edited by RoloDMonkey, NancyDru, Carolyn, mfer. Log in to edit this page.
Sub-themes are just like any other theme, with one difference: They inherit the parent theme's resources. There are no limits on the chaining capabilities connecting sub-themes to their parents. A sub-theme can be a child of another sub-theme, and it can be branched and organized however you see fit. This is what gives sub-themes great potential.
Imagine starting with a base theme designed as wireframes, then applying and refining all the details from a sub-theme. Then, from the same wireframe, testing out alternate designs by branching out another sub-theme. Working on a multi-site installation but you need a cohesive look and feel? With sub-theming, a lot of the design resources can be shared. Site-specific changes can be set to a specific sub-theme, but any shared resources can be edited once to be applied across all the installations. With careful planning, the possibilities are endless.
Creating a sub-theme
The sub-theme to-be should be located in its own directory. Prior to Drupal 6, this directory had to be a subdirectory of its base theme; in Drupal 6 and 7 it can be placed outside of the base theme's directory.
To declare your theme to be a sub-theme of another, it is necessary to alter the sub-theme's .info file. Add the following line to the sub-theme's .info to declare its parent or "base theme." Change "themeName" to the internal name of the parent theme (that is, the name of the parent theme's .info file, usually all lower case).
base theme = themeName
Style sheet inheritance
All style sheets defined in the parent theme will be inherited, as long as you declare at least one stylesheet in your sub-theme's .info file. You must declare at least one stylesheet in your sub-theme for any of the parent theme's stylesheets to be inherited.
Overriding inherited style sheets: Specify a style sheet with the same filename in the sub-theme. For instance, to override style.css inherited from a parent theme, add the following line to your sub-theme's .info file:
stylesheets[all][] = style.css
You will also need to create the style.css stylesheet file; if you simply wish to disable the imported styles, you can create an empty file.
JavaScript inheritance
All JavaScripts defined in the parent theme will be inherited.
Overriding inherited JavaScript: Specify a JavaScript file with the same filename in the sub-theme's .info file. For instance, to override script.js inherited from a parent theme, add the following line to your sub-theme's .info file:
scripts[] = script.js
You will also need to create the script.js stylesheet file; if you simply wish to disable the imported styles, you can create an empty file.
Template.php function inheritance
Anything defined in the parent theme's template.php file will be inherited. This includes theme function overrides, preprocess functions and anything else in that file. Each sub-theme should also have its own template.php file, where you can add additional functions or override functions from the parent theme.
There are two main types of functions in template.php: theme function overrides and preprocess functions. The template system handles these two types in very different ways.
Theme functions are called through theme('[hook]', $var, ...). When a sub-theme overrides a theme function, no other version of that theme function is called.
On the other hand, preprocess functions are called before processing a .tpl file. For instance, [theme]_preprocess_page is called before page.tpl.php is rendered. Unlike theme functions, preprocess functions are not overridden in a sub-theme. Instead, the parent theme preprocess function will be called first, and the sub-theme preprocess function will be called next.
There is no way to prevent all functions in the parent theme from being inherited. As stated above, it is possible to override parent theme functions. However, the only way to remove a parent theme's preprocess function is through hook_theme_registry_alter().
Page, node, block and other template (.tpl.php) file inheritance
Drupal 7 Any .tpl.php files from the parent theme will be inherited. You can add template files with more specificity — for instance, node--blog.tpl.php building on an inherited node.tpl.php.
A single hyphen is still used to separate words: for example, "user-picture.tpl.php" or "node--long-content-type-name.tpl.php", so the double hyphen always indicates a more targeted override of what comes before the "--". See Converting 6.x themes to 7.x for more info.
Drupal 6: Any .tpl.php files from the parent theme will be inherited. However, to add template files with more specificity, you must also copy over the more general template file from the parent theme manually. For instance, to add a node-blog.tpl.php template in a sub-theme, you must also copy over node.tpl.php from the parent theme. This bug has been fixed in Drupal 7 but will not be fixed in Drupal 6.
Overriding inherited .tpl.php templates: Add a template file with the same name in your sub-theme folder to have it override the template from the parent theme.
Screen shots and logo inheritance
The parent theme's screen shot will be inherited. The parent theme's logo (logo.png/logo.jpg) will not be inherited.
Overriding inherited screen shots: Specify a new image file in your sub-theme's .info file.
Region inheritance
Sub-themes do not inherit custom regions from a parent theme. If you are using custom regions, you should copy the region declarations from the parent theme's .info file. Be sure your sub-theme's page.tpl.php file matches the sub-theme's region settings.
Color and theme settings inheritance
Color.module support within the color directory is not inherited.
Theme settings set via advanced theme settings' theme-settings.php are not inherited.
Comments
Theme and module with the same name = no content
Thanks for the nice summary. One thing to add: when naming your sub-theme, avoid using the same name for a theme and a module. If you do you will just have "Array" as content of your blocks (I suppose the module and theme functions interfere with each other). I renamed the theme and everything's fine now.
Or worse :)
Themes may implement theme_block(). Modules may implement hook_block(). Having a module and a theme which occupy the same namespace will cause either function to be picked up for both roles.
If your module's hook_block() is picked up by the theme layer, you will see array() as the contents of all blocks.
I'm not sure what happens if your theme's theme_block() matches a module name. Probably nothing disastrous? Let us know!
If both exist, you'll get a fatal error when the theme attempts to redefine the function already defined by the module.
This is touched on in Doesn't Play Nicely. hook_block() is gone in D7 for this (and other) reasons.
If my comments have helped you, please pay it forward!
Use issue queues to discuss module issues - this will help your questions assist others (including yourself!) in future.
http://twitter.com/grobot ● www.giantrobot.co.nz
Overriding inherited style sheets
This guide says that to prevent inheritance you will need to create the style sheet and that it can be empty. However, the documentation in the the zen/STARTERKIT.info.txt says that we don't need to have a file with that name; all we need to do is the array declaration:
stylesheets[all][] = style.cssif we wanted to prevent inheritance of style.css.
No need for empty css files
vegantriathlete wrote:
> we don't need to have a file with that name
Yes, there is no need now for empty css files, it was just a workaround for bugs that were fixed for D6 and D7. As you say, a line in the .info file is enough.
More info: Overriding style sheets from modules and base themes.
Sub-theme bug
There is an important D6 sub-theme (and sub-sub-theme) bug, #481142: Theme settings forms are not inherited by sub-themes, with a patch by Zen's maintainer JohnAlbin (#26) that seems to work but has been waiting for review for a long time.
Bug fixed
#481142: Theme settings forms are not inherited by sub-themes has just been fixed today. That is to say, when Drupal 6.20 will be released (it's 6.19 now). For those who might want to test it now, new bug fixes are added to Drupal 6.x-dev twice a day.
Difference between preprocess extensions and theme overrides
This document doesn't make an important distinction between preprocess functions and theme functions. Others might find this discussion useful for understanding how Drupal extends preprocess functions but doesn't override them. The system of overrides in template.php described in this article is only applicable to theme functions, not to preprocess functions. Understanding the difference will help anyone who is new to Drupal theming avoid some of the programming assumptions I made!
See, http://drupal.org/node/915778
The document was updated to
The document was updated to make this more clear.
--
Read more at iRolo.net
Practical implementation of a preprocess function
I thought this code might be helpful to understanding a practical implementation of a preprocess function.
The code below would check the current path to see if it matches certain criteria and then add an additional stylesheet to the template that renders pages in that path.
Remember that if your theme name is flowers then the preprocess function would be named
flowers_preprocess_page(&$vars)You can include preprocess functions in your theme'stemplate.phpfile. If your theme doesn't have atemplate.phpfile you can simply create the file in your theme's directory.So you would have:
<?php
//template.php
//&$vars is simply the aggregated variables available at this point in the template building process
flowers_preprocess_page(&$vars) {
/**
* add additional CSS files using drupal_add_css()
* but only if my path contains "tulips"
* drupal_add_css() returns an array of stylesheets
* at this point in building the page template, $vars['styles'] has already been built
* so call drupal_get_css() again in order to re-build $vars['styles']
* after the call to drupal_get_css(), $vars['styles'] will be repopulated with
* your additional stylesheet
*/
if( module_exists('path') ) {
$alias = drupal_get_path_alias( $_GET['q'] );
$check_path = "tulips"; //we are looking for any pages that fall in the "tulips" path, e.g., "/tulips/boulder-co-tulip-festival"
if( strpos( $check_path, $alias ) !==FALSE ) {
$addcsspath = path_to_theme() . "/drupaladd.css";
$css = drupal_add_css( $addcsspath, "theme","all" );
//uncomment this line below to see how Drupal builds its internal CSS array
//print_r( $css );
$vars['styles'] = drupal_get_css(); //rebuild the styles variable with an array that includes all previous CSS files and the newer CSS file
}
}
}//flowers_preprocess_page()
?>
Notice that $vars['styles'] is available to your theme's page.tpl.php and other page template files as simply
$styles.template.php
It's not very clear what actually needs to happen with template.php.
I got notices when subtheming Bartik: #922984: Undefined variable: in Bartik
So I first copied template.php from Bartik. The notices remained.
Then I emptied template.php. The notices remained.
Finally I replaced all function bartik_* with function mysubtheme_* and the notices disappeared.
If the latter is the right thing to do then it would be good to update the section about template.php. If it's not the right thing to do it would also be good to update this section, to clarify what exactly needs to happen with template.php.
guaka.org - CRM-CMS.nl
Getting similar using renamed Bartik in site-specific directory
I'm consistently getting similar errors on a local setup of Drupal 7rc4 when trying to modify a renamed copy of Bartik placed into my site-specific directory. If I try to show the site name and slogan in settings I get these errors, which don't show up on a fresh view of the home page (after cache clearing) but on subsequent pages, which could be because the error is reported in page-tpl.php?
Notice: Undefined variable: hide_site_name in include() (line 99 of [path to renamed Bartik theme in sites/site_directory]/templates/page.tpl.php).
Notice: Undefined variable: hide_site_name in include() (line 109 of [path to renamed Bartik theme in sites/site_directory]/templates/page.tpl.php).
Notice: Undefined variable: hide_site_slogan in include() (line 116 of [path to renamed Bartik theme in sites/site_directory]/templates/page.tpl.php).
line 99
<?phpif ($hide_site_name && $hide_site_slogan) { print ' class="element-invisible"'; }
?>
line 109
<?phpif ($hide_site_name) { print ' class="element-invisible"'; }
?>
line 116
<?phpif ($hide_site_slogan) { print ' class="element-invisible"'; }
?>
I've tried renaming the functions as suggested above, but I still get the same error. The colour information settings in the renamedbartik/color directory also don't come across, although the settings show up the way I want. I'm using a sites.php file to redirect Drupal to the sites_directory name I'm using, same as the production server.
problem fixed
Instead of copying the entire Bartik directory and renaming it, which produces endless problems as described in this thread, I set up a new subtheme based on Bartik, which got rid of all the error messages. I copied and renamed Bartik's style.css file into the new subtheme directory, and worked on the CSS that way. Now, all I need is to get the colour module working.
Use machine name (in D7)
If you are having trouble with inheriting from a theme, try changing the ParentName to parentname (i.e., the all lower case machine name)
http://horuskol.net/
Something wrong :(
Hello,
I built a theme and I need to redesign my site. The layout doesn't change but many other things do, so I want to build a subtheme from my origin theme.
I followed the instructions but something is wrong, the subtheme's css doesn't appear in source code of web page.
Can somebody help me?
Origin .info file:
; $Id: forher.info $
name = ForHer
description = "Custom design of my site"
version = VERSION
core = 6.x
engine = phptemplate
stylesheets[all][] = layout.css
stylesheets[all][] = html-elements.css
stylesheets[all][] = forher.css
Subtheme .info file:
; $Id: redesign.info $
name = ReDesign
description = "Redesign of my site"
version = VERSION
core = 6.x
base theme = forher
stylesheets[all][] = femcafe.css
I've made screenshot.png for the new design, it's visible in admin/build/themes and femcafe.css is exist in the subtheme's directory. The subtheme's directory is inside of the origin theme's directory. The origin theme and sub-theme are available in themes' list and the sub-theme is the default. But it's not work for me.
It only works in Block administration page (admin/build/block), when "ReDesign" is selected.
This *really* should be in a forum instead of documentation page
<soapbox>
Questions about how to do something should be located in the forums, not added to documentation pages. Comments here should be extensions of the page information, explanations, or notes about version and/or platform differences.
</soapbox>
----------
"Nothing is impossible - it just hasn't been done yet."
Cool Blue Interactive
Octobang
Theme settings set via
Is this true in Drupal 7? I've subthemed Marinelli 7.x without including theme-settings.php or a number of other .inc files, and they all seem to be automatically inherited...
Content doesn't match title
The title implies that this page explains how to create a subtheme; it doesn't.
This fine list of ingredients is missing its recipe. If all that's required for a subtheme is a folder in .../sites/[all, mysite ]/themes containing a .info file that points to an installed parent theme, then we should say so. If we were wiki'd up here, I'd have changed 'er myself.
CSS Inheritance
Inheritance for CSS means that as long as you don't put a file with the same new in your info file, the sub-theme would take the values from the original theme CSS.
Diseñador web basado en Costa Rica. www.comunicacionrapida.com
Sub-Theme CSS
I noticed if you follow these instructions, you have to place the same CSS from the base theme in your alternative sub-theme CSS file to retain the styling.
However, if you modify the .info file to list only a new .css file in the sub-theme's .css folder and either leave it empty or make your override/added styles in that file, it appears to retain all the styles from the base theme without having to actually have them in your .css file.
Seems easier to me. Here's what my folder looks like (bold are folders):
bigdaddy_kid
And in the .info file the only .css related line is:
stylesheets[all][] = mystyles.cssAnd initially mystyles.css is empty for me to add styles to my hearts content.
Seems to me this would allow me to completely update the base theme with no concern for my changes (unless id's or classes or something like that changed in the HTML).
For the gurus, am I correct in how this works?
Why would I not want to do it this way?
Shouldn't your css line in
Shouldn't your css line in the .info file be
stylesheets[all][] = css/mystyles.css? I tried to do exactly this (same folder structure and everything), but it wouldn't load my "mystyles.css" at all.edit: my mistake was a stupid one: I had actived the subtheme, but not made it default... :)
Thanks!
Thanks for clarifying the difference between theme functions and preprocess functions.
Blocks not available for subtheme
-replied to wrong node, apologies please delete
suggested edit of 'Creating a sub-theme'
Creating a sub-theme
The sub-theme to-be should be located in its own directory. Prior to Drupal 6, this directory had to be a subdirectory of its base theme; in Drupal 6 and 7 it can be placed outside of the base theme's directory.
To declare your theme to be a sub-theme of another, it is necessary to alter the sub-theme's xxx.info file. To do this add the following line to the sub-theme's xxx.info file, to declare its parent or "base theme." Change "themeName" to the internal name of the parent theme, e.g., bartik.info, (usually all lower case) and change the 'name' (if you have copied the xxx.info file) to 'base theme'.
base theme = themeName
cloudmaker
"it is possible to inherit color.module information"
Re: "Color and theme settings inheritance"
see also http://drupal.org/node/466268
Favicon Inheritance
The favicon doesn't get inherited in Drupal 6. We should add this to the screenshot and logo section.