Understanding The Template Hierarchy (part 2)

In the last article about the template hierarchy I probably forgot to cover an important point, so I’m going to amend now and clarify a few things. I analyzed what happens when someone access the home page of a WordPress website, what templates WordPress looks for and loads first. Now I’ll go deeper into the templates that determine how the home page will look like.

It turns out that there are in fact three possible templates for the home page. Why so many? Because this is how WordPress gives you the greatest flexibility. With these three templates WordPress lets you choose if in your home page you want to have a classic blog page (home.php), a static page (page.php or a different template as I’ll explain later) or a custom page with none of them (frontpage.php). When I first discovered that there is a frontpage.php file, and that this is the first that gets loaded if it exists, I was quite surprised. The problem is that in the admin dashboard under settings->reading you can choose if you want a blog page or a static page as the home page but there isn’t any front page option anywhere. So, how do you choose that one? The surprising answer is that you don’t. It’s up to the theme to implement this template file, and then give the user the option to use it. Just as the responsive theme does.

responsive theme options

Responsive Theme Options

The template file frontpage.php takes the precedence over any other template file if it exists. If it doesn’t exists, WordPress reverts to the configuration found under the settings->reading section. What happens in the latter case? If you look carefully at the template hierarchy resources that I linked in the last article you’ll have the answer. If the user’s choice is for a blog page, WordPress will load the file home.php. If the choice is for a static page things are a bit more complicated but not so much after all. Before arriving to the file page.php WordPress will look for three templates. The first template file in this path is called $custom.php and must be assigned manually to the page in order to work. To do it, edit a page or create a new one, and choose the template file to assign to that page from the menu that you’ll find in the page attributes box. If you leave that to the default template then WordPress will look for the page-$slug.php template, and then for page-$id.php.

Since I like to see things, I’ve run a simple test to verify that everything is really working in this way. In my local test installation I’ve selected the twenty fourteen theme, then I’ve used an existing page that I had installed for other tests, and I’ve selected that page as my static home page under settings->reading. The slug of the page was ‘lead-generation-page’, and it had an id=22. To make my test I’ve taken the file page.php which is the default template for pages and I’ve duplicated it to two other files. I then have renamed the files as page-lead-generation-page.php, and page-22.php. Finally, I have edited both files, and have removed the sidebar from page-22.php, and sidebar and footer from page-lead-generation-page.php. According to the template hierarchy, WordPress now should load the file page-lead-generation-page.php, and I should see a home page without sidebar and footer. And in fact this is what I saw. Then I eliminated the file so that WordPress should load page-22.php, and I should have the footer back but not the sidebar. And in fact that’s exactly what I saw.

To further verify what was happening I installed the plugin What The File in my test installation, and I suggest you to do the same if you are learning WordPress. What The File adds an option to your toolbar showing what file and template parts are used to display the page you’re currently viewing. A fantastic help for a theme developer, and for a student too!

It looks a bit crazy to do such test when the documentation it’s already so clear. However, I think that it’s important to verify things personally even when they look so simple. Sometimes eve seemingly simple things show bugs or unexpected behaviors. And what if the documentation is outdated? Every good developer should verify and test, and never taken for granted what the documentation says.


So, what do you think ?