Theme Development

WordPress Theme Files

WordPress theme files are just PHP files used to display the HTML and the database output of your WordPress website. Theme files should be used to style your website and not to expand the functionality of your WordPress website. All themes can be very different and you can create many different types of websites, from blogs, to member sites, to ecommerce sites, the flexibility and ease of WordPress themes is one of the main reasons the CMS has become as popular as it is.

There is normally some confusion with developers starting out with WordPress as to where to place certain bits of code. A good thing to remember in theme development is to place anything that changes the look of the site in the theme and anything that changes the functionality in a plugin. This is because when you change themes, you just want to change the look of the site and not the functionality.

There are many files you can use in your theme, in this tutorial we are going to go through all these files you can include in your theme. WordPress also uses a file hierarchy to decide which file to use at a certain time.

Where Theme Files Are Stored?

The WordPress theme files will be stored inside their own folder and placed in the wp-content/themes/ folder. Inside this folder will be all the files to create your theme, the stylesheet, template files, images and any Javascript files which your theme needs to function correctly.

The basic WordPress install comes with a default theme, named after the year of the WordPress release. At the moment this default theme is called twentythirteen and gives you a good template to base the rest of your themes on. You can even use this as a child theme for any new themes that you create.

Child Themes

When you create a new WordPress theme you have to create all the files from scratch the most important file in your theme is the style.css file. This stylesheet file will define the name of the current theme and this is where you will register if your theme is a child theme. A child theme will allow you to inherit all the files in the parent theme and use these in your child theme.

By inheriting this theme you can have the exact same functionality as the parent theme, but just change the style.css to edit the way the theme looks. Any file that isn't in the child theme will be inherited from the parent theme, you can overwrite these parent theme files by simply creating them in the child theme.

The theme twentythirteen is built by the WordPress.org developers, if you are starting out in theme developer I recommend using this as your parent theme, this way you inherit all it's functionality and can simply just change the style and you have a new theme.

Manage Themes ‹ Dev WordPress — WordPress

Parent themes can be used as a framework for all your future theme development, you can continue to build on this parent theme and all child themes will inherit it's functionality. There can many big WordPress theme frameworks which are simply a parent theme.

To inherit a parent theme define the option Template in the style.css comments.

Template:       twentythirteen

Theme Stylesheet - style.css

The theme stylesheet style.css is the most important file in your theme, a theme does not exist without this file. The comments in the stylesheet will be used to tell WordPress the important information for the theme. Here you will define:

  • Theme Name
  • Theme URI
  • Author
  • Author URI
  • Description
  • Version
  • License
  • Tags
  • Parent Theme

Here is an example of the comments you need to include in your stylesheet.

/*
Theme Name: Twenty Thirteen
Theme URI: http://wordpress.org/themes/twentythirteen
Author: the WordPress team
Author URI: http://wordpress.org/
Description: The 2013 theme for WordPress takes us back to the blog, featuring a full range of post formats, each displayed beautifully in their own unique way. Design details abound, starting with a vibrant color scheme and matching header images, beautiful typography and icons, and a flexible layout that looks great on any device, big or small.
Version: 1.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Tags: black, brown, orange, tan, white, yellow, light, one-column, two-columns, right-sidebar, flexible-width, custom-header, custom-menu, editor-style, featured-images, microformats, post-formats, rtl-language-support, sticky-post, translation-ready
Text Domain: twentythirteen

This theme, like WordPress, is licensed under the GPL.
Use it to make something cool, have fun, and share what you've learned with others.
*/

If you are creating a new child theme then this style.css will override the parent theme stylesheet, so the styling of your new theme will be blank. If you want to use the parent theme styling too, you need to import this at the top of your stylesheet.

@import url("../twentythirteen/style.css");

Theme Functions.php File

The functions.php file will have access to create new functions to attach to all WordPress hooks and filters. The theme functions.php file used to add additional PHP code to your theme, this is an area where most developers new to WordPress will get confused. People think that you should use this instead of a plugin. This file will run PHP code exactly the same as a plugin will do. You should only use the functions.php file to add functionality that will aid the design of your website.

