Understanding get_template_part

If you’re creating WordPress themes you surely came across the get_template_part function at one point or another. It’s one of those hidden gems inside of WordPress that don’t get the attention they deserve. Let’s change that.

The get_template_part function is essentially a PHP include or require, on steroids:

• It already knows where your theme is located and it will look for the requested file in that theme’s directory
• It doesn’t issue a warning or fatal out if the requested file does not exist
• It can search for other suitable files, if the requested one is not found
• It knows about child themes and parent themes

Long story short, the get_template_part function allows you to break your theme down into smaller templates (or template parts), which can be reused across your other templates.

Although get_template_part is similar to a PHP include or require, you should not use it to include things like your theme options code, sidebars registration, custom widgets, etc. The get_template_part function should only be used to get template parts.

Let’s start off with some basic examples.

Basic Usage

Suppose we have a theme that has some post navigation elements above the post and below it. Let’s grab that and put it in a navigation.php file instead. Now, whenever we want to render our post navigation, all we would do is:

get_template_part( 'navigation' );

Which will load our navigation.php file if it exists. That’s fairly simple, right? Let’s add a little more spice to that. Since our post navigation goes above and below the post content, let’s add the second argument to get_template_part:

get_template_part( 'navigation', 'above' );
// post content goes here ...
get_template_part( 'navigation', 'below' );

The first call will look for navigation-above.php in our theme folder, and if that doesn’t exist, it will fall back to navigation.php. Similarly, the second call will look for navigation-below.php and fall back to navigation.php.

Pretty slick, eh? But the real power of get_template_part lies within the child themes model.

Child Themes

If you’re not familiar with the child themes model in WordPress, I strongly recommend you refer to the Codex. In a nutshell, a child theme may override the template files in your parent theme with their own, thus making modifications to the original theme without changing its source code or structure.

The get_template_part function plays quite an essential role in the child themes concept. Let’s go back to our first example from earlier:

get_template_part( 'navigation' );

As I already mentioned, this will look for a template file called navigation.php. However, if we’re in the child theme context, meaning a child theme is activated, such a call to get_template_part will look for navigation.php in our child theme first. If navigation.php is not found in our child theme, it will load the one in the parent theme. Makes sense?

Now comes the tricky part:

get_template_part( 'navigation', 'above' );

In a child theme context, this will look for the following templates in the following order:

1. navigation-above.php in the child theme
2. navigation-above.php in the parent theme
3. navigation.php in the child theme
4. navigation.php in the parent theme

The order is pretty important and something you should keep in mind.

Given this fallback model, it’s pretty common to use non hard-coded values with get_template_part in themes. For example:

get_template_part( 'navigation', get_post_type() );

Where get_post_type() will return the name of the post type that is currently shown, so if we’re on a Post, it’ll attempt to load navigation-post.php and fallback to navigation.php. If we’re on a Page, navigation-page.php and navigation.php. If we’re looking at a custom post type, say a Book, it will look for navigation-book.php and fall back to navigation.php.

A more common use case is post formats, with the post’s content area extracted into a template part of its own, like this:

get_template_part( 'content', get_post_format() );

Which will attempt to include content-gallery.php for gallery post formats, content-quote.php for quote post formats, and so on. If the particular file doesn’t exist, it will fall back to loading content.php. You can see this approach in action in the Twenty Eleven and Twenty Twelve themes.

Even if your theme does not include template files for all available post formats, it’s okay to follow this model, because a child theme might, and if it doesn’t, WordPress will just resort back to content.php.

Under the Hood

The real power of get_template_part comes from a function called locate_template, which does the whole searching in parent theme and child theme folders, and the reverting to other templates in a stack. The get_template_part function simply builds an array of templates for locate_template to look for. Here’s a quick example:

get_template_part( 'one', 'two' );

Creates an array of “one-two.php” and “one.php” (in that specific order) and passes it on to locate_template, which then loops through that array and looks for the files in the child and parent themes directories. The order is really important here, it’s kind of why file names have priority over their locations (parent theme or child theme) and explains the reason behind the lookup sequence.

It’s also worth noting, that functions such as get_header, get_sidebar and get_footer are very similar to get_template_part with a sort of hard-coded first argument.

At the time of writing, get_template_part is located in wp-includes/general-template.php and locate_template is in wp-includes/template.php.

Well, that’s about it folks! You should now be the master of the get_template_part voodoo, and now that you’re using it in your themes, you should get approximately 74% more sales. If you have any questions, go flood the comments. Take care!