Day 2: Creating a WordPress Child Theme the smart way

Over the last year I’ve had a lot of people inquire about how to build WordPress child themes, especially now that twentyten has become the new baseline standard for WordPress themes. I’m working on a huge child theme tutorial project that will be released some time in Q1 2011, but for now here is a quick and dirty rundown of some of the tips and tricks I’ve uncovered while working with child themes and how I create child themes the smart way.

What is a child theme and why should I build one?

A child theme is a theme that piggybacks on top of a parent theme. By that I mean a child theme uses the power of the parent theme to get things done and only adds differences and alterations where they are needed. The result is that whereas if you were to build a theme from scratch you’d have to include all the default files (header.php, footer.php, sidebar.php, functions.php, index.php, page.php, single.php, category.php, style.css etc etc) just to get it working, when you build a child theme you technically just have to add a new style.css file in a dedicated folder and you’re good to go. The benefit of using a child theme is twofold: First off you let the parent theme do all the heavy lifting while your custom child theme just makes small alterations, and secondly if there are any major changes to WordPress or the parent theme, these can be installed without putting your child theme in danger. That means you can stay current while still retaining control of your custom theme. Pretty nifty. So why should you build one? Because it’s much easier than building a theme from scratch.

Setting up a custom child theme in a snap

Creating a new child theme is incredibly easy. All you have to do to get started is to create a new folder in the Themes folder in your WordPress installation (yourdomain.com/wp-content/themes/), give the folder the name of your new child theme and create a blank style.css file inside that new folder. Once this is done, open the style.css file in your favourite web development application, HTML editor or Notepad and enter the following lines of code:

/*
Theme Name: YourChildThemeName
Theme URI: URL to a page about your child theme if you plan on publishing it
Description: A description of the child theme and its features - can include HTML and links if you want.
Author: Your name and usually a head nod to whomever built the theme you are basing your child theme on
Version: Version number
Template: twentyten <-- the name of the parent theme - for this example it is twentyten
Tags: If you want to you can add tags
*/

Of course you’ll need to customize this info to make it fit your theme. The only mandatory fields here are Theme Name, Description, Version Number and most importantly Template. It is the Template variable that tells WordPress what parent theme this child theme is based on. For our example we’re going to use twentyten because it’s a solid theme to build a child theme on.

So how does a child theme work?

If you customize the block of text above, save the style.css file and upload this new folder to your WordPress installation you’ll see that your new child theme now appears as a selectable option under Appearance -> Themes. But if you activate it you’ll end up with a site that has no style at all – just a default top-to-bottom text layout. That’s because the new style.css file you created overrides the parent theme style.css file, and since you haven’t inserted any style code there is no style.

Now here’s why I say I’m going to show you how to do this the smart way. Your first instinct is probably to go to the parent theme style.css, copy all the style code and just paste it into your child theme style.css. And you can do that if you want to. But what if a new version of your parent theme comes out that has all new style code? Then you have to do the whole process again, and you’ll lose all your customizations in the process. This is not ideal and kind of defeats the purpose of a child theme. I have a better option.

@import to the rescue

The name Cascading Style Sheets is actually a very descriptive name. Cascading Style Sheets work on a cascade principle meaning whatever appears further down in the cascade overrides what happened before. As a basic example if you make a style sheet with three p styles like this:

p { color: blue; }
p { color: pink; }
p { color: red; }

all paragraph text would come out red every time. And if you cut line two out and placed it on the bottom all paragraph text would come out pink. We can use this to our advantage when working with child themes.

Rather than copying all the style code over, we’re going to import it and use it as is unless we want to change it. To do this we use a simple function called @import. It looks like this:

@import url('../twentyten/style.css');

where “twentyten” can be swapped out for the folder name of your parent theme. This function imports the style.css file found under the twentyten folder one folder down from your child theme folder (so in the wp-content/themes folder) and applies it to the page. What you want is for the parent stylesheet to be applied at the top of the cascade so you place this line of code at the very top of your child theme style.css file before the theme definition (you can safe it and put it underneath if you want, makes no difference). If you do this you’ll see that all of a sudden your child theme looks exactly like the parent theme.

