Speckyboy Cyber Monday 2022

For the Novice Developer: The Anatomy of a WordPress Theme

on WordPress

The great thing about WordPress is that, due to its surging base of 60 million users, it’s one of the most widely-developed and themed content management systems in the world. This isn’t just due to the popularity of the software itself, however; WordPress is actually exceedingly easy to theme and extend in various ways based on a user’s experience and needs.

The theme structure that has been used with the software for the better part of the past decade has always been rooted in combining XHTML, CSS, and PHP, and doing so in pretty basic, easy-to-understand ways. The best way to begin learning about these three technologies and how to integrate them into a new theme is to learn about the actual anatomy of a WordPress theme itself.

From storage to variables, file structure to features, all WordPress themes can be broken down and explained using basic terminology and compartmentalization.

The Anatomy of a WordPress Theme

First Thing’s First: Where Themes are Stored Within a WordPress Installation

For those truly novice WordPress theme developers, it’s time to learn where the software actually keeps all of its theme files and folders. Every WordPress installation is bundled with a wp-content directory; this directory is generally used to contain everything a user might upload to the installation on their own, including plugins, image or other media uploads, and the WordPress theme files themselves.

WordPress themes are not contained in singular files, but are instead bundled together within a folder of their own. This folder is placed within the themes subdirectory located in the wp-content folder on the server. Within this directory are several PHP template files which control the look and feel of the site’s header, footer, and content areas independently. A stylesheet is included to give these pages a user-friendly design, and optional files can be included to extend a theme’s functions or add JavaScript scripts to a theme itself.

Themes themselves are located within the following directory on the server, which can be accessed and modified using a simple FTP client:


Of course, if a WordPress installation is in a subfolder within public_html this server path would differ slightly. It’s easy to understand, however, where and how to access a theme’s folder and associated template files.

Moving On: Learning About Theme Files and Typical File Structure within the Containing Folder

WordPress themes contain PHP template files, and those files must be named in a certain way in order for them to be seen and used by the software itself. While custom PHP template file can be created outside this mandatory file structure, it’s important to focus on creating these essential files first in order to ensure that every page within an installation can be properly displayed and used by the site’s readers.

Every theme must contain a style.css file; this file not only helps turn plain XHTML elements into vibrant containers for content, but also contains basic header information at the top of the file which identifies the theme’s name, author, version, homepage, and keywords. Without this file, and the header information it must include, the theme will not show up in the WordPress Dashboard and therefore will not be available for activation and use. For more information on what needs to be placed into this files, novice developers can visit the WordPress Codex for the series of lines and information they must customize to their theme.

The next files which should be created as part of the new theme should be the separate header and footer PHP template files. Almost every WordPress theme uses these files to split off the header and footer from the main content area, making it easy to alter those files and have the changes be reflected universally, rather than editing every content-containing file separately over a longer period of time. These files are pretty straightforward, but here’s a primer on each:

  • header.php should contain everything from the DOCTYPE tag to the end of the page’s navigation. This means that all <head> tag information, meta tags, <title> tag variables, and other information must be included in the site’s header. This template file also must contain the <?php wp_head(); ?> tag, which places valuable WordPress version-sharing information, and other website information, within the head of the document. It must be placed before the closing </head> tag.
  • footer.php begins when the page body closes, and includes any information that a user wishes to contain in the footer. This can be a content-rich footer, which is a currently-trendy way of closing the document, or simply a copyright statement and some valuable links to other resources. It must close the <body> tag as well as the HTML document itself, using the </html> tag before the end of the file.

Once these two files are created, they can be simply included into all of the other theme’s content-area PHP template files using WordPress PHP variables. It’s an exceedingly easy way to create a dynamic template, and users will be pleased with not having to learn extensive PHP inclusion coding in order to make the header and footer appear automatically on every page. With the header and footer complete, a new list of files must be created to display WordPress category, page, and post content to site readers. Those files include:

  • archive.php
  • category.php
  • index.php
  • page.php
  • search.php
  • single.php

