How to create flexible WordPress Parent Themes

Very soon, child themes will be accepted in the WordPress Theme Directory. Child themes are themes that inherit the functionality of other themes and allow modifications and adding new functionality. The theme from which the child theme inherits the functionality is called a “Parent Theme”. The intention with child themes was to provide an easy way to customize themes without losing the customizations in case of an update. However, due to the way child themes are structured, they can also offer a way to extent the parent theme’s functionality. In the same way, due to the relationship with the parent theme, the parent theme can stand as a solid foundation for the child theme to be developed on, offering advanced levels of functionality, diminishing from the child theme’s development process.

Building parent and child themes can actually solve a lot of common problems for developers. For example if developing websites in WordPress and much of the code base repeats itself through projects, a parent theme could stand as a framework offering a starting point for development and a child theme could only take care of the customizations and project-related tasks.

However, since the parent and child theme are 2 complete separate themes that could be made by 2 different developers, several issues may be encountered while used together; for example a major update to the parent theme’s code could cause the child theme to break or one would need to duplicate an entire template file just to make a minor modification, thus losing its inheritance from the parent theme. In this article we will go through some techniques and best practices, that can make a parent/child theme relationship more flexible. First, let’s see the basic principles of this relationship:

Parent/Child Themes Inheritance

Basically, a child theme inherits all the template files from the parent theme, except the ones that can be found in its directory. For example, if the file style.css is found in the child theme’s directory, this one will be used as default stylesheet, all other templates being inherited from the parent theme.

The sole exception to this rule is the file functions.php, which is loaded both from the child theme and from the parent theme.

More about the parent/child theme relationship can be read at the Codex article about Child Themes.

Now let’s see some techniques that we can use when developing parent themes, so we can improve the theme development process of child themes:

Functions that retrieve Template Locations

When manually calling for different template files, it is important to know whether we want to call it from the parent theme or the child theme and if we need the local path to the file or the URI to it.

Normally, if we call a file internally in our request, like requiring a template file, we need the local path. If we call for a file to be displayed in the outputted document, like for example a favicon, we need its URI.

Important: These functions return the values, not echo them and retrieve the locations without a trailing slash (/).

These are the functions that retrieve the template locations:

get_template_directory() : returns the local path of the parent theme’s directory. We need this for example if we require theme theme’s options page. This is likely not to be overridden in the child theme. Example:

require_once ( get_template_directory() . '/theme-options.php' );

get_template_directory_uri() : returns the URI to the parent theme’s directory. We need this for example if we want to call a file that we no not want to be overridden in the child theme. For example, if we register an included JavaScript file:

wp_register_stcript( 'myscript', get_template_directory_uri() . '/scripts/myscript.js' );

get_stylesheet_directory() : returns the local path of the child theme’s directory if a child theme is active and of the parent theme’s if no child theme is active. We need this for example if we want to include template files from the child theme. Example:

include ( get_stylesheet_directory() . '/default-values.php' );

The example above is just for demonstration purposes. If you require a file from the child theme, it is recommended to include it with the function get_template_part.

get_stylesheet_directory_uri() : returns the URI to the child theme’s directory. Useful if we want to call a file like a custom stylesheet or a favicon, that is likely to be overridden by the child theme. Example:

<link rel="shortcut icon" href="<?php echo get_stylesheet_directory_uri(); ?>/images/favicon.ico" >

Pluggable Functions

Pluggable functions, are functions that can be overridden by the child theme, i.e. they can be rewritten to be different than the original. They can be added in the functions.php file (or other files included from this file) and the way functions can be made pluggable is by adding an existence conditional before declaring them. The template engine loads the functions.php file from the child theme first, and if the function is already declared, it won’t be loaded from the parent theme’s functions.php. Here’s an example of a pluggable function:

if ( !function_exists( 'mytheme_nav_menu' ) ) :
function mytheme_nav_menu() {
	if ( current_theme_supports( 'menus' ) ) :
		wp_nav_menu( array( 'theme_location' => 'primary_nav', 'fallback_cb' => 'wp_list_pages' ) );
	else :
		wp_list_pages();
	endif;
}
endif;

If a function called mytheme_nav_menu is found in the child theme’s functions.php, the one above will not be loaded. This way, certain functionality sections of the theme can be modified without the need to override complete template files. More about pluggable functions can be read at the Codex article Pluggable Functions.

Action Hooks

Action hooks allow several PHP functions to ‘hook‘ to them, and calls these function when the action hook is called. With the help of action hooks, instead of hard coding a functionality in the theme, it can be declared in a function and then hooked to an action hook. A function can be hooked with the function add_action:

add_action( 'mytheme_after_header', 'mytheme_nav_menu' );

In the example above, we have hooked the function mytheme_nav_menu to the action mytheme_after_header. Action hooks can have any name, but it is preferable that they have descriptive names. Action hooks are called with the function do_action:

do_action( 'mytheme_after_header' );

Functions hooked to this action will be called every time the statement above is called. For example if the statement above is called after the header section, then all function hooked to it will be called there and all output by these functions will be outputted there.

Any hooked functions can be removed with the function remove_action:

remove_action( 'mytheme_after_header', 'mytheme_nav_menu' );

If this function is called before the action hook is fired, the function mytheme_nav_menu will no longer be called, even though it has been hooked earlier.

This way, the theme’s content can be controlled through hooks and customized and overridden by child themes. If template files code is written well and the only PHP statements are calls to hooks in different common locations and all functionality is declared in the functions.php file, the customization possibilities are unlimited and the need to override template files is even more diminished. Action hooks are also useful if plugins require calls to functions from the theme’s template files. Instead of editing the template files, the functions can be hooked.

Action hooks and functions hooked to them also accept arguments and call hooked functions with certain priorities, more about it can be read at the Codex function references about add_action and do_action.

WordPress also has some predefined action hooks that fire at certain moments during a normal request, more about action hooks can be read at the Codex articles about Actions and Action Reference.

Filter Hooks

A filter hook, takes a value that has been passed to it, passes it through all functions that have been hooked to it and then returns the value. This is useful if we want to allow customizing content before outputting it. Let’s take the example of a static footer code and see how this can be customized using filters:

<p>&copy; My Website, All rights reserved</p>

Now, instead of hard coding it into the footer, we can insert it into a string variable and pass it through a filter. The function which passes a variable through a filter is apply_filters:

<?php
	$copyright_text = '&copy My Website, All rights reserved';
	$copyright_text = apply_filters( 'mytheme_footer_copyright', $copyright_text );
?>
<p><?php echo $copyright_text; ?></p>

Now let’s pass this string to a function that also adds the word “Copyright” before it. A function hooked to a filter must accept the value as an argument and is hooked to the filter with the function add_filter:

function mytheme_add_copyright( $input ) {
	$copyright  = 'Copyright ';
	$copyright .= $input;
	return $copyright;
}

add_filter( 'mytheme_footer_copyright', 'mytheme_add_copyright' );

Now the final output of the footer text will be:

<p>Copyright &copy; My Website, All rights reserved</p>

If every outputted content would be passed through a filter, customizing the theme’s content would be much easier. WordPress has some predefined filter hooks, more information about filter hooks can be read at the Codex articles about Filters and  Filter Reference.

The strength of the parent theme can also be improved by adding functionality such as shortcodes to enlighten access to several functions and to allow insertion of certain content inside posts, theme options to allow as much customization of the theme as possible and intensive documentation on how to use and to develop upon the parent theme. A good practice is also to provide backwards compatibility when updating versions or adding functionality and to frequently check the child themes for compatibility issues.