Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Stepping into Templates

Template files are the building blocks of your WordPress site. They fit together like the pieces of a puzzle to generate the web pages on your 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.

A traditional web page consists of two files:

  • The HTML page to hold the structure and content of the page and
  • the CSS Style Sheet which holds the presentation styles of the page.

In WordPress, the (X)HTML structure and the CSS style sheet are present but the content is generated "behind the scenes" by various template files. The template files and the style sheet are stored together as a WordPress Theme. To learn more about creating Themes, read Theme Development.


The WordPress Page Structure

A simple WordPress web page structure is made up of three basic building "blocks": a header, the content, and a footer. Each of these blocks is generated by a template file in your current WordPress Theme.

Header

Content

Footer

  • The header contains all the information that needs to be at the top — i.e. inside the <head> tag — of your XHTML web page, such as the <doctype>, <meta> tags, and links to style sheets. It also includes the opening <body> tag and the visible header of your blog (which typically includes the title of your site, and may also include navigation menus, a logo bar, the description of your site, etc.).
  • The content block contains the posts and pages of your blog, i.e. the "meat" of your site.
  • The footer contains the information that goes at the bottom of your page, such as links to other Pages or categories on your site in a navigation menu, copyright and contact information, and other details.


Basic Template Files

To generate such a structure within a WordPress Theme, start with an index.php template file in your Theme's directory. This file has two main functions:

  • Include or "call" the other template files
  • Include the WordPress Loop to gather information from the database (posts, pages, categories, etc.)

For our simple structure, we only need to include two other template files: the header and the footer. These must be named header.php and footer.php. The Template Tags that include them look like this:

<?php get_header(); ?>


<?php get_footer(); ?>

In order to display the posts and pages of your blog (and to customize how they are being displayed), your index.php file should run the WordPress Loop between the header and footer calls.

More Complex Page Structures

Header

Content

Sidebar

Footer

Many WordPress themes include one or several Sidebars that contains navigation features and more information about your website. The sidebar is generated by a template file called sidebar.php. It can be included in your index.php template file with the following template tag:

<?php get_sidebar(); ?>

Where's the Beef?

Notice that we have not included a template tag to "get" the content of our web page. That is because the content is generated in the WordPress Loop, inside index.php.

Also note that the Theme's style sheet determines the look and placement of the header, footer, sidebar, and content in the user's browser screen. For more information on styling your WordPress Themes and web pages, see Blog Design and Layout.

Template Files Within Template Files

You have seen how WordPress includes standard template files (header, footer, and sidebar) within the index.php template file. You can also include other template files within any of your template files.

For example, sidebar.php might contain a template file that generates a search form — searchform.php. Because this is not one of WordPress's standard template files, the code to include it is a little different:

<?php get_search_form(); ?>

We should no longer be using include and TEMPLATEPATH to get our search forms into themes as WordPress supplies the above template tag.

Header

Content

Comment Form

Sidebar

Search Form

Footer

Most WordPress Themes include a variety of template files within other templates to generate the web pages on the site. The following template files are typical for the main template (index.php) of a WordPress site:

  • header.php
    • theloop.php (The Content)
    • wp-comments.php
  • sidebar.php
    • searchform.php
  • footer.php

However, this structure can be changed. For instance, you could put the search form in your header. Perhaps your design does not need a footer, so you could leave that template out entirely.

Special Template Files

WordPress features two core page views of web pages in a WordPress site. The single post view is used when the web pages displays a single post. The multi-post view lists multiple posts or post summaries, and applies to category archives, date archives, author archives, and (usually) the "normal" view of your blog's home page. You can use the index.php template file to generate all of these types of pages or rely on WordPress' template hierarchy to choose different template files depending on the situation.

The WordPress Template Hierarchy answers the following question:

What template file will WordPress use when a certain type of page is displayed?

WordPress automatically recognizes template files with certain standard names and uses them for certain types of web pages. For example, when a user clicks on the title of a blog post, WordPress knows that they want to view just that article on its own web page. The WordPress template hierarchy will use the single.php template file rather than index.php to generate the page — if your Theme has a single.php file. Similarly, if the user clicks on a link for a particular category, WordPress will use the category.php template if it exists; if it doesn't, it looks for archive.php, and if that template is also missing, WordPress will go ahead and use the main index.php template. You can even make special template files for specific categories (see Category Templates for more information). You can also make Custom Page Templates for specific Pages.

Template File Tips

Here are some tips for creating WordPress template files:

Tracking Opening and Closing Tags
Template files include the use of XHTML tags and CSS references. HTML elements and CSS references can cross template files, beginning in one and ending in another. For example, the html and body HTML elements typically begin in header.php and end in footer.php. Most WordPress themes make use of HTML div elements, which can also span several files. For instance, the main div for the page content might start in header.php and end in either index.php or single.php. Tracking down where an HTML element begins and ends can get complicated if you are developing, designing, or modifying a Theme. Use comments to note in the template files where a large container tag opens and where it closes so you can track which div is which at the end of different sections.
Test Template Files Under Different Views
If you have made changes to the comments, sidebar, search form, or any other template file, make sure you test them using different web page views (single post, different types of archives, and pages).
Comment Deviations
If you are designing Themes for public release, keep in mind that someone who downloads your Theme will probably want to modify it slightly for their own use. So, it is helpful if you make notes in your template files where you have made changes from the logic of the Default and/or Classic Themes. It is also a good idea to add comments in your Theme's main style file if you have style information elsewhere (such as in your header.php file or in HTML tags).
Close the Tag Door Behind You
If you start a HTML tag or div in one template file and don't close it there, make sure you include the closing tag in another template file. The WordPress Forum gets a lot of questions about "what happened to my theme" when they remove the footer template file without closing the tags that began in the header template file. Track down your tags and make sure they are closed. (A good way to verify that this is correct is to test your single and archive page views with an HTML validator).
CSS Styles in Templates
You are free to use whatever HTML and CSS tags and styles you like in your templates. However, you are encouraged to follow the standard WordPress theme structure (see Site Architecture 1.5). This will make your Themes more understandable to your users.

Template File Resources

For a comprehensive list of resources related to Template Files, see Templates. You may also wish to view the other articles in Category:Templates and Category:Template Tags.