You should not place code in your functions.php that you want to keep in future themes, anything that you will need in other themes should be moved into a plugin. This is so when you change themes in the future you will not lose this functionality. You see a lot of theme developers adding code to add the Google Analytics code to the footer of the website, this should not go in the functions.php file. When you change themes you will lose this code and will have to remember to add the Google Analytics code again.

When using a child theme this file is different to the others in the theme document, when you create new files in the child theme they will override the parent theme files. This is different with the functions.php file, you will not override the parent functions.php file but will inherit all it's code. This is the reason why many parent themes can be used as theme frameworks as you can place generic code in the parent theme functions.php file and all child themes will inherit this same code.

If you have bought a premium theme that is getting continuous updates then you don't want to change the code in that functions.php file as when this theme gets updated it will override the change you did.

The best way to handle this problem is to create a child theme and use this premium theme as the parent, then you put your new code changes in the child theme functions.php file. Then any changes that happen on the parent theme functions.php file will not override your changes.

Override Parent Functions

The child theme functions.php file is loaded before the parents functions.php file, this means that you should be able to override any of the parents theme functions with your own functions. But you are only able to do this if the parent theme is setup correctly.

Consider this example of a parent theme having a function to display social links for the website but only has Facebook link.

Parent Theme

<?php
function display_social_links()
{
     ?>
         <a href="http://www.facebook.com">Facebook</a>
     <?php
}
?>

In all your theme files where you want social links you can just use the above function.

But in your child theme you want to override this function so that you can include twitter in these social links. An option is to create a new function, but then have to change all your theme files with this new function or you can override the existing function so you don't have to change the other theme files.

To override the parent function you need to add the same function into your child themes functions.php, then you can add your new Twitter link.

Child Theme

function display_social_links()
{
     ?>
         <a href="http://www.facebook.com">Facebook</a>
         <a href="http://www.twitter.com">Twitter</a>
     <?php
}
?>

I'm sorry to say but this code will break your website, you will get a function already defined error in your parents theme functions.php file. This is because the child theme function doesn't override the parents theme function but will just define this function before the parents file is defined. The way that you will be able to override this function is if the parent function is wrapped in a IF statement of function_exists.

Parent Theme

<?php
if( !function_exists('display_social_links') )
{
function display_social_links()
{
     ?>
         <a href="http://www.facebook.com">Facebook</a>
     <?php
}
}
?>

This code means that if the function display_social_links hasn't been defined then you are able to define it with this function. As your child theme functions are defined before the parent theme then if the function display_social_links is defined in the child theme then the code will not go into this IF statement and you avoid the function is already defined error.

This means that you are only able to override parent theme functions if they are wrapped in a function_exists IF statement.

<?php
if( !function_exists('display_social_links') )
{

}
?>

If the function in the parents theme does not have this IF statement then the developer has intended for you to not be able to override this function.

Template File List

There are a number of different files that WordPress can expect in the theme, they will each do different things in the theme and WordPress will refer to them at different times, the following are all the common files that WordPress will expect to find in the theme.

style.css

This is the main stylesheet for the theme and the most important file in the theme, without this file WordPress will not know that directory is a WordPress theme. The comments in this file is where you will define all the information for the website.

rtl.css

This stylesheet is automatically used if the website is define to use the text right to left.

index.php

This is the main content file in your theme, if this is a parent theme it must provide a index.php file. If this file does not exist then nothing will be displayed on the homepage of the website.

comments.php

This is the file where you will add the code to display the comments for a post and the comment form to add a new comment to the post. This file is called when WordPress see's the function comments_template‎().

front-page.php

In WordPress you can define to use a static front page instead of the default list of recent posts. If you want your static front page to have a different design to the rest of your site then you can create a front-page.php file.

home.php

