When you're creating or modifying a WordPress theme so it works the way you want it to, one of the most important things to understand is which file WordPress is using to create which page. This post looks at how WordPress's template hierarchy works, and answers questions like "if I don't have an archive.php, what next?"

WordPress is database-driven. This means that rather than creating a whole series of static HTML files, one for each blog post like we had to in the bad old days, WordPress keeps the data - your posts, comments, tags and information like the blog's name and its authors - separate from instructions about how that data should be presented. This organisation means that you can change the appearance - the "theme" - of your blog without having to edit every single post you ever wrote.

A theme is a series of files which tells WordPress how to display your blog's data. That's why you can't have "WordPress without a theme" - without theme files, nothing would display on screen. When a browser asks for a page of your blog, WordPress determines what type of page that is, looks at the available theme files, and decides which file it should use to generate the web page according to a set order. The system used to decide which file to use is the WordPress template hierarchy - and it looks like this:

For some types of page, this is straightforward:

• is it a single post page? Is single.php available? If not, use index.php
• is it a page of search results? Is search.php available? If not, use index.php
• is it the blog's home page? Is home.php available? If not, use index.php
• is it a 404 page? Is 404.php available? If not, use index.php

Elsewhere, it gets a little more complicated. WordPress pages will use the PHP file for the template specified for them, or if none has been specified, page.php, or if that's not available, then index.php.

Archives pages can have different options according to what type of archive is being requested.

• Author archives: is author.php available? If not, use index.php
• Date (daily, monthly, annual) archives: is date.php available? If not, use index.php
• Category archives: is there a template in the format category-xx.php for this specific category? If not, is category.php available? If not, use index.php
• Tag archives: is there a template in the format tag-slug.php for this specific tag? If not, is tag.php available? If not, use index.php

As you can see, everything will default to index.php eventually: it's possible to publish a perfectly good and functional theme with only this file, a stylesheet and a screenshot for the Themes index.

Most themes, of course, will need more distinction than this: you'll want to *do* different things on a single post page than you do on the home page, or on archive pages, and that's when the template hierarchy becomes useful. Theme designers can have each page the way they want it, without having to create a whole bunch of unnecessary template pages that they don't need - imagine if you had to create a tag archive page for every tag you ever used! With the template hierarchy, you can create special archives for particular tags (or categories), and leave everything else to the default.

The hierarchy also means that you can add to themes and predict what will happen. If your theme shipped without an author.php file, you can add one and know that it will work: author archives will automatically use the new template file, while other archives would carry on using the file from your original theme. In other words, the template hierarchy makes theme functionality predictable, because we're all using the same system.

Tomorrow, we'll be looking at Conditional Tags, another way to control what's displayed according to the type of query being run.

Tags: template hierarchy

Posted by Sue on August 10, 2009 in WordPress.