Parent and Child Themes

From Habari Project

Jump to: navigation, search

In Habari it is possible to create a parent theme that contains the bulk of the behavior of a theme, and then define a separate child theme that inherits the properties of that theme but enhances them with its own templates and capabilities.


Creating a Parent Theme

Creating a parent theme requires no special components. Any theme can be a parent theme to another theme; However, depending on how the theme is built, the difficulty of implementing child themes based on that parent theme may increase.

There are certain things one should keep in mind if attempting to produce a theme explicitly for use as a parent theme:

Creating a Child Theme

At its core, creating a child theme is as simple as adding a single element to the theme's XML file. When this element is present, the child theme will require that the parent theme is present for Habari to activate. To create a child theme, add this element to the child theme's xml file, where "Theme Name" is the name (defined in the parent theme's XML file) of the parent theme:

<parent>Theme Name</parent>

Files Used By the Child Theme

Child themes require only the theme XML file to function. No other file is required, but it may be useful to duplicate some files from the parent to the child.


Within the theme XML file, areas are normally defined. If the child theme uses the same areas as the parent theme, these areas must be defined in the child theme file, as the child theme does not inherit area information automatically from its parent. In this way, areas that are in the parent theme can be made unavailable in the child theme, or new areas can be added to the child theme (which would then be defined in new templates that the child theme provides).

Also in the theme XML file, feature requirements and recommendations are normally defined. Similar to area definitions, child theme requirements are not inherited from the parent. If the parent theme requires a certain feature, it's very likely that the child does too, unless the child theme provides code that makes those feature requirements unnecessary. In that case, the requirements should be duplicated form the parent to the child.


If no theme.php file (or the class file defined in the theme XML file) exists for the child theme, then the theme.php file from the parent is used. If the child theme provides a theme.php file, then it is instead of the parent's theme.php file, if it exists. It's worth noting specifically that parent themes might not have a theme.php file at all, intending to leave the theme class implementation entirely to the child theme.

If the child theme implements a theme.php file, and it has a parent that includes a theme.php file, it is possible to retain the features provided in the parent only if the child theme class extends the parent theme class. For example, if the parent theme class is Wazi, and the child theme class is Izaw, and the author of Izaw wants to use the features provided by the Wazi class, then the implementation of Izaw needs to be as follows:

class Izaw extends Wazi { ... }

Normally, the custom theme class would extend Theme, but in this case, it extends the parent theme, giving the child theme access to all of the functionality provided by the parent. Child themes can extend the base Theme class if they do not wish to inherit any of the theme.php functionality provided by the parent theme.


Themes may provide a sub-directory named "assets". Within this directory, theme authors can place css and js files, which will be automatically added (in alphabetical order) to the appropriate stacks for output.

If the parent and child both include files from this directory, all of the files are used from both themes' assets directories. Files in the child theme's assets directory will not override files from the parent theme with the same name.

Template Files

When a theme runs, the template files from the parent theme are used unless there is an identically-named template file in the child theme's directory. If the template file exists in the child theme, the child theme's template file is used to render the output instead.

Non-Template Files

Template files are easy to manage between parent and child themes, because when rendering templates the system can search both directories and procure the correct file to work with. Files such as images are not as easy to locate, since they are referenced from the rendered templates in the browser.

In order to correctly source a file for output, the get_url() function must be employed. For example:

<img src="<?php echo $theme->get_url('images/logo.png'); ?>">

The above code causes the theme system to look for the file 'images/logo.jpg' in the currently active theme directories (whether parent or child) and return the child theme's version if it exists, or default to the parent theme's version.

Note that well-built parent themes will use this method in their templates even though the URL of the files may be well-known, since it will allow child themes to override the referenced files without copying and altering the template file, as would be required if get_url() was not used (and a fixed URL was used instead) in the parent theme's template file.

Personal tools