Watkins Web 3: Blog

Cheat Sheet: Wordpress Templates

As discussed in class, the PHP files that make up a Wordpress theme do not represent particular URLs or Posts in your database. Instead, they are templates for various page types. For example, single.php controls all permalink pages. Through the use of the Loop and PHP variables, each permalink page contains different content (pulled from the database), but they are formatted and laid out the same way.

Template Overview

Here’s a quick overview are the most important templates that control your site.

single.php

Controls the layout and content of a single post or “permalink” page like http://example.com/blog/i-love-garamond.

index.php

Controls the home page, but only if you visit Settings > Reading and set Front Page Displays to Your Latest Posts. If instead you set the front page to display a static page, index.php will not be used at all.

category.php

Controls category pages like http://example.com/blog/category/essays-about-design.

tag.php

Controls tag pages like http://example.com/blog/tag/typography.

page.php

Controls Wordpress Pages like http://example.com/blog/about/.

search.php

Controls search results pages like http://example.com/blog/?s=paul+rand.

archive.php

Controls date-based pages (usually) like http://example.com/blog/2012/02. This particular behavior is dependent on your URL choices under Settings > Permalinks.

author.php

Controls author pages like http://example.com/blog/author/jsmith.
Most useful for multi-author sites. Note: “authors” are just the public-facing word for “users” in Wordpress.

Custom Templates and Template Hierarchy

You don’t have to make use of every one of the templates listed above. Wordpress has a built-in feature called the “Template Hierarchy” which means that when certain templates are missing from the theme, others will take over to display your content. A good example is archive.php. While archive.php controls date-based browsing of posts, it will be used for category and tag pages if you are missing a category.php or tag.php file.

A related feature enables you to create additional templates that control a specific Page, Category, Tag, etc. I’m calling these “custom templates.”

Let’s use a custom Page template as an example. Suppose we’ve created a few Wordpress pages that are being displayed on our site: About, Contact, and Colophon. The content for each page is of course determined by the content fields in Wordpress, and the layout and HTML is determined by our page.php template. Suppose page.php is designed with a main column and sidebar to match our blog and portfolio. Now suppose we want to post a new page called Birthday Party that has a single main column and no navigation links. The best method would be to duplicate page.php, rename it to page-birthday.php, and edit it. The first change should be to give it a logical Template Name at the top (this also informs Wordpress that this is different from the regular page.php template):

<?php
	/**
	 * Template Name: My Birthday Page
	 *
	 * @package WordPress
	 * @subpackage Starter Kit
	 */ 
 ?>

Page templates Once we’ve added this new file and uploaded it our theme, it becomes available in the Page Attributes pane for any Page. Once we choose it from the Template pop-up and re-publish the Page, our Birthday Party page will use the new template.

Here’s another example. Suppose we have created blog categories called Features, Essays, and Quick Links. As discussed above, category.php will by default control the category listing pages located at http://example.com/blog/category/features/, http://example.com/blog/category/essays/, and http://example.com/blog/category/quick-links/.

But suppose we want to present Quick Links a little differently. First, we figure out the ID number of the Quick Links category (in Wordpress, click Posts > Categories, hover over the category name and look in your browser’s status bar for the ID). If Quick Links turns out to be Category ID number 3, we could then create a new category template called category-3.php. Once uploaded, http://example.com/blog/category/quick-links/ will immediately start using that template. Unlike pages you don’t need to choose the template from within the Wordpress inteface.

Further Reading