Codex

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

Difference between revisions of "Theme Development"

m (Child Themes style.css)
m (Referencing Files From a Template, remove content, link to theme developer handbook)
 
(195 intermediate revisions by 88 users not shown)
Line 1: Line 1:
 
{{Languages|
 
{{Languages|
  +
{{bn|থিম ডেভলপমেন্ট}}
 
{{en|Theme Development}}
 
{{en|Theme Development}}
  +
{{es|Desarrollo de Temas}}
 
{{ja|テーマの作成}}
 
{{ja|テーマの作成}}
  +
{{ko|Theme Development}}
  +
{{pt-br|Desenvolvimento de Temas}}
 
{{ru|Создание тем}}
 
{{ru|Создание тем}}
 
{{zh-cn|主题开发}}
 
{{zh-cn|主题开发}}
  +
{{zh-tw|主題開發}}
 
}}
 
}}
   
 
__TOC__
 
__TOC__
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.
 
   
  +
This article is about developing WordPress Themes. If you wish to learn more about how to install and use Themes, review [[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 [[Designing Themes for Public Release|for distribution]].
 
==Why WordPress Themes==
 
   
  +
== Why WordPress Themes ==
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?
 
   
  +
WordPress Themes are files that work together to create the design and functionality of a WordPress site. Each Theme may be different, offering many choices for site owners to instantly change their website look.
* To create your own unique WordPress site look
 
  +
* To take advantage of [[Stepping Into Templates|templates]], [[Template Tags|template tags]], and [[The Loop in Action|the WordPress Loop]] to generate different web page results and looks.
 
  +
You may wish to develop WordPress Themes for your own use, for a client project or to [[Theme_Review|submit to the WordPress Theme Directory]]. Why else should you build a WordPress Theme?
  +
  +
* To create a unique look for your WordPress site.
  +
* To take advantage of [[Stepping Into Templates|templates]], [[Template Tags|template tags]], and [[The Loop in Action|the WordPress Loop]] to generate different website results and looks.
 
* To provide alternative templates for specific site features, such as [[Category Templates|category pages]] and search result pages.
 
* To provide alternative templates for specific site features, such as [[Category Templates|category pages]] and search result pages.
* To quickly switch between two site layouts, or to take advantage of a [[Plugins|Theme or style switcher]] to allow users to change the look of your site.
+
* To quickly switch between two site layouts, or to take advantage of a [[Plugins|Theme or style switcher]] to allow site owners to change the look of your site.
* To design WordPress Theme(s) so that others may enjoy your designs through public release.
 
   
A WordPress Theme has many benefits, too.
+
A WordPress Theme has many benefits, too.
   
 
* It separates the presentation styles and [[Stepping Into Templates|template files]] from the system files so the site will upgrade without drastic changes to the visual presentation of the site.
 
* It separates the presentation styles and [[Stepping Into Templates|template files]] from the system files so the site will upgrade without drastic changes to the visual presentation of the site.
* It allows for customization of the presentation and web page results unique to that Theme.
+
* It allows for customization of the site functionality unique to that Theme.
* It allows for quick changes of the look and feel of a WordPress site.
+
* It allows for quick changes of the visual design and layout of a WordPress site.
* It takes away the need for a WordPress user to have to learn CSS, HTML, and PHP in order to have a good looking website.
+
* It removes the need for a typical WordPress site owner to have to learn CSS, HTML, and PHP in order to have a great-looking website.
   
Why should you build your own WordPress Theme? That's the real question.
+
Why should you build your own WordPress Theme? That's the real question.
   
* It's an opportunity to learn more about CSS, HTML/XHTML, and PHP.
+
* It's an opportunity to learn more about CSS, HTML, and PHP.
* It's an opportunity to put your expertise with CSS, HTML/XHTML, and PHP to work.
+
* It's an opportunity to put your expertise with CSS, HTML, and PHP to work.
 
* It's creative.
 
* It's creative.
 
* It's fun (most of the time).
 
* It's fun (most of the time).
* If you [[Designing Themes for Public_Release|release it to the public]], you can feel good that you shared and gave something back to the [[Contributing_to_WordPress|WordPress Community]] (okay, bragging rights!)
+
* If you [[Theme_Review|release it to the public]], you can feel good that you shared and gave something back to the [[Contributing_to_WordPress|WordPress Community]] (okay, bragging rights)
   
  +
== Theme Development Standards ==
==Anatomy of a Theme==
 
   
  +
WordPress Themes should be coded using the following standards:
WordPress Themes live in subdirectories residing in <tt>wp-content/themes/</tt>. The Theme's subdirectory holds all of the Theme's style sheet files, [[Stepping Into Templates|template files]], and optional functions file (<tt>functions.php</tt>), and images. For example, a Theme named "test" would probably reside in the directory <tt>wp-content/themes/test/</tt>. Avoid using numbers for the theme name, as this causes it not to be shown on themes page.
 
   
  +
* Use well-structured, error-free PHP and valid HTML. See [http://make.wordpress.org/core/handbook/coding-standards/ WordPress Coding Standards].
WordPress includes the [[Glossary#Twenty Ten theme|Twenty Ten theme]] as the default theme in each new installation. Examine the files carefully to get a better idea of how to build your own Theme files.
 
  +
* Use clean, valid CSS. See [http://make.wordpress.org/core/handbook/coding-standards/css/ CSS Coding Standards].
  +
* Follow design guidelines in [[Site Design and Layout]].
   
  +
=== Anatomy of a Theme ===
WordPress Themes consist of three main types of files, in addition to images. One is the style sheet called <tt>style.css</tt>, which controls the presentation (look) of the web pages. The second is the optional functions file (<tt>functions.php</tt>). The other files are the [[Stepping Into Templates|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.
 
   
  +
WordPress Themes live in subdirectories of the WordPress themes directory (''wp-content/themes/'' by default) which [[Editing wp-config.php#Moving_themes_folder|cannot be directly moved]] using the ''wp-config.php'' file. The Theme's subdirectory holds all of the Theme's stylesheet files, [[Stepping Into Templates|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.
==Theme Style Sheet==
 
   
  +
WordPress includes a default theme in each new installation. Examine the files in the default theme carefully to get a better idea of how to build your own Theme files.
In addition to CSS style information for your theme, the stylesheet, <tt>style.css</tt> '''''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 [[File Header|headers]], as this will lead to problems in the [[Administration_Panels#Design_-_Change_the_Look_of_your_Blog|Theme selection dialog]]. If you make your own Theme by copying an existing one, make sure you change this information first.
 
   
  +
For a visual guide, see this [http://yoast.com/wordpress-theme-anatomy/ infographic on WordPress Theme Anatomy].
The following is an example of the first few lines of the stylesheet, called the style sheet header, for the Theme "Rose":
 
   
  +
WordPress Themes typically consist of three main types of files, in addition to images and JavaScript files.
<pre>/*
 
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.
 
.
 
*/</pre>
 
   
  +
# The stylesheet called ''style.css'', which controls the presentation (visual design and layout) of the website pages.
  +
# [[Stepping Into Templates|WordPress template files]] which control the way the site pages generate the information from your WordPress database to be displayed on the site.
  +
# The optional functions file (''functions.php'') as part of the WordPress Theme files.
   
  +
Let's look at these individually.
The comment header lines in <tt>style.css</tt> are required for WordPress to be able to identify a Theme and display it in the [[Administration_Panels|Administration Panel]] under [[Administration_Panels#Design_-_Change_the_Look_of_your_Blog|Design]] > [[Administration_Panels#Themes|Themes]] as an available Theme option along with any other installed Themes.
 
   
== Child Themes style.css ==
+
==== Child Themes ====
The simplest Theme possible is a child theme which includes only a <tt>style.css</tt> file, plus any images. This is possible because it is a ''child'' of another theme which acts as its parent.
 
   
  +
This section has moved to the Theme Developer Handbook:
To create such a Theme, you must specify a set of templates to ''inherit'' for use with the Theme by editing the <tt>Template:</tt> line in the <tt>style.css</tt> header comments. For example, if you wanted the Theme "Rose" to inherit the templates from another Theme called "test", you would include <tt>Template: test</tt> in the comments at the beginning of Rose's <tt>style.css</tt>. Now "test" is the parent Theme for "Rose", which still consists only of a <tt>style.css</tt> file and the concomitant images, all located in the directory <tt>wp-content/themes/Rose</tt>. Additionally (as of WordPress 2.7), the child theme may contain template files, which can be selected in the admin panel as normal, and will override the parent's template files where those possess the same name.
 
  +
https://developer.wordpress.org/themes/advanced-topics/child-themes/
   
  +
=== Theme Stylesheet ===
For a detailed guide to child themes, see [[Child Themes]] or [http://op111.net/53 this great tutorial by op111].
 
   
  +
This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/basics/main-stylesheet-style-css/
'''Note''' : ''When defining the parent Theme, in the <tt>Template:</tt> section of the comment header, you must use the name of the directory of the style. For example, to use as parent template called Cold Steel, don't write <tt>Template: Cold Steel</tt>, but <tt>Template: cold_steel</tt>, assuming cold_steel is the directory of that Theme. Also, Themes that inherit from default should not specify the <tt>Template:</tt> section at all.''
 
   
==Theme Functions File==
+
=== Functions File ===
   
  +
This section has moved to the Theme Developer Handbook:
A theme can optionally use a functions file, which resides in the theme subdirectory and is named <tt>functions.php</tt>. This file basically acts like a [[Plugins|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:
 
  +
https://developer.wordpress.org/themes/basics/theme-functions/
* Define functions used in several template files of your theme
 
* Set up an admin screen, giving users options for colors, styles, and other aspects of your theme
 
   
  +
=== Template Files ===
The "Default" WordPress theme contains a <tt>functions.php</tt> file that defines functions and an admin screen, so you might want to use it as a model. Since <tt>functions.php</tt> 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.
 
   
  +
This section has moved to the Theme Developer Handbook:
==Theme Template Files==
 
  +
https://developer.wordpress.org/themes/basics/template-files/
   
  +
====Custom Page Templates====
[[Stepping Into Templates|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.
 
   
  +
This section has moved to the Theme Developer Handbook:
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 <tt>index.php</tt> 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.
 
  +
https://developer.wordpress.org/themes/template-files-section/page-template-files/#creating-custom-page-templates-for-global-use
   
  +
==== Query-based Template Files ====
==='''Basic Templates'''===
 
   
  +
This section has moved to the Theme Developer Handbook:
At the very minimum, a WordPress Theme consists of two files:
 
  +
https://developer.wordpress.org/themes/template-files-section/taxonomy-templates/
   
  +
==== Defining Custom Templates ====
* <tt>style.css</tt>
 
* <tt>index.php</tt>
 
   
  +
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_include" [[Plugin API#Current Hooks For Actions|action hook]]. More information about creating plugins can be found in the [[Plugin API]] reference.
Both of these files go into the Theme's directory. The <tt>index.php</tt> [[Stepping Into Templates|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 <tt>comments.php</tt> or <tt>[[FAQ Working with WordPress#Can I have popup comments?|comments-popup.php]]</tt> template file, then WordPress will automatically use the <tt>wp-comments.php</tt> and <tt>wp-comments-popup.php</tt> template files using [[Template Hierarchy]]. These default templates may not match your Theme very well, so you probably will want to provide your own.
 
   
  +
==== Including Template Files ====
(Note: As of 3.0, the "default" files aren't guaranteed to be present or be the same as they have been. The "Default" Theme is replaced with 2010, and may be deleted on some set ups. The markup is expectedly different and could impact your css design. It's much better/safer to supply your own.)
 
   
The basic files normally used to subdivide (which go into the Theme's directory) are:
+
This section has moved to the Theme Developer Handbook:
  +
https://developer.wordpress.org/themes/template-files-section/partial-and-miscellaneous-template-files/
   
  +
==== Referencing Files From a Template ====
* <tt>header.php</tt>
 
* <tt>sidebar.php</tt>
 
* <tt>footer.php</tt>
 
* <tt>comments.php</tt>
 
* <tt>[[FAQ Working with WordPress#Can I have popup comments?|comments-popup.php]]</tt>
 
   
  +
This section has moved to the Theme Developer Handbook:
Using these modular template files, you can put template tags within the <tt>index.php</tt> master file to include or ''get'' these units where you want them to appear in the final generated web page.
 
  +
https://developer.wordpress.org/themes/functionality/media/
   
  +
==== Plugin API Hooks ====
* To include the header, use the <tt>[[Function Reference/get header|get_header()]]</tt> template tag.
 
* To include the sidebar, use the <tt>[[Function Reference/get sidebar|get_sidebar()]]</tt> template tag.
 
* To include the footer, use the <tt>[[Function Reference/get footer|get_footer()]]</tt> template tag.
 
   
  +
This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/advanced-topics/plugin-api-hooks/
Here is an example of the ''include'' usage:
 
   
  +
==== Theme Customization API ====
<pre>
 
<?php get_sidebar(); ?>
 
   
  +
This section has moved to the Theme Developer Handbook:
<?php get_footer(); ?>
 
  +
https://developer.wordpress.org/themes/customize-api/
</pre>
 
   
  +
==== Untrusted Data ====
For more on how these various Templates work and how to generate different information within them, read the [[Templates]] documentation.
 
   
  +
This section has moved to the Security page in the Common APIs Handbook:
=='''Query-based Templates'''==
 
  +
https://developer.wordpress.org/apis/security/
   
WordPress can load different [[Stepping Into Templates|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.
 
   
  +
==== Translation Support / I18n ====
To use the [[Template Hierarchy]], you basically need to provide special-purpose Template files, which will automatically be used to override <tt>index.php</tt>. For instance, if your Theme provides a template called <tt>category.php</tt> and a category is being queried, <tt>category.php</tt> will be loaded instead of <tt>index.php</tt>. If <tt>category.php</tt> is not present, <tt>index.php</tt> is used as usual.
 
   
  +
To ensure smooth transition for language localization, use the WordPress gettext-based [[I18n for WordPress Developers|i18n]] functions for wrapping all translatable text within the template files. This makes it easier for the translation files to hook in and translate the labels, titles and other template text into the site's current language. See more at [[WordPress Localization]] and [[I18n for WordPress Developers]].
You can get even more specific in the Template Hierarchy by providing a file called, for instance, <tt>category-6.php</tt> -- this file will be used rather than <tt>category.php</tt> when generating the page for the category whose ID number is 6. (You can find category ID numbers in [[Administration_Panels#Manage_-_Change_your_content|Manage]] > [[Administration_Panels#Categories|Categories]] if you are logged in as the site administrator in WordPress version 2.3 and below. In WordPress 2.5 the ID column was removed from the Admin panels. You can locate the category id by clicking 'Edit Category' and looking on the URL address bar for the cat_ID value. It will look '...categories.php?action=edit&cat_ID=3' where '3' is the category id). For a more detailed look at how this process works, see [[Category Templates]].
 
   
  +
==== Theme Classes ====
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 [[The_Loop_in_Action|WordPress Loop]], and then you can load a particular template, or put some particular text on the screen, based on that condition.
 
   
  +
Implement the following template tags to add WordPress-generated class attributes to body, post, and comment elements. For post classes, apply only to elements within [[The Loop]].
For example, to generate a distinctive style sheet in a post only found within a specific category, the code might look like this:
 
   
  +
* [[Function Reference/body class|body_class()]]
<pre><?php
 
  +
* [[Function Reference/post class|post_class()]]
if (is_category(9)) {
 
  +
* [[Function Reference/comment class|comment_class()]]
// looking for category 9 posts
 
include(TEMPLATEPATH . '/single2.php');
 
} else {
 
// put this on every other category post
 
include(TEMPLATEPATH . '/single1.php');
 
}
 
?></pre>
 
   
  +
=== Template File Checklist ===
Or, using a query, it might look like this:
 
   
  +
When developing a Theme, check your template files against the following template file standards.
<pre><?php
 
$post = $wp_query->post;
 
if ( in_category('9') ) {
 
include(TEMPLATEPATH . '/single2.php');
 
} else {
 
include(TEMPLATEPATH . '/single1.php');
 
}
 
?></pre>
 
   
  +
==== Document Head (header.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.
 
   
  +
* Use the proper [http://en.wikipedia.org/wiki/Document_Type_Declaration DOCTYPE].
== Media Icons ==
 
  +
* The opening <tt><html></tt> tag should include [[Function_Reference/language_attributes|<tt>language_attributes()</tt>]].
  +
* The <tt><meta></tt> charset element should be placed before everything else, including the <tt><title></tt> element.
  +
* Use [[Function_Reference/bloginfo|<tt>bloginfo()</tt>]] to set the <tt><meta></tt> charset and description elements.
  +
* Use [[Function_Reference/wp_title|<tt>wp_title()</tt>]] to set the <tt><title></tt> element. [[Function_Reference/wp_title#Note|See why]].
  +
* Use [[Automatic Feed Links]] to add feed links.
  +
* Add a call to [[Function_Reference/wp_head|<tt>wp_head()</tt>]] before the closing <tt></head></tt> tag. Plugins use this [[Plugin API/Action Reference|action hook]] to add their own scripts, stylesheets, and other functionality.
  +
* Do not link the theme stylesheets in the Header template. Use the [[Plugin_API/Action_Reference/wp_enqueue_scripts|<tt>wp_enqueue_scripts</tt>]] action hook in a theme function instead.
   
  +
Here's an example of a correctly-formatted HTML5 compliant head area:
'''This feature is [http://trac.wordpress.org/ticket/6751 currently broken in WordPress 2.5].'''
 
   
  +
<pre>
Wordpress uses media icons to represent [[Using_Image_and_File_Attachments|attachment files]] on your blog and in the Admin interface, if those icons are available.
 
  +
<!DOCTYPE html>
  +
<html <?php language_attributes(); ?>>
  +
<head>
  +
<meta charset="<?php bloginfo( 'charset' ); ?>" />
  +
<title><?php wp_title(); ?></title>
  +
<link rel="profile" href="http://gmpg.org/xfn/11" />
  +
<link rel="pingback" href="<?php bloginfo( 'pingback_url' ); ?>" />
  +
<?php if ( is_singular() && get_option( 'thread_comments' ) ) wp_enqueue_script( 'comment-reply' ); ?>
  +
<?php wp_head(); ?>
  +
</head>
  +
</pre>
   
  +
==== Navigation Menus (''header.php'') ====
It looks for image files named by media type in the <tt>images</tt> directory of the current theme. (As of Wordpress 2.2, the default theme comes with only one media icon, <tt>audio.jpg</tt>.)
 
   
  +
* The Theme's main navigation should support a custom menu with [[Function_Reference/wp_nav_menu|<tt>wp_nav_menu()</tt>]].
For example, for an attachment of [http://en.wikipedia.org/wiki/Internet_media_type MIME type] <tt>audio/mpeg</tt>, Wordpress would look for an icon file at these locations, stopping after the first match (see <tt>[[Function_Reference/wp_mime_type_icon|wp_mime_type_icon]]</tt>):
 
  +
** Menus should support long link titles and a large amount of list items. These items should not break the design or layout.
  +
** Submenu items should display correctly. If possible, support drop-down menu styles for submenu items. Drop-downs allowing showing menu depth instead of just showing the top level.
  +
  +
==== Widgets (''sidebar.php'') ====
  +
  +
* The Theme should be widgetized as fully as possible. Any area in the layout that works like a widget (tag cloud, blogroll, list of categories) or could accept widgets (sidebar) should allow widgets.
  +
* Content that appears in widgetized areas by default (hard-coded into the sidebar, for example) should disappear when widgets are enabled from Appearance > Widgets.
  +
  +
==== Footer (''footer.php'') ====
  +
  +
* Use the [[Function_Reference/wp_footer|<tt>wp_footer()</tt>]] call, to appear just before closing <tt>body</tt> tag.
  +
  +
<pre>
  +
<?php wp_footer(); ?>
  +
</body>
  +
</html>
  +
</pre>
   
  +
==== Index (''index.php'') ====
# <var>my_theme</var>/images/audio.jpg
 
# <var>my_theme</var>/images/audio.gif
 
# <var>my_theme</var>/images/audio.png
 
# <var>my_theme</var>/images/mpeg.jpg
 
# <var>my_theme</var>/images/mpeg.gif
 
# <var>my_theme</var>/images/mpeg.png
 
# <var>my_theme</var>/images/audio_mpeg.jpg
 
# <var>my_theme</var>/images/audio_mpeg.gif
 
# <var>my_theme</var>/images/audio_mpeg.png
 
   
  +
* Display a list of posts in excerpt or full-length form. Choose one or the other as appropriate.
==Theme Template Files List==
 
  +
* Include [[Function_Reference/wp_link_pages|<tt>wp_link_pages()</tt>]] to support navigation links within posts.
   
  +
==== Archive (''archive.php'') ====
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.''
 
   
  +
* Display archive title (tag, category, date-based, or author archives).
;<tt>style.css</tt>: The main stylesheet. This '''must''' be included with your Theme, and it must contain the information header for your Theme.
 
  +
* Display a list of posts in excerpt or full-length form. Choose one or the other as appropriate.
;<tt>index.php</tt>: The main template. If your Theme provides its own templates, <tt>index.php</tt> must be present.
 
  +
* Include [[Function_Reference/wp_link_pages|<tt>wp_link_pages()</tt>]] to support navigation links within posts.
;<tt>comments.php</tt>: The comments template. If not present, <tt>comments.php</tt> from the "default" Theme is used. Note that you should include your own, as "default" may not be present, or change (ie, 2010 theme).
 
;<tt>[[FAQ Working with WordPress#Can I have popup comments?|comments-popup.php]]</tt>: The popup comments template. If not present, <tt>comments-popup.php</tt> from the "default" Theme is used. Note that you should include your own, as "default" may not be present, or change (ie, 2010 theme).
 
;<tt>home.php</tt>: The home page template.
 
;<tt>single.php</tt>: The single post template. Used when a single post is queried. For this and all other query templates, <tt>index.php</tt> is used if the query template is not present.
 
;<tt>single-<post-type>.php</tt>: The single post template used when a single post from a custom post type is queried. For example, <tt>single-books.php</tt> would be used for displaying single posts from the custom post type <tt>books</tt>. <tt>index.php</tt> is used if the query template for the custom post type is not present.
 
;<tt>page.php</tt>: The page template. Used when an individual [[Pages|Page]] is queried.
 
;<tt>category.php</tt>: The [[Category Templates|category template]]. Used when a category is queried.
 
;<tt>tag.php</tt>: The [[Tag Templates|tag template]]. Used when a tag is queried.
 
;<tt>taxonomy.php</tt>: The [[Taxonomy Templates|term template]]. Used when a term in a custom taxonomy is queried.
 
;<tt>author.php</tt>: The [[Author Templates|author template]]. Used when an author is queried.
 
;<tt>date.php</tt>: The date/time template. Used when a date or time is queried. Year, month, day, hour, minute, second.
 
;<tt>archive.php</tt>: The archive template. Used when a category, author, or date is queried. Note that this template will be overridden by <tt>category.php</tt>, <tt>author.php</tt>, and <tt>date.php</tt> for their respective query types.
 
;<tt>search.php</tt>: The search results template. Used when a search is performed.
 
;<tt>404.php</tt>: The '''[[Creating_an_Error_404_Page|404 Not Found]]''' template. Used when WordPress cannot find a post or page that matches the query.
 
   
  +
==== Pages (''page.php'') ====
These files have a special meaning with regard to WordPress because they are used as a replacement for <tt>index.php</tt>, when available, according to the [[Template Hierarchy]], and when the corresponding [[Conditional Tags|Conditional Tag]] (a.k.a <tt>is_*();</tt> function) returns true. For example, if only a single post is being displayed, the <tt>[[Conditional Tags#A Single Post Page|is_single()]]</tt> function returns 'true', and, if there is a <tt>single.php</tt> file in the active Theme, that template is used to generate the page.
 
   
  +
* Display page title and page content.
==Referencing Files From a Template==
 
  +
* Display comment list and comment form (unless comments are off).
  +
* Include [[Function_Reference/wp_link_pages|<tt>wp_link_pages()</tt>]] to support navigation links within a page.
  +
* Metadata such as tags, categories, date and author should not be displayed.
  +
* Display an "Edit" link for logged-in users with edit permissions.
   
  +
==== Single Post (''single.php'') ====
The WordPress Default Theme (based on Michael Heilemann's [http://binarybonsai.com/kubrick/ Kubrick] layout for WordPress 1.2) provides a good example of how queries are mapped onto templates.
 
   
  +
* Include [[Function_Reference/wp_link_pages|<tt>wp_link_pages()</tt>]] to support navigation links within a post.
The code <tt><?php bloginfo('template_directory'); ?></tt> 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.
 
  +
* Display post title and post content.
  +
** The title should be plain text instead of a link pointing to itself.
  +
* Display the post date.
  +
** Respect the [[Settings General Screen|date and time format settings]] unless it's important to the design. (User settings for date and time format are in [[Administration Panels]] > [[Administration Panels#Settings|Settings]] > [[Administration Panels#General|General]]).
  +
** For output based on the user setting, use <tt>the_time( get_option( 'date_format' ) )</tt>.
  +
* Display the author name (if appropriate).
  +
* Display post categories and post tags.
  +
* Display an "Edit" link for logged-in users with edit permissions.
  +
* Display comment list and comment form.
  +
* Show navigation links to next and previous post using [[Function_Reference/previous_post_link|<tt>previous_post_link()</tt>]] and [[Function_Reference/next_post_link|<tt>next_post_link()</tt>]].
   
  +
==== Comments (''comments.php'') ====
The code <tt><?php bloginfo('stylesheet_directory'); ?></tt> 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.
 
   
  +
* Author comment should be highlighted differently.
The constant TEMPLATEPATH is a reference to the absolute path to the template directory for the current Theme (without the / at the end).
 
  +
* Display gravatars (user avatars) if appropriate.
  +
* Support threaded comments.
  +
* Display trackbacks/pingbacks.
  +
* This file shouldn’t contain function definitions unless in the [http://php.net/manual/en/function.function-exists.php <tt>function_exist()</tt>] check to avoid redeclaration errors. Ideally all functions should be in ''functions.php''.
   
  +
==== Search Results (''search.php'') ====
Note that URIs that are used in the stylesheet are relative to the stylesheet, not the page that references the stylesheet. For example, if you include an <tt>images/</tt> directory in your Theme, you need only specify this relative directory in the CSS, like so:
 
   
  +
* Display a list of posts in excerpt or full-length form. Choose one or the other as appropriate.
<pre style="font-size: 0.9em">h1 { background-image: URL(images/my_background.jpg); }</pre>
 
  +
* The search results page shows the search term which generated the results. It's a simple but useful way to remind someone what they just searched for -- especially in the case of zero results. Use [[Function_Reference/the_search_query|<tt>the_search_query()</tt>]] or [[Function_Reference/get_search_query|<tt>get_search_query()</tt>]] (display or return the value, respectively). For example: <pre><h2><?php printf( __( 'Search Results for: %s' ), '<span>' . get_search_query() . '</span>'); ?></h2></pre>
  +
* It's a good practice to include the search form again on the results page. Include it with: [[Function_Reference/get_search_form|<tt>get_search_form()</tt>]].
   
  +
=== JavaScript ===
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.
 
   
  +
This section has moved to the Theme Developer Handbook:
==Defining Custom Templates==
 
  +
https://developer.wordpress.org/themes/basics/including-css-javascript/
   
  +
=== Screenshot ===
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 <tt>template_redirect</tt> [[Plugin API#Current Hooks For Actions|action hook]]. More information about creating plugins can be found in the [[Plugin API]] reference.
 
   
  +
Create a screenshot for your theme. The screenshot should be named ''screenshot.png'', and should be placed in the top level directory. The screenshot should accurately show the theme design and saved in PNG format. While .jpg, .jpeg, and .gif are also valid extensions and file formats for the screenshot, they are not recommended.
==Plugin API Hooks==
 
   
  +
The recommended image size is 1200px wide by 900px tall. The screenshot will usually be shown smaller but the over-sized image allows for high-resolution viewing on HiDPI displays. Note that because the Manage Themes screen is responsive, the top and bottom of the screenshot image might not be viewable so keep graphics near the center.
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:
 
   
  +
=== Theme Options ===
; wp_head
 
: Goes in the [[Glossary#HTML|HTML]] <tt>&lt;head&gt;</tt> element of a theme; <tt>header.php</tt> template. Example plugin use: add javascript code.
 
   
  +
Themes can optionally support the [[Appearance Customize Screen|Theme Customize Screen]]. For an example code, see [http://themeshaper.com/sample-theme-options/ A Sample WordPress Theme Options Page].
: Usage: <tt><nowiki><?php do_action('wp_head'); ?></nowiki></tt>
 
:''-or-''&nbsp; <tt><nowiki><?php wp_head(); ?></nowiki></tt>
 
   
  +
When enabling the availability of the Theme Customize Screen for a user [[Roles and Capabilities#Roles|role]], use the "edit_theme_options" user capability instead of the "switch_themes" capability unless the user role actually should also be able to switch the themes. See more at [[Roles and Capabilities#Capabilities|Roles and Capabilities]] and [[Adding Administration Menus]].
; wp_footer
 
: Goes in the "footer" of a theme; <tt>footer.php</tt> template. Example plugin use: insert PHP code that needs to run after everything else, at the bottom of the footer.
 
   
  +
If you are using the "edit_themes" capability anywhere in your Theme to gain the Administrator role access to the Theme Customize Screen (or maybe some custom screens), be aware that since [[Version 3.0]], this capability has not been assigned to the Administrator role by default in the case of WordPress [[Glossary#Multisite|Multisite]] installation. See [http://wordpress.org/support/topic/capability-manage_options-vs-edit_themes#post-1566844 the explanation]. In such a case, use the "edit_theme_options" capability instead if you want the Administrator to see the "Theme Options" menu. See the [[Roles and Capabilities#Additional_Admin_Capabilities|additional capabilities]] of Administrator role when using WordPress Multisite.
: Usage: <tt><nowiki><?php do_action('wp_footer'); ?></nowiki></tt>
 
:''-or-''&nbsp; <tt><nowiki><?php wp_footer(); ?></nowiki></tt>
 
   
  +
== Theme Testing Process ==
; wp_meta
 
: Typically goes in the <tt><nowiki><li>Meta</li></nowiki></tt> section of a theme's menu or sidebar; <tt>sidebar.php</tt> template. Example plugin use: include a rotating advertisement or a tag cloud.
 
   
  +
This section has moved to the Theme Developer Handbook:
: Usage: <tt><nowiki><?php do_action('wp_meta'); ?></nowiki></tt>
 
  +
https://developer.wordpress.org/themes/advanced-topics/theme-testing/
:''-or-''&nbsp; <tt><nowiki><?php wp_meta(); ?></nowiki></tt>
 
   
  +
== Resources and References ==
; comment_form
 
: Goes in <tt>comments.php</tt> and <tt>comments-popup.php</tt>, directly before the comment form's closing tag (<code><nowiki></form></nowiki></code>). Example plugin use: display a comment preview.
 
   
  +
=== Code Standards ===
: Usage: <tt><nowiki><?php do_action('comment_form', $post->ID); ?></nowiki></tt>
 
  +
* [[Know Your Sources]]
  +
* [[WordPress Coding Standards]]
  +
* [[CSS Coding Standards]]
   
  +
=== Theme Design ===
For a real world usage example, you'll find these plugin hooks included in the default theme's templates.
 
  +
* [[Site Design and Layout]]
   
  +
=== CSS ===
==Theme Development General Guidelines==
 
  +
* [[CSS]]
  +
* [[CSS Shorthand]]
  +
* [[CSS#WordPress_Generated_Classes|WordPress Generated Classes]]
   
  +
=== 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):
 
  +
* [[Stepping Into Templates]]
# Indicate precisely what your Theme and template files will achieve.
 
  +
* [[Templates]]
# Adhere to the naming conventions of the standard theme hierarchy.
 
  +
* [[Template Hierarchy]]
# Indicate deficiencies in your Themes, if any.
 
  +
* [[Template Tags]]
# Clearly reference any special modifications in [[Commenting_Code|comments]] within the template and style sheet files. Add comments to modifications, template sections, and CSS styles, especially those which cross template files.
 
  +
* [[The Loop]]
# If you have any special requirements, which may include custom Rewrite Rules, or the use of some additional, special templates, images or files, please explicitly state the steps of action a user should take to get your Theme working.
 
  +
* [[Conditional Tags]]
# Try and test your Theme [[CSS_Fixing_Browser_Bugs|across browsers]] to catch at least a few of the [[CSS_Troubleshooting|problems]] the users of the Theme may find later.
 
  +
* [[Function Reference]]
# Provide contact information (web page or email), if possible, for support information and questions.
 
  +
* [[I18n for WordPress Developers]]
  +
* [[Data Validation]]
   
  +
=== Functions listing ===
Take time to read through [[Designing Themes for Public Release]], an article with good tips on preparing your Theme for the public.
 
  +
* [[Function Reference]]
   
==References and Resources==
+
=== Testing and QA ===
  +
* [[Theme Unit Test]]
  +
* [[Validating a Website]]
  +
* [[CSS Fixing Browser Bugs]]
  +
* [[CSS Troubleshooting]]
   
  +
=== Release & Promotion ===
There is a comprehensive list of WordPress Theme and Template File resources in the [[Templates]] article.
 
  +
* [[Theme Review|Theme Review Process]]
   
 
[[Category:Design and Layout]]
 
[[Category:Design and Layout]]

Latest revision as of 08:53, 20 February 2023

This article is about developing WordPress Themes. If you wish to learn more about how to install and use Themes, review 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.

Why WordPress Themes

WordPress Themes are files that work together to create the design and functionality of a WordPress site. Each Theme may be different, offering many choices for site owners to instantly change their website look.

You may wish to develop WordPress Themes for your own use, for a client project or to submit to the WordPress Theme Directory. Why else should you build a WordPress Theme?

  • To create a unique look for your WordPress site.
  • To take advantage of templates, template tags, and the WordPress Loop to generate different website results and looks.
  • To provide alternative templates for specific site features, such as category pages and search result pages.
  • To quickly switch between two site layouts, or to take advantage of a Theme or style switcher to allow site owners to change the look of your site.

A WordPress Theme has many benefits, too.

  • It separates the presentation styles and template files from the system files so the site will upgrade without drastic changes to the visual presentation of the site.
  • It allows for customization of the site functionality unique to that Theme.
  • It allows for quick changes of the visual design and layout of a WordPress site.
  • It removes the need for a typical WordPress site owner to have to learn CSS, HTML, and PHP in order to have a great-looking website.

Why should you build your own WordPress Theme? That's the real question.

  • It's an opportunity to learn more about CSS, HTML, and PHP.
  • It's an opportunity to put your expertise with CSS, HTML, and PHP to work.
  • It's creative.
  • It's fun (most of the time).
  • If you release it to the public, you can feel good that you shared and gave something back to the WordPress Community (okay, bragging rights)

Theme Development Standards

WordPress Themes should be coded using the following standards:

Anatomy of a Theme

WordPress Themes live in subdirectories of the WordPress themes directory (wp-content/themes/ by default) which cannot 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.

WordPress includes a default theme in each new installation. Examine the files in the default theme carefully to get a better idea of how to build your own Theme files.

For a visual guide, see this infographic on WordPress Theme Anatomy.

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.

Let's look at these individually.

Child Themes

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/advanced-topics/child-themes/

Theme Stylesheet

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/basics/main-stylesheet-style-css/

Functions File

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/basics/theme-functions/

Template Files

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/basics/template-files/

Custom Page Templates

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/template-files-section/page-template-files/#creating-custom-page-templates-for-global-use

Query-based Template Files

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/template-files-section/taxonomy-templates/

Defining Custom Templates

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_include" action hook. More information about creating plugins can be found in the Plugin API reference.

Including Template Files

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/template-files-section/partial-and-miscellaneous-template-files/

Referencing Files From a Template

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/functionality/media/

Plugin API Hooks

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/advanced-topics/plugin-api-hooks/

Theme Customization API

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/customize-api/

Untrusted Data

This section has moved to the Security page in the Common APIs Handbook: https://developer.wordpress.org/apis/security/


Translation Support / I18n

To ensure smooth transition for language localization, use the WordPress gettext-based i18n functions for wrapping all translatable text within the template files. This makes it easier for the translation files to hook in and translate the labels, titles and other template text into the site's current language. See more at WordPress Localization and I18n for WordPress Developers.

Theme Classes

Implement the following template tags to add WordPress-generated class attributes to body, post, and comment elements. For post classes, apply only to elements within The Loop.

Template File Checklist

When developing a Theme, check your template files against the following template file standards.

Document Head (header.php)

  • Use the proper DOCTYPE.
  • The opening <html> tag should include language_attributes().
  • The <meta> charset element should be placed before everything else, including the <title> element.
  • Use bloginfo() to set the <meta> charset and description elements.
  • Use wp_title() to set the <title> element. See why.
  • Use Automatic Feed Links to add feed links.
  • Add a call to wp_head() before the closing </head> tag. Plugins use this action hook to add their own scripts, stylesheets, and other functionality.
  • Do not link the theme stylesheets in the Header template. Use the wp_enqueue_scripts action hook in a theme function instead.

Here's an example of a correctly-formatted HTML5 compliant head area:

<!DOCTYPE html>
<html <?php language_attributes(); ?>>
    <head>
        <meta charset="<?php bloginfo( 'charset' ); ?>" />
        <title><?php wp_title(); ?></title>
        <link rel="profile" href="http://gmpg.org/xfn/11" />
        <link rel="pingback" href="<?php bloginfo( 'pingback_url' ); ?>" />
        <?php if ( is_singular() && get_option( 'thread_comments' ) ) wp_enqueue_script( 'comment-reply' ); ?>
        <?php wp_head(); ?>
    </head>

Navigation Menus (header.php)

  • The Theme's main navigation should support a custom menu with wp_nav_menu().
    • Menus should support long link titles and a large amount of list items. These items should not break the design or layout.
    • Submenu items should display correctly. If possible, support drop-down menu styles for submenu items. Drop-downs allowing showing menu depth instead of just showing the top level.

Widgets (sidebar.php)

  • The Theme should be widgetized as fully as possible. Any area in the layout that works like a widget (tag cloud, blogroll, list of categories) or could accept widgets (sidebar) should allow widgets.
  • Content that appears in widgetized areas by default (hard-coded into the sidebar, for example) should disappear when widgets are enabled from Appearance > Widgets.

Footer (footer.php)

  • Use the wp_footer() call, to appear just before closing body tag.
<?php wp_footer(); ?>
</body>
</html>

Index (index.php)

  • Display a list of posts in excerpt or full-length form. Choose one or the other as appropriate.
  • Include wp_link_pages() to support navigation links within posts.

Archive (archive.php)

  • Display archive title (tag, category, date-based, or author archives).
  • Display a list of posts in excerpt or full-length form. Choose one or the other as appropriate.
  • Include wp_link_pages() to support navigation links within posts.

Pages (page.php)

  • Display page title and page content.
  • Display comment list and comment form (unless comments are off).
  • Include wp_link_pages() to support navigation links within a page.
  • Metadata such as tags, categories, date and author should not be displayed.
  • Display an "Edit" link for logged-in users with edit permissions.

Single Post (single.php)

  • Include wp_link_pages() to support navigation links within a post.
  • Display post title and post content.
    • The title should be plain text instead of a link pointing to itself.
  • Display the post date.
  • Display the author name (if appropriate).
  • Display post categories and post tags.
  • Display an "Edit" link for logged-in users with edit permissions.
  • Display comment list and comment form.
  • Show navigation links to next and previous post using previous_post_link() and next_post_link().

Comments (comments.php)

  • Author comment should be highlighted differently.
  • Display gravatars (user avatars) if appropriate.
  • Support threaded comments.
  • Display trackbacks/pingbacks.
  • This file shouldn’t contain function definitions unless in the function_exist() check to avoid redeclaration errors. Ideally all functions should be in functions.php.

Search Results (search.php)

  • Display a list of posts in excerpt or full-length form. Choose one or the other as appropriate.
  • The search results page shows the search term which generated the results. It's a simple but useful way to remind someone what they just searched for -- especially in the case of zero results. Use the_search_query() or get_search_query() (display or return the value, respectively). For example:
    <h2><?php printf( __( 'Search Results for: %s' ), '<span>' . get_search_query() . '</span>'); ?></h2>
  • It's a good practice to include the search form again on the results page. Include it with: get_search_form().

JavaScript

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/basics/including-css-javascript/

Screenshot

Create a screenshot for your theme. The screenshot should be named screenshot.png, and should be placed in the top level directory. The screenshot should accurately show the theme design and saved in PNG format. While .jpg, .jpeg, and .gif are also valid extensions and file formats for the screenshot, they are not recommended.

The recommended image size is 1200px wide by 900px tall. The screenshot will usually be shown smaller but the over-sized image allows for high-resolution viewing on HiDPI displays. Note that because the Manage Themes screen is responsive, the top and bottom of the screenshot image might not be viewable so keep graphics near the center.

Theme Options

Themes can optionally support the Theme Customize Screen. For an example code, see A Sample WordPress Theme Options Page.

When enabling the availability of the Theme Customize Screen for a user role, use the "edit_theme_options" user capability instead of the "switch_themes" capability unless the user role actually should also be able to switch the themes. See more at Roles and Capabilities and Adding Administration Menus.

If you are using the "edit_themes" capability anywhere in your Theme to gain the Administrator role access to the Theme Customize Screen (or maybe some custom screens), be aware that since Version 3.0, this capability has not been assigned to the Administrator role by default in the case of WordPress Multisite installation. See the explanation. In such a case, use the "edit_theme_options" capability instead if you want the Administrator to see the "Theme Options" menu. See the additional capabilities of Administrator role when using WordPress Multisite.

Theme Testing Process

This section has moved to the Theme Developer Handbook: https://developer.wordpress.org/themes/advanced-topics/theme-testing/

Resources and References

Code Standards

Theme Design

CSS

Templates

Functions listing

Testing and QA

Release & Promotion