Now you can use the cascade effect to change, add to or override any of the defined styles in the parent stylesheet without actually touching it. All you have to do is add a new instance of the style call in your new style.css file and insert the code you want. Foolproof and very simple.

But I have something even better! I’ve created a custom style.css file specifically for twentyten child themes that carries with it not only the import code for the original twentyten stylesheet, but also a complete set of every style call in the original stylesheet without any actual style code. That way if you leave it as is you’ll have the look of twentyten but if you want to change something you can do it in the new stylesheet without having to copy over a single line of code. I’ve also added a more robust CSS reset in the new file for good measure.

You can download this custom style.css file right here.

Style.css is just the beginning

Using the new style.css file you can take control of the style of your WordPress site and make pretty extensive changes, but you’re still stuck with the overall theme structure of twentyten. To go further you need to start adding theme files of your own to the child theme. This is a fairly simple process of copying the original theme file – say page.php – from the parent theme into your child theme folder and making changes to it. WordPress automatically picks the theme file in the child theme folder over the parent theme file so it doesn’t require further configuration. The same thing goes for custom theme files like category-specific files (to target a specific category simply make a new file called category-X.php where X is the category number) and custom headers, sidebars and footers (you can call custom header, sidebar and footer files by changing the call to get_header(‘custom_name’); and creating a new file called header-custom_name.php).

But there is one caveat (well, actually there’s two, but the second one has a whole sub-section below): If you do any custom source calls in your header.php or any other files – for example a call to a second stylesheet, JavaScripts or some other element – to files contained within your child theme folder you can’t use the standard

call to generate the theme folder URL. This call targets the parent theme folder. To target the child theme folder you need to change it to

It’s a subtle difference but it drove me insane until I figured it out.

Functions.php is a special case

So style.css is dead simple, the other theme files are relatively simple, but what if you want to add, modify or remove functions from functions.php? That’s where things get interesting. For some reason whereas all the other files simply override the parent theme files, the parent functions.php file is called after the child theme functions.php file. As a result if you create a duplicate of functions.php in your child theme folder and make changes to it, those changes will be overridden by the functions.php file in the parent folder. Weird.

To fix this you need to call the parent theme functions, then deactivate them and then create a new function to replace the old one. It’s a bit of a hassle but here’s an example: I want to add a secondary menu to the footer of my theme. Twentyten has only one custom menu defined so I need to add a second menu to the functions.php file. If I was working in a regular theme all I’d have to do was add that new menu in the array like this:

register_nav_menus( array(
	'primary' => __( 'Main Menu Navigation', 'twentyten' ),
	'secondary' => __( 'Footer Menu Navigation', 'twentyten' ),
) );

But if I add this code to my child theme functions.php file it will simply be cancelled out by the parent theme function. So to get this to work I have to first create a function that removes the original function, then tell WordPress to run this remove function only after the parent theme functions.php has been set up, and finally call our new function. It’s convoluted as hell and the end result looks like this:

// Remove the default 'register_nav_menus' function
function remove_register_nav_menus() {
    remove_action( 'twentyten_setup', 'register_nav_menus' );
}

// Call 'remove_register_nav_menus' (above) during WP initialization
add_action('after_setup_theme','remove_register_nav_menus');

// Register new 'register_nav_menus' function by running 'register_nav_menus' on the 'twentyten_setup' hook. */
add_action( 'twentyten_setup', 'register_nav_menus' );

// This child theme uses wp_nav_menu() in two locations.
register_nav_menus( array(
	'primary' => __( 'Main Menu Navigation', 'twentyten' ),
	'secondary' => __( 'Footer Menu Navigation', 'twentyten' ),
) );

This method can be applied to most of the functions in the twentyten theme. Fortunately for some of the functions twentyten has filters built in you can hook into without doing this whole unregistering and reregistering process. To figure out how these work just read the functions.php file – it’s all explained.

I could write a whole book on how to mess with functions.php to get it to do your bidding but for now I think this will suffice. This should give you a solid base to start building child themes, so get cracking.

This tutorial is part of the 24 Days of WordPress series. If you want to learn more about WordPress and Expression Web check out the Sams Teach Yourself Microsoft Expression Web in 24 Hours series (version 2, 3 and 4), Lynda.com’s WordPress 3.0 Essential Training course and Microsoft Expression Web 4 LiveLessons.