Dissecting WordPress Themes Part 1: Creating a Theme

Themes are sometimes referred to as the “skin” of a WordPress site because it is the theme that determines the appearance of the site’s pages in a web browser. I prefer to think of the theme as both the skeleton and skin: the skeleton being the theme’s template files and the skin its style sheet. Like a skeleton, a theme’s template files determine the structure of a site’s pages. And like skin wrapped around the skeleton, a theme’s style sheet determines its aesthetics. The theme, then, is responsible for organizing the raw content (posts, pages, images, and so forth) and presenting it to the world. Perhaps that means the posts are muscles and the pages are organs; or is that taking the analogy too far?

As every WordPress user knows, you can select from many hundreds of different themes that have been designed, engineered, and contributed to the WordPress community by web designers and software developers. You can use these themes “as is” or modify them to meet your needs. Indeed, if you know some HTML, CSS, and PHP you can also develop your own themes from scratch.

In this multi-part series of articles, I’ll walk you through the creation of a theme step-by-step. The theme we’ll develop is perhaps the simplest (and ugliest) theme you’re ever likely to run across. In fact, it will contain only very simple markup and almost no styling at all. The purpose of this “Trace” theme is merely to demonstrate the workings of the WordPress theme machinery and to get you started on the path to developing your own themes.

Setting Up Your Development Environment

If you want to follow along with this step-by-step tutorial, it will be helpful to have a local WordPress development environment available on your computer. This environment will provide you with easy access to all of the theme’s files and allow you to follow along as WordPress objects like posts, pages, comments, categories, and tags are staged for illustration. In order to create such a development environment, you can follow the instructions in the following articles:

Additionally, you will need to create folders and files as you implement the Trace theme. To perform these activities I’ll be using my favorite IDE, NetBeans. If you would like to follow along, I’ve provided instructions for installing NetBeans in the article Installing NetBeans IDE on Windows. If you would rather use a different IDE (or just a text editor), skip the rest of this section and continue with Creating the Theme.

Begin by launching NetBeans IDE. The IDE’s application window will appear. Select File→New Project from the menu to bring up the New Project dialog. In the Choose Project step, select PHP from the Categories list and PHP Application from the Projects list. Click Next.

New Project Dialog

The New Project dialog allows you to create NetBeans project files of various types. Here, we choose to create a PHP application.

You now see the Name and Location step. Enter TraceTheme in the Project Name field. In the Sources Folder, enter the location of your WordPress installation. In my case, this is g:\xampp\htdocs\lab1. Click Next.

Name and Location Dialog

The Name and Location step allows us to set the project name and a folder to hold the source files. Creating the project file in the WordPress installation directory allows us to access all WordPress files including core, theme, and plugin files.

In the Run Configuration step, leave the default values as shown and click Next.

Run Configuration Dialog

The Run Configuration step allows you to specify how source files will be deployed. In this case, we’ll be creating files directly in the wp-content\themes folder so no deployment is needed.

We won’t be using any frameworks in this tutorial, so leave all of the boxes unchecked in the PHP Frameworks step and click Finish.

PHP Frameworks Dialog

The PHP Frameworks step allows you to include various PHP frameworks in your project. For this tutorial, no frameworks are needed.

The Projects tab in the Navigator should now be open to the WordPress installation directory as shown below. Creating the project in the WordPress installation directory allows easy access to all of the WordPress distribution files including the core files, themes, and plugins. The IDE opens WordPress’s index.php file automatically. We won’t be touching this file, so close it by clicking the small x in the editor tab.

NetBeans IDE

The NetBeans IDE offers many tools and excellent editors. The circled area shows files and folders in the Navigator. The project source tree begins in the WordPress installation directory where we created the project.

Creating the Theme

If you’ve used WordPress as an end-user, you already understand that you can use the Administration Screen’s Appearance→Themes page to browse, download, activate, configure, and delete themes. If you self-host your WordPress installation (as opposed to using WordPress.com), you can also modify installed themes and create your own.

So what, exactly, is a WordPress theme? Well, a theme (minimally) consists of three items:

  1. A folder (subdirectory) in the filesystem that stores all of a theme’s files
  2. A CSS style sheet called style.css, in the theme’s folder
  3. A PHP file called index.php, also in the theme’s folder

Let’s begin our investigation of the WordPress theme architecture by creating these three components.

Creating the Theme Folder