If you don't want to use a static front page but still want your home page to be slightly different to the rest of your site you can create a home.php file which WordPress will use on the homepage of your site.

If the home.php file doesn't exist then WordPress will use the index.php file to display the homepage content.

  • home.php
  • index.php

single.php

The single.php file is the template used on single posts. If this file doesn't exist then the index.php file is used. If your site has custom post types, WordPress will display the content with this file by default but you can define a different style for this content type by creating the file single-{post-type}.php.

For example if you create a new portfolio post type and want to style this differently, create a file for single-portfolio.php.

If your theme didn't have a custom post type template file or a single.php file then WordPress will use the index.php file to display the content.

  • single-{post_type}.php
  • single.php
  • index.php

page.php

The page.php file is used when single pages are displayed, if this file doesn't exist then WordPress will display the content with the index.php file.

You can also set a new page template by page ID or by page slug by using the template filename of page-{ID}.php pr page-{SLUG}.php.

  • custom template file
  • page-{slug}.php
  • page-{id}.php
  • page.php
  • index.php

category.php

When a category is displayed in WordPress it will use the index.php file by default unless the category.php file is in the theme, then this file will be used to display posts.

If you want to use a different template file for each category you can create a new template for each category by using the file name category-{ID}.php or category-{SLUG}.php.

If there is no category page then WordPress could also use the archive.php file to display the category lists.

  • category-{slug}.php
  • category-{id}.php
  • category.php
  • archive.php
  • index.php

tag.php

The tag.php file will display a list of posts with the queried tag, if the tag.php file doesn't exist then the index.php file is used.

The tag.php file is similar to the category page as you can display a single tag differently to the others by creating a new file of tag-{ID}.php or tag-{SLUG}.php.

If WordPress can now find any of these files it can use the archive.php file to display the tag list posts.

  • tag-{slug}.php
  • tag-{id}.php
  • tag.php
  • archive.php
  • index.php

taxonomy.php

If your website has a custom taxonomy then this file will be used to display the the taxonomy term.

If you want to use different layout for a single taxonomy you can use the file taxonomy-{taxonomy}-{term}.php.

If these taxonomy files are not in the theme WordPress will search for the archive.php file to display the list of posts.

  • taxonomy-{taxonomy}-{term}.php
  • taxonomy-{taxonomy}.php
  • taxonomy.php
  • archive.php
  • index.php

author.php

In WordPress the author can have their own pages to display more information about themselves, you can use the author.php file to display this author page.

The Author page can also be displayed by creating a theme file for author-{nicename}.php or by creating a file for author-{ID}.php.

  • author-{nicename}.php
  • author-{id}.php
  • author.php
  • archive.php
  • index.php

date.php

When posts are queried by date then they will be displayed by using the date.php file. If this file doesn't exist then WordPress will use the archive.php file to display the list of posts. If this file isn't found WordPress will then use the index.php file.

  • date.php
  • archive.php
  • index.php

archive.php

The archive template can be used to display a list of posts if the category, author or date files don't exist.

  • archive.php
  • index.php

search.php

WordPress comes with inbuilt functionality to search for list of posts, when the results of the search are displayed the search.php file are displayed.

If there is no search.php file then WordPress will use the index.php file.

  • search.php
  • index.php

attachment.php

You can use the attachment.php file to display a page with a single media attachment.

If you don't have an attachment.php file then WordPress will use the single.php file to display the media file.

  • MIME_type.php
  • attachment.php
  • single-attachment.php
  • single.php
  • index.php

image.php

If you are viewing a single image attachment you can use the image.php file to display the image, if this file doesn't exist then it will use the attachment.php file.

404.php

When a page is not found in WordPress it will call a 404 error and use the 404.php file to display a message to the user.

The 404 Not Found template. Used when WordPress cannot find a post or page that matches the query.

  • 404.php
  • index.php
Back to top

Fastest WordPress Hosting With WPEngine

Stunning speed, powerful security, and best-in-class customer service. At WP Engine.

Risk free for 60 days