The following article is about developing or designing your own WordPress Theme. If you wish to learn more about how to install and use Themes, review the documentation regarding Using Themes. This topic differs from Using Themes because it discusses the technical aspects of writing code to build your own Themes rather than how to activate Themes or where to obtain new Themes.
You may wish to develop WordPress Themes for your own use or for distribution.
WordPress Themes are files and styles that work together to create a presentation or look for a WordPress site. Each Theme may be different, offering many choices for users to take advantage of in order to instantly change their website look. Why should you build your own WordPress Theme?
A WordPress Theme has many benefits, too.
Why should you build your own WordPress Theme? That's the real question.
WordPress Themes live in subdirectories residing in wp-content/themes/. The Theme's subdirectory holds all of the Theme's style sheet files, template files, an optional functions file (functions.php), and images. For example, a Theme named "test" would probably reside in the directory wp-content/themes/test/.
WordPress includes two Themes in the download, a "Classic" and "Default" Theme. The two Themes are different and use different functions and tags to generate their web page results and looks. Examine the files carefully for these Themes to get a better idea of how to build your own Theme files.
WordPress Themes consist of three main types of files, in addition to images. One is the style sheet called style.css, which controls the presentation (look) of the web pages. The second is the optional functions file (functions.php). The other files are the template files which control the way the web page generates the information from the Database to be displayed as a web page. Let's look at these individually.
In addition to CSS style information for your theme, the stylesheet, style.css must provide details about the Theme in the form of comments. No two Themes are allowed to have the same details listed in their comment headers, as this will lead to problems in the Theme selection dialog. If you make your own Theme by copying an existing one, make sure you change this information first.
The following is an example of the first few lines of the stylesheet, called the style sheet header, for the Theme "Rose":
/* Theme Name: Rose Theme URI: the-theme's-homepage Description: a-brief-description Author: your-name Author URI: your-URI Template: use-this-to-define-a-parent-theme--optional Version: a-number--optional . General comments/License Statement if any. . */
The simplest Theme includes only a style.css file, plus images, if any. To create such a Theme, you must specify a set of templates to inherit for use with the Theme by editing the Template: line in the style.css header comments. For example, if you wanted the Theme "Rose" to inherit the templates from another Theme called "test", you would include Template: test in the comments at the beginning of Rose's style.css. Now "test" is the parent Theme for "Rose", which still consists only of a style.css file and the concomitant images, all located in the directory wp-content/themes/Rose. (Note that specifying a parent Theme will inherit all of the template files from that Theme — meaning that any template files in the child Theme's directory will be ignored.)
The comment header lines in style.css are required for WordPress to be able to identify a Theme and display it in the Administration Panel under Design > Themes as an available Theme option along with any other installed Themes.
Note : When defining the parent Theme, in the Template: section of the comment header, you must use the name of the directory of the style. For example, to use as parent template the Default Wordpress Theme, don't write Template: WordPress Default, but Template: default, because default is the directory of this Theme.
A theme can optionally use a functions file, which resides in the theme subdirectory and is named functions.php. This file basically acts like a plugin, and if it is present in the theme you are using, it is automatically loaded during WordPress initialization (both for admin pages and external pages). Suggested uses for this file:
The "Default" WordPress theme contains a functions.php file that defines functions and an admin screen, so you might want to use it as a model. Since functions.php basically functions as a plugin, the Function_Reference list is the best place to go for more information on what you can do with this file.
Templates are PHP source files used to generate the pages requested by visitors. Let's look at the various templates that can be defined as part of a Theme.
WordPress allows you to define separate templates for the various aspects of your weblog; however, it is not essential to have all these different template files for your blog to function fully. Templates are chosen and generated based upon the Template Hierarchy, depending upon what templates are available in a particular Theme. As a Theme developer, you can choose the amount of customization you want to implement using templates. For example, as an extreme case, you can use only one template file, called index.php as the template for all pages generated and displayed by the weblog. A more common use is to have different template files generate different results, to allow maximum customization.
At the very minimum, a WordPress Theme consists of two files:
Both of these files go into the Theme's directory. The index.php template file is very flexible. It can be used to include all references to the header, sidebar, footer, content, categories, archives, search, error, and other web pages generated by the user on your site. Or it can be subdivided into modular template files, each one taking on part of the workload. If you do not provide any other template files, WordPress will use the built-in default files. For example, if you do not have either a comments.php or comments-popup.php template file, then WordPress will automatically use the wp-comments.php and wp-comments-popup.php template files using Template Hierarchy. These default templates may not match your Theme very well, so you probably will want to provide your own. The basic files normally used to subdivide (which go into the Theme's directory) are:
Using these modular template files, you can put template tags within the index.php master file to include or get these units where you want them to appear in the final generated web page.
Here is an example of the include usage:
<?php get_sidebar(); ?> <?php get_footer(); ?>
For more on how these various Templates work and how to generate different information within them, read the Templates documentation.
WordPress can load different Templates for different query types. There are two ways to do this: as part of the built-in Template Hierarchy, and through the use of Conditional Tags within The Loop of a template file.
To use the Template Hierarchy, you basically need to provide special-purpose Template files, which will automatically be used to override index.php. For instance, if your Theme provides a template called category.php and a category is being queried, category.php will be loaded instead of index.php. If category.php is not present, index.php is used as usual.
You can get even more specific in the Template Hierarchy by providing a file called, for instance, category-6.php -- this file will be used rather than category.php when generating the page for the category whose ID number is 6. (You can find category ID numbers in Manage > Categories if you are logged in as the site administrator). For a more detailed look at how this process works, see Category Templates.
If your Theme needs to have even more control over which Template files are used than what is provided in the Template Hierarchy, you can use Conditional Tags. The Conditional Tag basically checks to see if some particular condition is true, within the WordPress Loop, and then you can load a particular template, or put some particular text on the screen, based on that condition.
For example, to generate a distinctive style sheet in a post only found within a specific category, the code might look like this:
<?php
if (is_category(9)) {
// looking for category 9 posts
include(TEMPLATEPATH . '/single2.php');
} else {
// put this on every other category post
include(TEMPLATEPATH . '/single1.php');
}
?>
Or, using a query, it might look like this:
<?php
$post = $wp_query->post;
if ( in_category('9') ) {
include(TEMPLATEPATH . '/single2.php');
} else {
include(TEMPLATEPATH . '/single1.php');
}
?>
In either case, this example code will cause different templates to be used depending on the category of the particular post being displayed. Query conditions are not limited to categories, however -- see the Conditional Tags article to look at all the options.
This feature is currently broken in WordPress 2.5.
Wordpress uses media icons to represent attachment files on your blog and in the Admin interface, if those icons are available.
It looks for image files named by media type in the images directory of the current theme. (As of Wordpress 2.2, the default theme comes with only one media icon, audio.jpg.)
For example, for an attachment of MIME type audio/mpeg, Wordpress would look for an icon file at these locations, stopping after the first match (see wp_mime_type_icon):
Here is the list of Theme template files recognized by WordPress. Of course, your Theme can contain any other style sheets, images, or files. Just keep in mind that the following have special meaning to WordPress -- see Template Hierarchy for more information.
These files have a special meaning with regard to WordPress because they are used as a replacement for index.php, when available, according to the Template Hierarchy, and when the corresponding Conditional Tag (a.k.a is_*(); function) returns true. For example, if only a single post is being displayed, the is_single() function returns 'true', and, if there is a single.php file in the active Theme, that template is used to generate the page.
The WordPress Default Theme (based on Michael Heilemann's Kubrick layout for WordPress 1.2) provides a good example of how queries are mapped onto templates.
The code <?php bloginfo('template_directory'); ?> inserts the URL of the template directory into the template output. You can append any additional URI information to this output to reference files in your Theme.
The code <?php bloginfo('stylesheet_directory'); ?> inserts the URL of the directory that contains the current Theme stylesheet into the template output. You can append any additional URI information to this output to reference files for your Theme, specifically those that are used by the stylesheet.
The constant TEMPLATEPATH is a reference to the absolute path to the template directory for the current Theme (without the / at the end).
Note that URIs that are used in the stylesheet are relative to the stylesheet, not the page that references the stylesheet. This obviates the need to include PHP code in the CSS file to specify directories. For example, if you include an images/ directory in your Theme, you need only specify this relative directory in the CSS, like so:
h1 { background-image: URL(images/my_background.jpg); }
It is a good practice to use URIs in the manner described above to reference files from within a template, since, then your template will not depend on absolute paths.
It is possible to use the WordPress plugin system to define additional templates that are shown based on your own custom criteria. This advanced feature can be accomplished using the template_redirect action hook. More information about creating plugins can be found in the Plugin API reference.
When developing Themes, it's good to keep in mind that your Theme should be set up so that it can work well with any WordPress plugins you (or another Theme user) might decide to install. Plugins add functionality to WordPress via "Action Hooks" (see Plugin API for more information). Most Action Hooks are within the core PHP code of WordPress, so your Theme does not have to have any special tags for them to work. But a few Action Hooks do need to be present in your Theme, in order for Plugins to display information directly in your header, footer, sidebar, or in the page body. Here is a list of the special Action Hook Template Tags you need to include:
</form>). Example plugin use: display a comment preview.For a real world usage example, you'll find these plugin hooks included in the default theme's templates.
Please be clear about the following in your documentation (a README file included with your Theme helps many users over any potential stumbling blocks):
Take time to read through Designing Themes for Public Release, an article with good tips on preparing your Theme for the public.
There is a comprehensive list of WordPress Theme and Template File resources in the Templates article.