After we know about the template hierarchy of a wordpress theme, it’s time for us to look at how a wordpress theme looks like.

Anatomy of a Theme

WordPress Themes live in subdirectories of the WordPress themes directory (wp-content/themes/ by default) which can not be directly moved using the wp-config.php file. The Theme’s subdirectory holds all of the Theme’s stylesheet files, template files, and optional functions file (functions.php), JavaScript files, and images. For example, a Theme named “test” would reside in the directory wp-content/themes/test/. Avoid using numbers for the theme name, as this prevents it from being displayed in the available themes list.

For a visual guide, see this infographic on WordPress Theme Anatomy from Joost de Valk.

The anatomy of a WordPress theme

WordPress Themes typically consist of three main types of files, in addition to images and JavaScript files.

  1. The stylesheet called style.css, which controls the presentation (visual design and layout) of the website pages.
  2. WordPress template files which control the way the site pages generate the information from your WordPress database to be displayed on the site.
  3. The optional functions file (functions.php) as part of the WordPress Theme files.

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.

  1. 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.).
  2. The content block contains the posts and pages of your blog, i.e. the “meat” of your site.
  3. 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:

  1. Include or “call” the other template files
  2. Include the WordPress Loop to gather information from the database (posts, pages, categories, etc.)

The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. See details here.

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

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.

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. 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.

Wrapping up

The cheatsheet for how your blog works

WordPress themes are made up of a folder of template files, each of which controls a specific piece of your theme. Parts of your site that remain static no matter what page you’re on are controlled by header, sidebar and footer files. You can hack these files so they detect what page you are on and serve different content accordingly, such as display different navigation on posts than on pages; however it is most common for these sections to look the same throughout the site.

  • header.php
    Global file that displays headers and navigation. Also contains HTML code.
  • The Loop
    The display of contents of the main area of your site are controlled by individual WordPress theme template files using what’s called “the loop”.
  • sidebar.php
    Sidebar display is controlled in this file. Multiple sidebars can be set up in functions.php, and contents of sidebar widgets are set up from the WordPress wp-admin panel.
  • footer.php
    Contains instructions for global footer and closes HTML tags.

index.php – home

The index file controls what the homepage of your WordPress theme looks like. By default it is a loop that queries and then displays the most recent blog posts, with a link in the bottom to view previous posts.

Alternately, you can specify in wp-admin -> settings -> reading to have the home page be a page you created yourself in WordPress. In that case, you specify a different page/URL for the regular blog posts to appear on, and that page is generated by index.php.

single.php – individual posts

The display of individual posts in your WordPress theme is controlled by a little file called single.php. It contains a loop that queries just one post and displays it.

You can specify if you want sidebars (and which you want), if you want it to look different than the other pages on the site.

page.php – individual pages

Page.php controls what pages look like. You can choose to eliminate sidebars or other elements, add other unique elements for pages alone.

WordPress also allows you to create different page templates within your WordPress theme for different types of pages. To create a page template, simply copy page.php, rename it to whatever you want, then add this code to the top:

<?php
/*
Template Name: YourPageNameHere
*/
?></pre>
<pre>

archive.php, category.php, tag.php – archives

You can control the look and feel of different archives using template files also. If there is no archive file, the archives will look like index.php; however you can create an archive.php to override that. If you create a file called category.php, it will override archive.php for categories only. If you create a tag.php, you can override it for tag archives only.

The Loop

The loop is perhaps the most powerful part of your WordPress theme. It starts with a query (which determines which posts or pages to grab), and ends with a PHP “endwhile” statement. Everything in between is up to you. You can specify the output of titles, post content, metadata, custom fields and commenting all within the loop and each element is output for each post or page until the query is done. You can set up multiple loops and queries on a single page; for example: on a single.php you could have the loop showing the entire content of a single post, with a loop outputting just titles and thumbnails for related posts below it.

  • Query post or page
  • Start Loop
  • the_title (outputs the title of the post)
  • the_excerpt (outputs the post excerpt)
  • the_content (outputs the full post content)
  • the_category (outputs the post categories)
  • the_author (outputs the post author)
  • the_date (outputs the post date)
  • other tags (there is a variety of other tags you can use in the loop)
  • endwhile;
  • Exit the loop

Background files of a WordPress theme

In order for a WordPress theme to work, it needs a few essential background files. These files can be modified to your needs and can quite powerfully affect the custom look and functionality of your site.

comments.php

This controls the output of comments, which can be included in the loop if you desire comments on your theme. Comments.php can be overriden by plugins such as Disqus, which then take over comment functionality on your blog.

functions.php

Functions.php allows you to put your own custom PHP code in order to modify core elements of your theme. It is often used to specify multiple sidebars, change the number of characters in the excerpt or add custom admin panel options for wp-admin.

style.css

This is the main CSS stylesheet for your theme. It also contains text at the top which tells WordPress what the name of your WordPress theme is, who the author is and what the URL of your site is.