WordPress – The theme hierarchy

WordPress – The theme hierarchy

Theme hierarchy in WordPress – The anatomy of a theme

What is the WordPress theme hierarchy / template hierarchy? Well, let me explain..

My cousin asked me to develop a website for her Father’s business. Initially I thought this would be a great learning experience as I knew the basics of web development (HTML, CSS, PHP, and a bit of JavaScript) but had never completed a full website before. I slowly but surely realised just what I had landed myself into… !

To cut a long story short I decided it would be best to create and implement a WordPress theme. I’ve always heard this makes content management very straightforward and doesn’t require much knowledge of PHP / HTML for managing. Sounds perfect – Unless you’re the one developing the WordPress theme in which case it’s an absolute pain!

Had I known how difficult this would be I definitely would not have chosen to develop a WordPress theme for my first development job. The first hurdle I encountered was understanding the theme hierarchy. See what I did at first was simply hard code an index.php and styles.css and upload them as a “theme”. Then I tried to create a new page from within WordPress and that wouldn’t work – It kept bringing me back to index.php. I had also tried to create a contact.php with the company contact details – Now how do I get this to appear in WordPress? Hmmmm..

At this point I learned about the WordPress Theme Hierarchy. I didn’t really understand it, but I knew it was how WordPress determines which template file(s) to use on individual pages. So I kept trying numerous different implementations, none of which worked. Read multiple blog posts and just ended up confused. Until I saw the ‘template-loader.php’ being mentioned somewhere and this is what finally made me understand the theme hierarchy template. Show me in code and I’ll understand!

Let’s take a look:

wordpress theme hierarchy

Examining this file is what finally made everything click with me in terms of how pages get selected, and the reason why creating a new page in the WordPress GUI was not working. I only had an index.php! Basically, this code steps through each of the query context conditionals in a specific order, and defines the template to use for the first one that returns true. So in my case, only index.php was being found and so only the contents of index.php were being returned.

When a person browses to your website, WordPress selects which template to use for rendering that page. As we learned earlier in the Template Hierarchy, WordPress looks for template files in the following order:

  • Page Template — If the page has a custom template assigned, WordPress looks for that file and, if found, uses it.
  • page-{slug}.php — If no custom template has been assigned, WordPress looks for and uses a specialized template that contains the page’s slug. A slug is a few words that describe a post or a page. If the page slug is recent-news, WordPress will look to use page-recent-news.php.
  • page-{id}.php — If a specialized template that includes the page’s slug is not found, WordPress looks for and uses a specialized template named with the page’s ID. If the page ID is 6, WordPress will look to use page-6.php.
  • page.php — If a specialized template that includes the page’s ID is not found, WordPress looks for and uses the theme’s default page template.
  • index.php — If no specific page templates are assigned or found, WordPress defaults back to using the theme’s index file to render pages

I realise this is just the basic knowledge needed but I hope to discuss this further. Writing here helps me understand and get my thoughts clear.

2 thoughts on “WordPress – The theme hierarchy

  1. Pingback: Anonymous

Leave a Reply

%d bloggers like this: