Brian Cryer

Cry WordPress How To...

Theme files in a nutshell

These notes are intended to provide a succinct reminder of which files are required for a WordPress theme. It is not a tutorial.

Theme directory

WordPress themes reside in the directory

wp-content/themes/theme-name

where theme-name is the name of the theme. This folder contains all the files (and folders) required by the theme.

Minimum file set

The minimum set of files that must exist are:

style.css
Provides both the CSS styles and details about the theme.
index.php
Specifies how your latest posts will be displayed on your home page.

Typically this provides a list of posts or content generated in WordPress. This is used if a static front page is not set, and if home.php does not exist.

page.php
Template used to render authored content. You can have more than one page template (@@@).
single.php
Template used to render an individual post.
archive.php
Specifies how an archived page will look like. If there is no archive.php file then index.php is used instead.

It is a WordPress setting for your website whether index.php is used as the default page (listing recent posts) or whether page.php is used to show a nominated page.

Common optional files

The following files are common but not mandatory:

header.php
Provides the header for every page.
footer.php
Provides the footer for every page.
sidebar.php
Provides code for the sidebar.
comments.php
Controls how comments are rendered.
functions.php
These is where any custom php functions for your theme should go.
home.php
Used to generate the home page if a static page has not been set.
404.php
The template used when the requested page or post is missing.
page-{slug}.php (or page-{id}.php)
Provides a custom page layout for a single page.

For a more comprehensive list see http://codex.wordpress.org/Theme_Development#Template_Files_List

Theme stylesheet: style.css

The file style.css provides both the CSS styles for the theme and also information about the theme. Information about the theme (such as the name, author, version etc) are all provided by comments

For example:

/*
 * Copyright (C) A.B.Cryer 2013.
 * Theme Name: Insight
 * Description: Blog microsite with the same look and feel as the main.
 * Author: Brian Cryer
 * Version: 2013.12.17
 */

For a full list of file headers see http://codex.wordpress.org/File_Header but the main ones I use are:

Author:
The name of the author or creator of the theme.
Author URI:
The website for the author (or creator).
Description:
Free format text description of the theme.
License:
The license under which the theme is distributed. If this is to be included on the WordPress site then the license should be "GNU General Public License v2.0".
License URI:
Link to a page containing the full text of the license.
Tags:
A list of tags used to describe the theme. These are used when someone searches for a theme. The list of valid tags can be found here: http://wordpress.org/themes/tag-filter/
Theme Name:
The name by which the theme will be identified in WordPress. This is the only mandatory header.
Theme URI:
Address of a page giving information about your theme.
Version:
Version number for the theme. This is useful as a simple means of seeing whether a site is using the latest version of your theme.

index.php (list of posts)

The file index.php is used to display a list of recent posts. Traditionally it was used for the homepage for site. Whilst the home page can be a nominated content page, index.php remains the default home page for new installations.

Whilst this is overly simplistic, each index.php will be structured something like this:

<?php get_header(); ?>
... content ...
<?php get_footer(); ?>

The important thing to note is that the index.php file pulls in the header and footer.

The content of the idnex.php is then what is to be displayed. Other content will typically be one or more of:

A list of posts
A list of posts, the page content will be something like:

<?php if (have_posts()) : ?>
  <?php while (have_posts()) : the_post(); ?>
    <div <?php post_class() ?>>
    <h1><a href="<?php the_permalink() ?>"><?php the_title(); ?></a></h1>
    <h2>Posted on <?php the_time('F jS, Y') ?></h2>
    <?php the_excerpt() ?>
    </div>
    <hr>
  <?php endwhile; ?>
  <p><?php previous_posts_link(); ?> <?php next_posts_link(); ?></p>
<?php else : ?>
  <p><?php _e('Sorry, no posts matched your criteria.'); ?></p>
<?php endif; ?>

Side bar
Something like:

<div class="sidebar">
  <?php get_sidebar(); ?>
</div>

Remember that you will need to provide styling and anything else necessary to position the sidebar where you want it on the page.

page.php (authored content)

The file page.php is used to render any authored content (other than posts). A typical (but minimal) example is:

<?php get_header(); ?>
  <?php if (have_posts()) : ?>
    <?php while (have_posts()) : the_post(); ?>
      <div <?php post_class() ?>>
        <h1><a href="<?php the_permalink() ?>"><?php the_title(); ?></a></h1>
        <?php the_content(); ?>
        <div class="comments">
          <?php comments_template(); ?>
        </div>
      </div>
    <?php endwhile; ?>
    <div>
    <p><?php previous_posts_link(); ?> <?php next_posts_link(); ?></p>
    </div>
  <?php else : ?>
    <p><?php _e('Sorry, the page you are looking for is not here.'); ?></p>
    <p><a href="<?php echo get_option('home'); ?>">Return to the homepage</a></p>
  <?php endif; ?>
  <div class="sidebar">
    <?php get_sidebar(); ?>
  </div>
<?php get_footer(); ?>

Yes, whilst this is used to display pages it still refers to posts.

single.php (single post)

The file single.php is used to render a single post. Its content is similar to index.php, and a typical (but minimal) example is:

<?php get_header(); ?>
  <?php if (have_posts()) : ?>
    <?php while (have_posts()) : the_post(); ?>
      <div <?php post_class() ?>>
        <h1><a href="<?php the_permalink() ?>"><?php the_title(); ?></a></h1>
        <h2>Posted on <?php the_time('F jS, Y') ?></h2>
        <?php the_content(__('(more...)')); ?>
        <div class="comments">
          <?php comments_template(); ?>
        </div>
      </div>
    <?php endwhile; ?>
    <div>
    <p><?php previous_posts_link(); ?> <?php next_posts_link(); ?></p>
    </div>
  <?php else : ?>
    <p><?php _e('Sorry, no posts matched your criteria.'); ?></p>
    <p><a href="<?php echo get_option('home'); ?>">Return to the homepage</a></p>
  <?php endif; ?>
  <div class="sidebar">
    <?php get_sidebar(); ?>
  </div>
<?php get_footer(); ?>

Where are images?

Assuming that you have all your images in a folder called images (so in wp-content/themes/theme-name/images) then in your php files you should refer to this using the prefix:

<?php bloginfo('template_url');?>

That way WordPress can add in any path that it needs to contribute. So for example a logo image in the header could be referenced as:

<img alt="Company logo" src="<?php bloginfo('template_url');?>/images/logo.gif">

Page themes

If all your pages are to look the same (which is normally the case) then all you need is a single page.php. If on the other hand you need some pages to look a little different then you need page templates.

To create an alternative page start by copying page.php (keep it in the same folder), edit it and add the following at the top:

<?php
/*
Template Name: Other layout
*/
?>

when you quick-edit a page the new name (here "Other layout" but you may want a more descriptive name) will appear in the "Template" drop down list for you to select.

Upload a theme to WordPress

WordPress will allow you to add (or update) a theme, you do this by uploading the theme as a .zip file. You will find the option to do this by logging into your WordPress dashboard, clicking on "Appearance" and the option to "Add New" should be available at the top of the page.

To zip up your own custom theme, simply zip up the contents of the folder containing your theme. Be sure that the style.css file and template files are in the root of the zip. If you include the file "screenshot.png" then this is used by WordPress as a snapshot of what the theme looks like.

Altheratively you can simply copy the files to the wp-content/themes/theme-name folder.

These notes have been tested with WordPress 3.5 and 4.0

About the author: is a dedicated software developer and webmaster. For his day job he develops websites and desktop applications as well as providing IT services. He moonlights as a technical author and consultant.