Understanding The Template Hierarchy (part 1)

In this series of articles I’ll try to analyse the structure of the template hierarchy and how WrodPress manages it. I will also try to go deeper and look at the WordPress functions that allow you to completely change that hierarchy to your like. As always, this is the analysis of a beginner learner, so I hope you’ll forgive me if I make some mistakes.

WordPress is a template-based CMS. Now, I’m not saying that other CMSs are not template-based, in fact I dont’ know Drupal and Joomla just to name the two other most popular CMSs, so they might as well use templates in a similar fashion.

I used to install WordPress and use only its basic functions, without any customization at all except for those allowed by the theme in use or WordPress itself. In doing so, I always thought that WordPress was quite a rigid platform. All themes that I used had more or less the same structure: they allowed me to choose a static page as home page or use it as a blog, and they had sidebars whose position could be on either side or among the content. What I realized when I started studying the platform more deeply is that on the contrary, WordPress is incredibly flexible. At the point that in theory we could have a different layout for each page and for each post type, with even different headers, footers and sidebars. Having all this flexibility however doesn’t mean that you have to use it always at its fullest. Power must be used wisely but it allows you to manage also extreme cases.

Now, I’m going to explore how WordPress decides to use a template over another to show a particular page or post or section.

The first document that I read when I decided to understand more about the template hierarchy was of course on codex at this address: codex.wordpress.org/Template_Hierarchy. Although this is a good place to start, it’s not really the best place to learn the template hierarchy for a beginner. However, they point to some very good resources, and if you are a visual learner like me you’re going to love them.

The way the template hierarchy works is that WordPress will look for some specific template files depending on what you require to view, and then revert to other files that are lower in the hierarchy if it doesn’t find the first, until it gets to index.php which is the lowest in the hierarchy. Index.php is the only mandatory file that any theme must have. In case any template file is missing or fails to load, WordPress will always look for index.php at the end. So in fact index.php is just a template file, the most generic one.

To have a better idea of how all this is put together you can give a look at the graphic representation. Click on the image, and then zoom on it. To view it from its original source click here.

Wordpress Template Hierarchy

WordPress Template Hierarchy

I also like to use an interactive representation of the hierarchy that you can find at wphierarchy.com. What I like of this website is that each box has a link to the codex page on WordPress.org that explains that particular template.

Now, to test that hierarchy and understand a bit more about it I’ve tried to imagine what happens in a standard scenario. A visitor will access your home page via a link or by typing it on the address bar. Now, since you are requesting the home page, what will WordPress load? It depends on your settings and on your theme structure also. If you look at the image above, the first thing that WordPress will look for is the file frontpage.php in the directory of your active theme. If your theme has this file, this is what WordPress will load when someone access the home page of your website. It’s up to the theme developer then to structure this file in a way that will respect the hierarchy that comes after this it.

To see how a file frontpage.php is made I’ve setup a local installation on my pc and loaded the Responsive theme. This theme is quite popular, and has just the file frontpage.php. You don’t need to know the WordPress API to understand this code, in my opinion is quite self explanatory. This is how the file begins:

$responsive_options = responsive_get_options();
* If front page is set to display the
* blog posts index, include home.php;
* otherwise, display static front page
* content
if ( 'posts' == get_option( 'show_on_front' ) && $responsive_options['front_page'] != 1 ) {
get_template_part( 'home' );
} elseif ( 'page' == get_option( 'show_on_front' ) && $responsive_options['front_page'] != 1 ) {
$template = get_post_meta( get_option( 'page_on_front' ), '_wp_page_template', true );
$template = ( $template == 'default' ) ? 'index.php' : $template;
locate_template( $template, true );
} else {


I’m not going to show the whole file, for the purpose of this article are relevant lines that I’ve posted.

The line 1 is where the theme loads the user’s options. The variable $responsive_options of course will be an array containing all the options. Then the ‘if’ statement checks whether the user has chosen to show on the home page the posts, a static page or wants the theme to manage the front page. In the last case it loads the header, and then you can look at the file by yourself if you are curious to know how the rest of the page is rendered.

This is an example of how a theme can manage the template hierarchy the right way. In the next article I’ll try to go deeper and see how the templates file are called.

So, what do you think ?