Jess G's BlogTutorials and Random Thoughts

WordPress Template Include: An Explanation on Template Inclusion for Themes and Plugins

get_template_part() and get_query_template() both use locate_template() to find and load a specified template from your theme, or in some instances, your plugin. I've worked on projects where I've either used all three of these functions — or have seen them all used — in different places and different ways. To other developers, this may seem like a lack of consistency but it really isn't. Each function has their use for a particular scenario and in this blog post, I'll make a (half-assed) attempt to clarify.

The root: locate_template()

This function is located in wp-includes/template.php @ line 368 (as of v3.5.1). A quick review of this function reveals that what it does is loop through an array of templates, and looks for these templates in one of the two specified paths: STYLESHEETPATH or TEMPLATEPATH. Depending on how the two optional parameters are set, you can either have the template load (via load_template()) or simply return the template-path.

Next: get_template_part()

This function was introduced in v3.0. What get_template_part() does is load a template based on a slug and an optional name. The slug allows you to categorize template parts. A good example is post formats. You may have an aside template, gallery template, etc. A good naming convention for these types of templates would be format-aside.php, or format-gallery.php. In your theme, you would these templates like so: get_template_part('format', 'aside'). One advantage of get_template_part() is that it creates an action when the template is loaded: get_template_part_{$slug}. This action allows plugin developers to extend get_template_part(). The best usage for get_template_part() is in your theme template files, when you don't have to pass data between templates.

What about get_query_template()?

This function has been around since v1.5. This is the main function that handles the kind of template that is served up during a query. For example, a request for a single post will trigger a call to get_single_template(), which in turn calls get_query_template() by passing two parameters: the name of the queried template (in this case "single") and an array of php files. The call to get_query_template() creates a filter that calls locate_template(). The filter created is named after the template query, example: single_template. You can see for yourself what is going on in get_query_template().

So Which One Do I Use?

A way to determine which function to use is this: are you in a theme template (header.php, category.php, etc.) or inside a function?

  1. If you answered "inside a theme template" then get_template_part() is the best way to go.

  2. If you answered "inside a function", then locate_template() would be the better option.

The reason for using locate_template() inside a function is that you may find yourself in a situation where you may be outputting markup but also a) wish to keep the markup separate from your function (ie: separation of concerns), and/or b) would like theme authors to override this markup in a child-theme by providing a template. Why not use get_query_template()? Because the functions that call get_query_template() are used to call query-related WordPress templates. While calling get_query_template() does create an action hook that can be extended by other plugins, you can also achieve the same result by adding a do_action() call in your function that calls locate_template(). However, adding custom hooks and filters is a topic for another post.