WordPress Template Files Heirachy & Stucture

Codex

Codex tools: Log in / create account

Template Hierarchy

Languages: English • Français • 日本語 • Русский • (Add your language)

Note: This article covers an advanced topic. See Stepping Into
Templates for an introduction to WordPress templates.

Contents

[hide]

* 1 Introduction

o 1.1 What this article is about

o 1.2 Who might find this useful

o 1.3 Using Conditional Tags

* 2 The Template File Hierarchy

o 2.1 The General Idea

o 2.2 Examples

o 2.3 Visual Overview

o 2.4 The Template Hierarchy In Detail

+ 2.4.1 Home Page display

+ 2.4.2 Single Post display

+ 2.4.3 Page display

+ 2.4.4 Category display

+ 2.4.5 Tag display

+ 2.4.6 Author display

+ 2.4.7 Date display

+ 2.4.8 Search Result display

+ 2.4.9 404 (Not Found) display

+ 2.4.10 Attachment display

* 3 Changelog

* 4 Source File

* 5 See also

* 6 External Resources

Introduction

WordPress Templates fit together like the pieces of a puzzle to
generate the web pages on your WordPress site. Some templates (the
header and footer template files for example) are used on all the web
pages, while others are used only under specific conditions.

What this article is about

This article seeks to answer the following question:

Which template file(s) will WordPress use when it displays a
certain type of page?

Who might find this useful

Since the introduction of Themes in WordPress v1.5, Templates have
become more and more configurable. In order to develop WP themes, a
proper understanding of the way WordPress selects template files to
display the various pages on your blog is essential. If you seek to
customize an existing WordPress theme, this article aims to help you
decide which template file needs editing.

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. See the
Conditional Tags page and “Query Based” in Theme Development for more.

The Template File 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.

First, 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 <a class=”moz-txt-link-freetext”
href=”http://example.com/wp/”>http://example.com/wp/ and a visitor
clicks on a
link to a category page like <a class=”moz-txt-link-freetext”
href=”http://example.com/wp/category/your-cat/”>http://example.com/wp/category/your-cat/,
WordPress looks for a template file in the current Theme’s directory
that matches the category’s ID. If the category’s ID is 4, WordPress
looks for a template file named category-4.php. If it is missing,
WordPress next looks for a generic category template file,
category.php. If this file does not exist either, WordPress looks for a
generic archive template, archive.php. If it is missing as well,
WordPress falls back on the main Theme template file, index.php.

If a visitor goes to your home page at <a class=”moz-txt-link-freetext”
href=”http://example.com/wp/”>http://example.com/wp/,
WordPress first determines whether it has a static front page. If a
static front page has been set, then WordPress loads that page
according to the page template hierarchy. If a static front page has
not been set, then WordPress looks for a template file called home.php
and uses it to generate the requested page. If home.php is missing,
WordPress looks for a file called index.php in the active theme’s
directory, and uses that template to generate the page.

Visual Overview

The following diagram shows which template files are called to generate
a WordPress page based on the WordPress Template hierarchy.

Graphic Example of the WordPress Template Hierarchy Structure Full-Size
Image (png)

The Template Hierarchy In Detail

The following sections describe the order in which template files are
being called by WordPress for each query type.

Home Page display

1. home.php

2. index.php

Single Post display

1. single.php

2. index.php

Page display

WordPress Pages:

1. custom template – Where custom template is the Page Template
assigned to the Page.

2. page-slug.php – If the page slug is recent-news, WordPress
will look to use page-recent-news.php Note: not available until Version
2.9.

3. page-id.php – If the page ID is 6, WordPress will look to use
page-6.php Note: not available until Version 2.9.

4. page.php

5. index.php

Category display

Category Templates:

1. category-slug.php – If the category’s slug were news,
WordPress would look for category-news.php Note: not available until
Version 2.9.

2. category-id.php – If the category’s ID were 6, WordPress
would look for category-6.php

3. category.php

4. archive.php

5. index.php

Tag display

Tag Templates:

1. tag-slug.php – If the tag’s slug were sometag, WordPress
would look for tag-sometag.php

2. tag-id.php – If the tag’s ID were 6, WordPress would look for
tag-6.php Note: not available until Version 2.9.

3. tag.php

4. archive.php

5. index.php

Author display

Author Templates:

1. author.php

2. archive.php

3. index.php

Date display

Archive (Date) Templates:

1. date.php

2. archive.php

3. index.php

Search Result display

Creating a Search Page:

1. search.php

2. index.php

404 (Not Found) display

Creating an Error 404 Page:

1. 404.php

2. index.php

Attachment display

Attachment Templates:

1. MIME_type.php – it can be any MIME type (image.php,
video.php, audio.php, application.php or any other).

2. attachment.php

3. single.php

4. index.php

--
Dwayne Myers
(386)307-4289
Http://www.DreamDrivenDesigns.com