WordPress 3 Template Hierarchy
This chart is one entire page in our book, but I thought it would be good to focus on specifically. Template hierarchy has gotten a bit more advanced since the last time we covered it.
The idea is that WordPress will look for files in a theme to use to render the current page in a specific order. For example, let say you have a page for showing posts from a certain category like this. On this site, all our category pages are currently the same and use “archive.php” template. This file is pretty far down the hierarchy, and is shared with other types of views, for example, tag and category pages.
Visualizing the Template Hierarchy
If we wanted to differentiate our category pages from our tag pages, we could create a file in our theme called “category.php” and our site would instantly start using that template for these pages, without us having to do anything else. We could get even more specific, have theme files that are unique to the categories themselves! To make a page specific to our security category, we could make a file called “category-security.php” and our site would use that file when viewing that category page.
You could really get fancy with customized pages by having a good understanding of the template hierarchy! Do take care not to get too overly repetitive with your templates though. If you have 10 categories and want to have a different header on each, you may be better off using a single category.php file with conditional tags rather than 10 separate files.
This was based on this hierarchy list that was sent to me by Ptah Dunbar. Thanks Ptah!
- 404
- 404.php
- index.php
- Search
- search.php
- index.php
- Tax
- taxonomy-{tax}-{term}.php
- taxonomy-{tax}.php
- taxonomy.php
- archive.php
- index.php
- Home
- home.php
- index.php
- Attachment
- mime.php
- type.php
- mime_type.php
- attachment.php
- single.php
- index.php
- Single
- single-{post-type}.php
- single.php
- index.php
- Page
- custom_template.php
- page-{slug}.php
- page-{id}.php
- page.php
- index.php
- Category
- category-{slug}.php
- category-{id}.php
- category.php
- archive.php
- index.php
- Tag
- tag-{slug}.php
- tag-{id}.php
- tag.php
- archive.php
- index.php
- Author
- author-{author-nicename}.php
- author-{author-id}.php
- author.php
- archive.php
- index.php
- Date
- date.php
- archive.php
- index.php
- Archive
- archive.php
- index.php
About the author
Chris Coyier is a real-world web designer who has been reaching for WordPress to power client sites for many years. He subscribes to the theory that not only is WordPress capable of powering any website it is almost always the right choice. His other projects include CodePen and Quotes on Design.
20 responses
-
Thank you for this post. It’s very useful!
-
Fikri RasyidHow about “home” of custom post type? We can use home.php or index.php for displaying our latest post. But which template will be used if we have custom post titled -for example- book? Furthermore, how’s the permalink’s structure?’
-
Andrew NacinArchive/index pages for custom post types will be coming in 3.1.
-
Paul KazmercykAndrew: So WP 3.1 will be adding to the existing template hierarchy to accommodate custom post types? Will it be something like mycustomposttype.php > archive.php > index.php?
-
-
-
You forgot front-page.php which WordPress looks first for the homepage.
-
This is a really useful chart, thanks!
To compliment the template conversation, it’d be awesome to have some tutorials that go through the new Twenty Ten theme, especially the monster (but nicely commented) functions.php file. These new PHP functions such as _e, __ and esc_attr_e are confusing! It’d be great to know what’s essential to a new theme and what’s not.
-
Andrew Nacin
As you might have guessed, those are for translations. Kubrick (the default theme from WP 1.5 to 2.9) was distributed in two formats — hardcoded for the U.S. English crowd, and internationalized for everyone else. Aside from forcing us to maintain two different copies and it isn’t teaching best practices.
You can learn more about translations here (though that page could probably use an refresh). For the most part, it’s one main function, __(), with a bunch of shorthand aliases to make things easier. The function _e() is actually just
echo __(). And esc_attr_e() is justecho esc_attr( __() ).Glad you like the comments :-)
-
Thanks for the reply, Andrew! Yeah, this new functions.php file is overly complicated for me but I’m determined to at least learn a little more about how I can slim it down b/c I’m positive I’m not using everything and I like to optimize themes for speed.
I’d really love to see a play-by-play for each of the code functions in the functions.php file and how/where they relate to the code in the rest of the theme template files and the origin of different functions. For instance, I see something like this
__( '<em>alias</em>', 'twentyten' )or<?php _e( '<em>description</em>', 'twentyten' ); ?>and I’m unsure of where twentyten is established and what the alias or description means or does, even with the excellent comments you left.It’d also be great to know which code is essential/highly recommended/optional.
-
-
-
Using single files really helps keep the code seperated IMO. I prefer this. Another thing that wasn’t said about this is vs seperate conditional tags is that if you screw up the code you only have to debug one file instead of having to go through a lot more code to debug.
Your book rocks and I am glad you keep adding to the information via this website! I wish all ebooks publishers did this!
-
Dave BergschneiderNice, info graphic. I like the way you cascaded them because a lot of people don’t understand that there is more than one path for templates files to get the same result.
-
Nice one, but typo in the heading!
“Heirarchy”-
Chris Coyier Post AuthorAh yes I see where you mean. We’re just fixing the final proof of the print version now, so good timing, I’ll make sure that’s fixed.
-
-
good
i hope WordPress will modif dynamic inclusion such as including footbar.php from theme files by calling function get_footbar()
or leftsidebar by calling function get_leftsidebar()
-
Great post! The “Which Template File Will WordPress Use” chart makes it much easier to understand. Big thank you from a visual person :)
-
This one is called knowledge sharing. Thanks a lot for your work. It will reduce lots of time for template implementation. Big Thank you for this.
-
So this is definitely the best explanation/infographic I’ve seen of this concept. Very useful, thanks. However, can anyone clearly define the different use cases for when to use a page/post-specific template (e.g. page-{id}.php) and when to select a template from the Page editing interface?
-
PhilippYou do no, that there is a official template hierarchy graph from the wordpress codex?
-
Chris Coyier Post Author
As I’m sure you saw while looking at that link, it’s not updated for 3.0.
-
What are the differences? I don’t think I see any.
Or did they update it since this was last written?
P.S. loving digwp!
-
-
-
What happened to single-{ID}? Is that no longer checked before single-{post-type}?
