This article introduces one of the most important topics in WordPress development: the WordPress template hierarchy. It’s one of the most important concepts in all of WordPress theme development.
Key Takeaways:
- The WordPress template hierarchy determines which PHP template files will be used to construct a given webpage on your site, based on the type of post content requested: for example, whether the webpage displays a Page, a Post, or an archive of many Posts.
- The template hierarchy follows a defined order set in WordPress itself. Learning this hierarchy will let you pinpoint which of your webpages will use which template.
As we work through this chapter, remember the following analogy: WordPress is a factory that processes raw material, posts, into finished products, webpages.
In this chapter, we’re in the stage of the production process where a bundle of posts has been fetched out of the warehouse, and are all ready to be assembled and made to display beautifully by our assembly line, the WordPress theme.
However, the theme provides a lot of possible lines to send those posts down: our different PHP templates. Putting our posts through index.php will result in a webpage that looks one way; putting it through home.php, archive.php, or page.php will give very different results.
How do we know which assembly line a given bundle will go down? With the WordPress template hierarchy. The template hierarchy is a built-in system in WordPress that specifies which line to send a given bundle of posts down, based on properties of the bundle itself.
This chapter explains how the template hierarchy makes its decisions.
index.php: The Ultimate Fallback
For the factory to work, there must always be at least one assembly line that can take any given bundle of posts. This is why every WordPress theme must have an index.php template file.
index.php is the final fallback. Whether you’re building a webpage around all the Posts you wrote in September 2016, or around a single Page, or around the results of a search for all the posts containing the phrase “snow tires,” or around one or more posts of a totally custom post type, such as Recipe or Movie Review, the rule is the same: If the template hierarchy doesn’t find something else to use, it falls back to index.php.
So WordPress can always build out a webpage using index.php if it doesn’t have a more fitting template file to use. However, it will try to find a better template file if one exists.
The Rest of the Hierarchy
WordPress has created some really powerful choice trees for deciding which template to display. From the Codex:
We won’t be including this in Resources, because it was created by the lovely Michelle Schulp, not us. You can view the full file on this page: https://codex.wordpress.org/Template_Hierarchy#Visual_Overview.To see what’s going on, let’s follow an example page from left to right on the diagram.
TRACING A SITE’S “ABOUT US” PAGE THROUGH THE TEMPLATE HIERARCHY
Let’s see what happens for an imaginary site’s “About Us” page, written as a Page and located at site.com/about.
Bundle Type: “Singular Page”
Starting from the very left of the diagram: what’s our “page type”? This question really means, “What kind of bundle of posts are we dealing with?” The answer is “Singular Page,” because the warehouse has sent us a bundle containing only one single post, rather than lots of posts together.
Static Page
Next up, we have two options: is this a “Single Post Page” or a “Static Page”? Don’t let the language confuse you: what they’re really asking is, “Is this a single post of type Post or of any custom post type, or is it a single post of type Page?” It’s the second one, which they’re calling a “Static Page.”
Page Template: Default Template
Okay, are we using a “Custom Template” or a “Default Template”? We’ll get into custom templates later, in Understanding and Creating WordPress Custom Post Templates. You can read this as, “Did you select something other than ‘Default Template’ in the Page Editor?”
Custom post templates
In this case, let’s say we’re not using a custom template on our “About” page. So the right answer for us is “Default Template.”
Template Used: page.php, with index.php Fallback
The next two nodes—page-$slug.php and page-$id.php—are little-used options that let you create templates for individual pages. We don’t have those, so we’ll skate right through them.
That leaves us with the template that will actually display our About page: page.php. And if our theme doesn’t have page.php, we’ll slide all the way back to our ultimate fallback: index.php.
We’ve just finished our first trip through the WordPress template hierarchy. Based on the number and type of posts we’ve retrieved from the database, we’re able to know exactly which of our PHP templates WordPress will rely on to build out the corresponding webpage.
A SECOND EXAMPLE: THE BLOG INDEX
Let’s take a second trip through the template hierarchy, this time with the site’s blog index page. This is the page on your website that displays your most recent Posts. But which page is this, specifically? It depends on your site’s settings in Settings > Reading:
If you leave the setting as its default, then your blog index is your site’s homepage: the webpage you see when you navigate to yourdomain.com.
However, you can also set your blog index to appear at the URL of an existing “static page”. Choosing a “static page” for your blog index page will change the blog index’s URL to something like yourdomain.com/blog, for a Page titled “Blog,” or yourdomain.com/news, for a Page titled “News.”
Whatever webpage your blog index is, WordPress knows when you’re visiting it, and it’ll fetch a bundle of your most recent Posts.
Bundle Type: “Blog Posts Index Page”
When this bundle hits the template hierarchy—starting from the left of the diagram—the hierarchy recognizes your “Page Type” as “Blog Posts Index Page.”
Template Used: home.php, with index.php Fallback
As you can see, this tree is simple: your blog index page will display the contents of home.php. If that doesn’t exist, it’ll default back to good old index.php.
Seeing the Whole Hierarchy
Are you starting to get how the template hierarchy works? Once you understand the basic concept, making WordPress themes that benefit from this knowledge simply requires creating and modifying the proper template files for the types of webpages you wish to affect.
The diagram above is great, but there are a few other great ways to visualize and understand the template hierarchy:
- Template Hierarchy on the WordPress Codex, at: http://codex.wordpress.org/Template_Hierarchy. The Codex is the canonical source for information on the template hierarchy, and on WordPress itself. Learn to love it! On this page, you can learn what each type of template file does.
- Interactive Template Hierarchy Resource, at: http://wphierarchy.com/. This is an interactive version of the Codex’s template hierarchy image. Click on any node to get help understanding what it means and when it applies.
- WPTuts+ Cheat Sheet, at: http://wp.tutsplus.com/articles/wordpress-cheat-sheets-template-heirarchy-map/. Especially if you understand WordPress conditional functions like
is_home(), we really appreciate the brevity of this visual map. It’s not exhaustive, but it’s easy to read.
Now You Understand the Template Hierarchy
The WordPress template hierarchy is a major part of the magic of WordPress themes and WordPress theme development. Now that you understand its basic workings, you can really dive in and understand exactly which templates apply in which cases.
GET RID OF THE GUESSWORK WITH WHICH TEMPLATE
One final recommendation: If you ever get stuck knowing which template is operating on a particular webpage, you can install a plugin: Which Template. It’s located at https://wordpress.org/plugins/which-template/. When you browse the site while logged-in, it prints the current template into your admin bar.
Which Template indicates that this webpage is using the active theme’s.
This plugin can be a great way to learn the template hierarchy in depth, as you see exactly which template is active at each part of your site.