One of the simpler and more powerful concepts that runs underneath WordPress themes is that of the template hierarchy. It’s super powerful and can make your life much easier as you build out a theme for your site. And it’s not all that complex, so once you get the idea you’ll find working on themes much easier.
The Problem that Leads to the Hierarchy
WordPress wants to solve two problems with its themes: make them easy to customize and hard to break.
Broadly, WordPress wants to solve two problems with its themes: make them easy to customize and hard to break. Obviously both of these are part of what makes WordPress great — its themes end up having both of those qualities — but balancing them is something that takes some thought and insight.
To make themes hard to break, WordPress makes it such that every template for every page on the site uses the same structure — the concept of The Loop, about which I’ve written an introduction if you’re curious. This abstraction makes it easy for WordPress to know with a fair certainty that any given template file can render any given content.
This dependence on The Loop — which should always exist in the
index.php file of your WordPress theme — allows WordPress to use it anytime it doesn’t have a more fitting file to use to render the page content it needs to. This is why a WordPress theme is hard to break — because even for obscure new content types WordPress will always be able to count on that
index.php file being there to catch and render it.
To make WordPress easy to customize, WordPress has built up a large choice-tree on top of
index.php. It can take it for granted that
index.php will be there: but it’ll try to find a better template file to use if it exists. This means that if I want to change the page layout for when I have a single post, for example, I can just make a file called
single.php, with The Loop inside of it, and WordPress will use that when it thinks there’s only one post on the page. This is powerful.
The Dynamics of the Template Hierarchy
As we’ve said, WordPress has built up — using the concepts of The Loop, and it’s certainty that it can always fall back to
index.php if it needs to — into some really powerful choice trees. Let say you want to customize the way your category archive — the listing of multiple posts from a single category — will look. If you’ve got an
index.php in place, the first option you have is that you could use
archive.php. This is the template that WordPress uses for any archive, so you could customize that if you also want this view to be used when your visitor clicks onto tags or month archives as well.
If you don’t like that, we can then continue down the path: the next option is that we can make a
category.php. This is the one we want for the project I described at the outset: it’ll be used for any category archive, but only for a category one. Month or tag or any other type of archive will not use it, but all categories will.
But if you now decide that not only do you want most of your categories to use it, but you’d like some special category to look different than that — we’ll use Poems as an example — you’ve got a few more options. You can create a new template file as
category-poems.php or, if you figure out the category number,
category-32.php, and WordPress will use that to render the view when someone click a link to your poetry category.
This simple dynamic is, as you may be able to imagine, really powerful. Customization and improvements can be made on the fly as you build out a WordPress theme. Start with a simple
index.php, get it set up just how you like, and then tweak it for all the different ways that WordPress will possibly find itself displaying your content.
Seeing the Whole Hierarchy
Once you understand this concept, making WordPress themes that benefit from this knowledge is simply a matter of filling out your knowledge of the specific template file you can make to replace the way your theme template hierarchy is currently cascade and which file you can replace.
Listing out the specific layout of each tree that WordPress looks at for each type isn’t all that useful here, so I’ll refrain. I promise it’d only bore both of use. But there are a few exemplary ways to see and understand this data when you need to reference it, so I’ll point you to them for further study:
- Template Hierarchy on the WordPress Codex: The Codex is the canonical source for all your information about WordPress. Learn to love it. The page is quite long and detailed, which makes for somewhat dull reading, but makes it super valuable as a reference. You can easily CMD/CTRL+F for whatever you specific problem is — “single taxonomy” for example — and quickly find a great explanation.
- WPTuts+ Cheat Sheet: Especially if you understand the basic terminology and function of WordPress functions like
is_home()I really appreciate the brevity of their visual map. It’s not exhaustive, but it’s easy to read. (It’s also the image in the previous section.)
- Marktime Media’s Graphical Version: These are a bit large and unwieldy for many contexts, but they’re really thorough and rather nice-looking to boot. If you’re a real WordPress nerd you could even use them as your desktop background.