The first step to creating a new theme is to create a directory for it. WordPress stores all of its themes, whether activated or not, in a directory called wp-content\themes within the WordPress installation directory. Within the themes directory is a separate subdirectory for each installed theme. The name of each theme’s subdirectory corresponds with the theme’s name. For example, the two themes installed along with WordPress 3.5.1 are stored in subdirectories called twentyeleven and twentytwelve. When you install a new theme using the Appearance→Themes page, it lands in a new subdirectory within the themes parent directory. In order for WordPress to find our new theme, we’ll create a directory called trace corresponding to our Trace theme.

Note: In Windows you can use Windows Explorer to create a new directory. On Mac OS, you can use Finder. On Linux, the tool will depend on the graphical shell you’re using, or, in a command-line environment, you can use the mkdir command. This tutorial will assume that you’re following along with a local WordPress installation on Windows and using the NetBeans IDE, but other platforms will be similar.

In NetBeans IDE, click on the wp-content folder in Projects tab of the Navigator to open the folder. Click on the themes folder to open it as well. Right-click on the themes folder, and select New→Other from the menu. In the Choose File Type step, select Other from Categories and then Folder from File Types. Click Next.

Create Folder

You can create a folder for our Trace Theme from within NetBeans.

In the Name and Location step enter trace in the Folder Name field and click Finish as shown below.

Create Folder Name

Supplying the folder name and location as shown will create a new trace folder under the themes directory to hold our theme’s style sheet and template files.

Now, for illustration, log in to the WordPress Administration Screen as an administrator and navigate to the Appearance→Themes page. Notice in the screenshot below that the Current Theme is Twenty Twelve and the only Available Theme is Twenty Eleven. Our Trace theme does not yet appear on the page.

Manage Themes

The Manage Themes page does not yet recognize our new theme because it doesn’t contain the required components.

Creating the Style Sheet

Now, we’ll create the second required theme component, a CSS style sheet called style.css. In the IDE, right-click on the trace folder and select New→Cascading Style Sheet from the pop-up menu. Enter style in the File Name field and click Finish.

Create Stylesheet

The New Cascading Style Sheet dialog allows us to create a style sheet for our theme. Here, we create the style.css file in the trace directory.

The style.css file for a WordPress theme doubles as both a CSS style sheet and a description of the theme with which it is associated. The “theme description” role requires a comment block at the top with a particular format. In the IDE editor, delete the contents of the generated stylesheet and enter the code below.

/*
Theme Name: Trace
Theme URI: http://webterranean.net/
Description: A theme to trace WordPress Themes.
Author: Charlie Butler
Author URI: http://webterranean.net/
Version: 1.0
Tags: white, one-column, fixed-width
License: GNU General Public License
License URI: license.txt
General Comments (optional).
*/

Create the style.css file with the information above (supply your own Author and Author URI if you like). Save the file by selecting File→Save from menu bar or by clicking the disk icon in the toolbar. Refresh the Appearance→Themes page of the Administration Screen. Now notice that an entry for our Trace theme appears in the Broken Themes area. WordPress recognizes our theme directory but is not yet willing to accept it into the theme family.

Broken Theme

WordPress recognizes that our theme is present, but considers it a “broken” theme because it does not yet have an index.php template file.

Creating index.php

To fix that problem we’ll need to create the third required theme component, index.php. Back in the IDE, right-click the trace folder in the Navigator and select New→PHP File from the pop-up menu. Enter index in the File Name field and click Finish.

New PHP File

We’ll create a new PHP file called index.php in the trace directory.

This file will normally contain a blend of HTML and PHP, but for now, just create a trivial version with the following lines. This code simply outputs a trace message to the browser, letting us know that the index.php file is running.

<?php
  echo "<p>In index.php</p>\n";
?>

Save the index.php file and once again refresh the Appearance→Themes page. Notice that since our Trace theme meets the minimum requirements for a WordPress theme, it is now available to be activated.

Trace Theme Available

WordPress now considers our Trace theme worthy and promotes it to the Available Themes list. We won’t bother with a preview picture right now.

Go ahead and click the Activate link that corresponds to the Trace theme. You should see the message New theme activated with a link inviting you to visit the site. Click the Visit Site link.

Trace Theme Activated

The Trace theme is activated and we can take a look at the site (such as it is).

You should now see the In index.php message in the browser.

Creating Template Files

The index.php file is called a “template file” in WordPress parlance. A typical theme will include many template files used in different situations, such as generating headers, footers, sidebars, archive lists, pages, etc. As we proceed through this tutorial, we’ll examine all of these variations of template files. For now, let’s add a couple others that are typically used along with index.php to generate a valid HTML page.

