The WordPress Template Hierarchy

http://codex.wordpress.org/Template_Hierarchy

The General Idea

WordPress uses the Query String — information contained within each link on your web site — to decide which template or set of templates will be used to display the page.

To see the query string put this in your theme’s page template:

<?php
echo "<pre>"; print_r($wp_query->query_vars); echo "</pre>";
?>

WordPress matches every Query String to query types — i.e. it decides what type of page (a search page, a category page, the home page etc.) is being requested.

Templates are then chosen — and web page content is generated — in the order suggested by the WordPress Template hierarchy, depending upon what templates are available in a particular WordPress Theme.

WordPress looks for template files with specific names in the current Theme’s directory and uses the first matching template file listed under the appropriate query section below.

With the exception of the basic index.php template file, Theme developers can choose whether they want to implement a particular template file or not. If WordPress cannot find a template file with a matching name, it skips down to the next file name in the hierarchy. If WordPress cannot find any matching template file, index.php (the Theme’s home page template file) will be used.

Examples

If your blog is at http://example.com/blog/ and a visitor clicks on a link to a category page like http://example.com/blog/category/your-cat/: Here is the progression of how WordPress uses the template hierarchy to find and generate the right file.

WordPress looks for a template file in the current Theme’s directory that matches the category’s ID.

1. If the category’s ID is 4, WordPress looks for a template file named category-4.php.
2. If it is missing, WordPress next looks for a generic category template file, category.php.
3. If this file does not exist either, WordPress looks for a generic archive template, archive.php.
4. If it is missing as well, WordPress falls back on the main Theme template file, index.php.

Page display

Template file used to render a static page (page post-type)

1. custom template file – The Page Template assigned to the Page. See get_page_templates().
2. page-{slug}.php – If the page slug is recent-news, WordPress will look to use page-recent-news.php
3. page-{id}.php – If the page ID is 6, WordPress will look to use page-6.php
4. page.php
5. index.php

Using Conditional Tags

WordPress provides more than one way to match templates to query types. WordPress Theme developers can also use Conditional Tags to control which templates will be used to generate a certain page. Some WordPress Themes may not implement all of the template files described here. Some Themes use conditional tags to load other template files.

WordPress can load different Templates for different query types. There are two ways to do this: as part of the built-in Template Hierarchy, and through the use of Conditional Tags within The Loop of a template file.

To use the Template Hierarchy, you basically need to provide special-purpose Template files, which will automatically be used to override index.php. For instance, if your Theme provides a template called category.php and a category is being queried, category.phpwill be loaded instead of index.php. If category.php is not present, index.php is used as usual.

You can get even more specific in the Template Hierarchy by providing a file called, for instance, category-6.php — this file will be used rather than category.php when generating the page for the category whose ID number is 6.

If your Theme needs to have even more control over which Template files are used than what is provided in the Template Hierarchy, you can use Conditional Tags. The Conditional Tag basically checks to see if some particular condition is true, within the WordPress Loop, and then you can load a particular template, or put some particular text on the screen, based on that condition.

For example, to generate a distinctive stylesheet in a post only found within a specific category, the code might look like this:

<?php
if ( is_category( '9' ) ) {
    get_template_part( 'single2' ); // looking for posts in category with ID of '9'
} else {
    get_template_part( 'single1' ); // put this on every other category post
}
?>

Or, using a query, it might look like this:

<?php
$post = $wp_query->post;
if ( in_category( '9' ) ) {
    get_template_part( 'single2' );
} else {
    get_template_part( 'single1' );
}
?>