Download this Chapter as a PDF
If you’d like to read the chapter as a PDF from the e-book, feel free to download it here. Enjoy!
About Up and Running
In Up and Running, we give this chapter’s detailed treatment to all the key concepts of WordPress development. If you’re interested, check it out! And we agree with a buyer tweet from last week:
If anyone is on the fence about “Up and Running”, don’t be! The vids and eBook are incredibly helpful for new devs!
Key Takeaways:
- A child theme is a specially registered WordPress theme that inherits most of its properties from a declared parent theme. A major reason to create a child theme is to be able to update the parent theme without losing desired customizations.
style.css
is the only mandatory file in a child theme. The general rule is that child theme files override parent theme files if they exist.- To properly use child themes, you’ll need to know how to include the parent theme’s
style.css
; how the WordPress template hierarchy responds to child themes; and under what circumstances you can overwrite existing functions infunctions.php
.
A WordPress child theme is a WordPress theme that depends on a “parent” theme—which could be any other theme already in existence, as long as that theme isn’t itself a child theme.
A child theme inherits everything about its parent—and then it only changes what it needs to change. So you could set up a child theme that’s identical to its parent, simply by importing the parent theme’s stylesheet (we’ll cover that later) and making no other changes.
Why Use a Child Theme?
If you make changes to a WordPress theme, and then update the theme, you lose your changes.
Themes often update, and for very good reasons: important new features, bugfixes, and (especially) crucial security patches, as well as other reasons. There’s no way to update “just part of” a theme—so if you make changes to a third-party theme (say a commercial theme) and then update that theme to a new version, your changes are gone.
Child themes let you make only the changes you need to make, all while letting the parent theme continue to update under you. This is the major reason why they exist.
As you get used to working with child themes, you’ll discover another reason to use them: they’re really convenient. It’s much easier to write only the changes you need to a clean file (for example, style.css
or functions.php
) than it is to dive into an existing theme and start pulling wires. So child themes are not only necessary, they’re nice.
How to Make a Child Theme
To make a child theme, you create a new theme. Normal themes (themes that can become parent themes) have two required files: style.css
and index.php
. Child themes, however, have only one: style.css
. This is because they inherit the parent’s index.php
by default.
Registering a Child Theme and the "Template: "
Line
Child themes are registered like normal themes, in a comment block in style.css
. There’s one new field, though: Template:
. This line is mandatory for every child theme, and corresponds to the name of the folder in which the parent theme is located.
Here’s an example child theme comment block:
/*
Theme Name: Twenty Fifteen Child
Theme URI: http://upandrunningwp.com/
Description: Child theme for the Twenty Fifteen theme
Author: WPShout
Author URI: http://wpshout.com/
Template: twentyfifteen
Version: 1.0.0
*/
This goes in style.css
in a new theme folder:
And gives this result:
Notice, again, that the parent theme’s “nice name” is Twenty Fifteen, but the name of its directory is twentyfifteen. That’s the one we need to write after Template:
.
Pulling in the Parent Theme’s Stylesheet
If we activate our Twenty Fifteen Child theme right now, our site won’t look anything like Twenty Fifteen. On the contrary, it’ll look like an absolute disaster:
Why? Because WordPress is no longer listening to the parent theme’s style.css
. The child’s style.css
is the primary stylesheet for the site now—and since it has nothing in it, the site looks (and is!) totally unstyled.
There are several good ways to solve this problem; we’ll cover two.
Option One: @import
ing the Parent Theme’s style.css
from the Child Theme’s style.css
This first solution is a single line in the child’s style.css
:
@import url("../twentyfifteen/style.css");
That’s better! This simply uses CSS’s @import
directive to pull all the contents of the parent theme’s style.css
file into your child theme’s style.css
. Now your site’s looking the way it did before, and you can write your own styles below.
Option Two: enqueue
ing the Parent Theme’s style.css
in the Child Theme’s functions.php
This solution uses a good old wp_enqueue_style()
call, in the functions.php
of the child theme:
/* Environment: functions.php of a child theme whose parent is twentyfifteen */
function wpshout_enqueue_twentyfifteen_stylesheet( ) {
wp_enqueue_style(
'twentyfifteen',
get_template_directory_uri() . '/style.css'
);
}
add_action( 'wp_enqueue_scripts', 'wpshout_enqueue_twentyfifteen_stylesheet' );
One thing to note here is the use of the function get_template_directory_uri()
. This function refers to the root directory of the current theme if called in a normal theme, and to the root directory of the parent theme if called in a child theme. So with this function you don’t always know whether you’re talking to your own theme or its parent—not too useful in general, but it’s what we need here, since we for sure want to be talking to the parent.
Why would you load the parent’s style.css
in this way? The PHP route turns out to be a little bit quicker, because CSS @imports
force additional server requests. Remember, it’s your browser, not the server, that can figure out what @import
even means. When it does, it has to then turn around and ask the server—a second time—for the stylesheet it’s supposed to be @import
ing.
This performance differential is not usually crucial for most websites and most hosting environments, so either of these methods is a great way to get your parent themes loaded up. However, because of its better performance, the wp_enqueue_style()
solution is better coding practice, so we recommend you use that when possible.
How Child Theme and Parent Theme Files Interact
We’ve already seen that the child’s style.css
takes over for the parent’s. Let’s look more closely at an important question: under what circumstances do the child theme’s files substitute for the parent theme’s?
Here’s a diagram that breaks that question down for each piece of a child theme:
In most cases, child theme files simply override identically-named files in the parent.
In most cases, child theme files simply override identically-named files in the parent. The two noteworthy exceptions are:
- Files in the WordPress template hierarchy
functions.php
Files in the WordPress Template Hierarchy
When you add a child theme, WordPress still steps through the template hierarchy as it always does, with one difference: at every step in the hierarchy, it first checks in the child theme, then in the parent theme.
Traversing the Template Hierarchy with a Child Theme: A First Example
Let’s say we’re about to display our About page, a post of type Page. This Page’s slug
is about
and its id
is 2
.
In this example, let’s say that the parent theme has two template files: page.php
and index.php
. The child theme has just one template file: index.php
.
Here’s how WordPress will decide which template to display:
page-$slug.php
:- Does the child theme have a file named
page-about.php
? (No) - Does the parent theme have a file named
page-about.php
? (No)
- Does the child theme have a file named
page-$id.php
:- Does the child theme have a file named
page-2.php
? (No) - Does the parent theme have a file named
page-2.php
? (No)
- Does the child theme have a file named
page.php
:- Does the child theme have a file named
page.php
? (No) - Does the parent theme have a file named
page.php
? (Yes)
- Does the child theme have a file named
In this case, WordPress will use the parent theme’s page.php
template to display the page.
A Second Example
Now let’s imagine the same situation, but that the child theme does have a page.php
as well:
page-$slug.php
:- Does the child theme have a file named
page-about.php
? (No) - Does the parent theme have a file named
page-about.php
? (No)
- Does the child theme have a file named
page-$id.php
:- Does the child theme have a file named
page-2.php
? (No) - Does the parent theme have a file named
page-2.php
? (No)
- Does the child theme have a file named
page.php
:- Does the child theme have a file named
page.php
? (Yes)
- Does the child theme have a file named
In this case, the child theme’s page.php
will override the parent’s, and WordPress will use the child’s page.php
to display the page.
functions.php
A child theme’s
functions.php
loads before its parent’s.
functions.php
is a very special case: it loads before the parent’s functions.php
. Depending on how the parent theme is written, this can play out in two very different ways:
Themes with Pluggable Functions
Careful parent theme authors use
function_exists()
checks to let the child’sfunctions.php
overwrite specific parent theme functions.
PHP has a function titled function_exists()
. Much like WordPress’s conditional tags, it returns a boolean—either true
or false
—depending on whether the function it’s given to look for exists or not.
Careful parent theme authors wrap all their functions in if ( ! function_exists() ) {}
. In plain language, this means “if function doesn’t exist”: the !
means “not,” and so the if-statement is false
if the function does exist, and true
otherwise. Theme developers use it as follows:
/* Environment: Parent theme's functions.php */
// Only run if wpshout_filter_example() does not already exist
if ( ! function_exists( 'wpshout_filter_example' ) ) {
function wpshout_filter_example( $title ) {
return 'Hooked: '.$title;
}
add_filter( 'the_title', 'wpshout_filter_example' );
}
if ( ! function_exists( ) )
checks create what are called pluggable functions.
This creates what are called pluggable functions: functions that the child theme’s functions.php
can overwrite. How does the child theme overwrite them? Simply by registering those functions, since the child’s functions.php
executes first! So the child theme author could write:
/* Environment: Child theme's functions.php */
function wpshout_filter_example( $title ) {
return 'Hooked by Child! ' . $title;
}
add_filter( 'the_title', 'wpshout_filter_example' );
Here, the child’s wpshout_filter_example()
will execute—and the parent’s won’t, since ! function_exists( 'wpshout_filter_example' )
now evaluates to false
.
How to Work With Parent Themes That Don’t Use Pluggable Functions
This situation makes life more difficult for child theme authors. Let’s take our same example: the child theme functions.php
registering a function called wpshout_filter_example()
that also exists in the parent theme’s functions.php
.
The child theme’s function registers just fine. Then, the parent theme’s functions.php
registers a function by the same name.
PHP really doesn’t like this. Here’s a real-world example, using a Twenty Fifteen function and a child theme of Twenty Fifteen:
So if the parent theme isn’t doing function_exists()
checks, you need to avoid duplicate function names at all costs.
This also means that any custom PHP functionality the parent theme adds is simply bound to execute. If you want to change or remove pieces of that functionality, you’ll have to do so manually, one step at a time, by writing your own functions that dequeue
unwanted stylesheets, and so on.
What We’ve Learned
We now know the basics of child themes, and how and why to use them. To change existing themes—for example, commercial themes on client sites—you’ll be using child themes constantly, so this is a really great piece of knowledge to have under your belt.
And if you like this style of presenting WordPress development, there’s a whole lot more where that came from in Up and Running. Each chapter also ends with a limerick and a quiz, so let’s get into those!
Summary Limerick
When child themes are born from their parent,
The family ties are apparent:
What they don’t override
It will swiftly provide,
So inheritance comes in inherent.
Quiz Time!
- Child themes exist so that:
- Theme customizations can persist when the themes themselves update
- People without technical expertise can easily customize themes
- Themes are easy to restore should they become lost or corrupted
- It’s possible to make the following themes into parent themes:
- Specially coded existing themes
- Existing themes with a
functions.php
- Any theme that is not already a child theme
- If a child theme author names a function identically to a function in the parent theme which is not wrapped in a
if ( ! function_exists() ) {}
check, then:- Both functions will execute
- Neither function will execute
- PHP will throw a fatal error
Answers and Explanations
A.
Theme updates often provide needed security fixes as well as new features, and would overwrite theme customizations without the child theming process.C.
There are no special requirements for parent themes; however, there are no “grandchild” themes.C.
PHP cannot process duplicate function names. With theif ( ! function_exists() ) {}
check, the child theme’s function will execute and the parent theme’s will not; this allows child theme authors to selectively replace parent theme functions, which is why
is good practice in theming generally.if ( ! function_exists() ) {}
[…] It’s in need of some brushing up, but for now you’ll be adequately served by these two articles on WPShout or this one on the WordPress.org […]
[…] show you how this works, I took two screenshots in sequence on a theme that is a child theme of Twenty Sixteen and so inherits its sizes rules. This was the first screenshot, before creating […]
[…] WordPress Child Themes: A Complete Guide to the Core Concepts – If you make changes to a WordPress theme, and then update the theme, you lose your changes … than it is to dive into an existing theme and start pulling wires. So child themes are not only necessary, they’re nice. […]