While it’s possible to include all of a site’s markup directly in index.php, most themes delegate header components to a template file called header.php and footer components to footer.php. A common configuration is to include those files from index.php as follows:

<?php
  get_header();
  echo "<p>In index.php</p>\n";
  get_footer();
?>

The call to get_header() in index.php causes the header.php file contents to be included in the output at the point it is called. Similarly, the call to get_footer() includes the footer.php file.

While you’re in the editor, right-click on the get_header() function call and select Navigate→Go to Declaration from the pop-up menu. This will open the general-template.php core file where the get_header() function is declared and highlight the function within the file. This is a very useful feature to view usage comments, parameters, return values, etc. while you’re coding.

Go to Declaration

To get more information about any WordPress template tag, right-click on it to bring up the context menu and select Navigate > Go to Declaration. This will open a new editor tab with the cursor positioned on the declaration for the selected call.

Now, let’s create the header.php file in the theme’s directory. In the IDE Navigator right-click on the trace directory and select New→PHP File from the pop-up menu. Enter header as the File Name and click Finish. In the editor, delete the generated code and replace it with the code below. This code just echos the <!DOCTYPE>, <html>, and <body> tags, along with a message indicating that we’re executing the header.php file.

<?php
  echo "<!DOCTYPE html>\n";
  echo "<html>\n";
  echo "<body>\n";
  echo "<p>In header.php</p>\n";
?>
Note: Many developers will intermix HTML and PHP code rather than echoing the HTML as I do in this article. In some cases, this results in a cleaner look in the source files. However, once the template file becomes more complex, I find it harder to read when there are many <?php … ?> tags jumping in and out of “PHP mode.” So my preference is to code everything in PHP. This is just a personal preference–it works fine either way.

We’ll continue by creating footer.php in the theme’s directory. Again, right-click on the trace directory in the Navigator, select New→PHP File, enter footer as the File Name, and click Finish. Replace the generated code with the following code. This code finishes up the page by outputting a trace message, followed by the closing </body> and </html> tags.

<?php
  echo "<p>In footer.php</p>\n";
  echo "</body>\n";
  echo "</html>\n";
?>

We now have the components necessary to create a valid HTML page. Refresh the browser window and let’s take a look at the source for the displayed web page.

Note: The method for viewing a page’s source depends on the browser. For Internet Explorer, right-click on the page and select View Source. For Firefox and Chrome, right-click on the page and select View Page Source. For Safari, enable the Develop menu from Safari Preferences→Advanced (if necessary); then select Develop→Show Page Source.

As you can see from the page source below, the page contains output generated from each of our template files.

<!DOCTYPE html>
<html>
<body>
<p>In header.php</p>
<p>In index.php</p>
<p>In footer.php</p>
</body>
</html>

While we’re at it, let’s go ahead and add one more common template file, sidebar.php. Create the file using the same method as you did for the other files. Replace the generated code with the following code that just echos another trace message.

<?php
  echo "<p>In sidebar.php</p>\n"
?>

Edit the index.php file to add the call to get_sidebar() before the call to get_footer() as shown below.

<?php
  get_header();
  echo "<p>In index.php</p>\n";
  get_sidebar();
  get_footer();
?>

Of course, in a real template the page’s sidebar would be displayed, well, on the side. However, based on the dictates of the theme (and sometimes on the device being used to view the page), the sidebar could be displayed in other locations. In any case, it’s usually the style sheet that’s responsible for positioning the page’s components.

Once again, refresh the browser and view the page source. You should now see all four trace messages as shown below.

<!DOCTYPE html>
<html>
<body>
<p>In header.php</p>
<p>In index.php</p>
<p>In sidebar.php</p>
<p>In footer.php</p>
</body>
</html>

The diagram below depicts the dynamic assembly of our web page using the four template files we’ve created so far.

Dynamic includes using template tags

Using WordPress template tags, index.php dynamically includes header.php, sidebar.php, and footer.php in the construction of the final page.

In this first part of our exploration of WordPress themes, we discussed the three components required of every theme: a directory to hold the theme’s files, a style sheet called style.css with required information in its comment block, and an index.php file to display the site’s “home page.” We also included a couple of other common template files: header.php, footer.php, and sidebar.php. Our theme doesn’t yet display any posts, but we’ll take care of that in the next part when we look at “The Loop.”

References

  • codex.wordpress.org. The WordPress “codex” lives at this site which contains everything you ever wanted to know about WordPress but were afraid to ask.
  • netbeans.org. The project site for NetBeans IDE has an excellent collection of tutorials, videos, and how-to’s for NetBeans and related technologies.

Speak Your Mind

*