With the theme’s content files created, there is one last required theme file and one more optional one which can be added to the containing folder. The required file (for the vast majority of WordPress installations) is the sidebar.php template. This file is pretty self-explanatory, and it contains the entire theme’s sidebar information. It can be included into all of the other content-specific template files by using a simple, WordPress-exclusive PHP variable. It simply gets placed within the sidebar <DIV> tag and that’s all there is to it.

With all of the actual content display template files created, there is one last thing which can be added to the theme’s containing folder. That is the functions.php file which serves not to display content, but rather to add functionality and alter how content is created, displayed, or interacted with. This file is sort of like a theme-specific listing of plugins; anything placed into functions.php will only modify the site’s operation while the relevant theme is selected. For most novice developers, this file is extraneous and will likely not need to be included with a theme. However, it’s a good idea to create a blank version of the file so that it can be easily added to at a later date, especially as theme development skills are joined by PHP coding skills which may prompt a user to add functions to the site.

Bringing Dynamic Content into the Fold with the WordPress Loop

Now that all of the standard template files have been created, and the header, footer, and sidebar can be dynamically included into any template file using standard WordPress PHP variables, it’s time to pull the actual WordPress content into the templates for display to the end user. This is done on almost every page by using a variation of the so-called “WordPress Loop.”

Without using database queries and advanced pieces of code, one WordPress Loop can be included per template file when displaying post content, the dynamic content assigned to pages from within the WordPress Dashboard, and creating single category, archive, and tag pages. The Loop is even used in the comment template to pull entries from the database, and a second “Comment Loop” is used to pull the associated interactions with that entry from a linked database table.

The WordPress Loop always starts with the code below, which simply checks the database to see if there are any entries to display based on the template hierarchy currently in action. That means the Loop will automatically look for certain categories, date ranges, or tags, based on the permalink a user has clicked. Here’s how that conditional looks:

<?php if (have_posts()) : while (have_posts()) : the_post(); ?>

Next, template developers can begin calling information from the database and printing it on the page by using standard WordPress PHP variables. These can be used to display things like the entry title, the full content or an excerpt of the content, tags, categories, the date, the author’s name, and permalink information for inclusion in an <a> tag. Here’s a very basic example of a WordPress Loop pulling entry information using these variables:

<a href="<?php the_permalink() ?>"><?php the_title(); ?></a><br/>
Posted on <?php the_time('F D y') ?>

<p><?php the_content(); ?></p>

Now that the appropriate information has been pulled out of the database using these simple WordPress PHP variables, the WordPress Loop must be closed. This process involves not only bringing an end to the built-in database queries, but also using another conditional statement to print a brief error message to readers if no content is found for display within the Loop. This will happen if a user visits a category page for which no entries have been assigned, or if they navigate to an archive month during which no entries were posted. Here’s how the end of the Loop looks in most standard WordPress templates:

<?php endwhile; ?>
<?php else : ?>
<?php _e("Unfortunately, there are no entries to be displayed here. Please try a different link."); ?>

The php_e variable above is simply an instruction that an error message should be displayed to users who find an empty Loop on any of the site’s dynamic template pages. The text within the parentheses can be customized to a template developer’s liking, and the tag can be surrounded by standard XHTML elements in order to customize its display via CSS code in the style.css file which was created and discussed earlier in this primer on theme anatomy.

Remember to Always Debug and Validate After Composing a Theme

The final piece of the WordPress theme development puzzle comes in the form of debugging and validation. These two elements go hand in hand, as many themes will develop bugs because of coding errors, and those coding errors will cause online validators to simply display error messages; the W3C calls such themes “invalid” and urges all web designers to correct any errors to ensure the smooth operation of their theme in multiple browsers across all computing platforms.

The most important thing to test after a theme has been developed is whether or not the content is being pulled properly from the database, and whether it’s displaying properly on the page. If the content simply isn’t being pulled out of the database, it’s likely that either the opening WordPress Loop syntax was botched during the design process, or one or more of the WordPress PHP variables used for displaying content has been placed incorrectly into the file. Check for typos, spaces or errant punctuation in the PHP code, and other small mistakes which might affect the display of entries and page content.

When all of the appropriate testing has been completed, and when the theme is perfect in both content and appearance, developers can either keep their theme to themselves or upload the work to the WordPress Extend theme gallery for others to download and enjoy.