WordPress Theme Building Course!

This article is part of the How to Build a WordPress Theme course. If you’re new to WordPress theme building, be sure to start from the beginning of the course to get a complete picture.
FULL COURSE 
Building a WordPress theme can be an intimidating process for beginners. There are files to deal with and things to consider that probably meant nothing before.

That’s okay, though. The majority of those files can be grouped together as concepts and those concepts come together to form a simple, functional WordPress theme.

underscoresIn this course, I’m going to teach you how to build a WordPress theme yourself using the Underscores (_s) Starter Theme by Automattic as an example.

Instead of building everything from scratch, I’m going to introduce you to the simple elements of a basic theme piece by piece. This makes things easier to understand because you can see the big picture as you learn.

Here are the two versions of the theme we are going to use as an example.

I will be using today’s version of Underscores. While there’s a chance your version of the theme will include minor changes from the one I use in my code examples, you should still have no issues following along.

Github Version – Customizable Version

The Github version of this starter theme is ready for use immediately. The theme is already named and all function names used in the theme have a set prefix.

The customizable version allows you to set the theme name, slug (folder name, function name prefix, etc.), author information, and theme description before downloading the same exact version (without said changes) found on Github.

In other words, both sources will provide you with a working starter theme. The customizable version will allow you to brand certain elements of your theme in an automated fashion, saving you plenty of time.

Choose a version to download and let’s go over the theme files.

Underscores Starter Theme File Structure

underscores-files-rootHow you organize your theme files is something you will work on over time. With the exception of a file or two, your file configuration possibilities are limitless if you know a little PHP.

You’ll have to find a balance between your own organization methods, ease of use for your users (because they create child themes), and simple common sense.

For now, we’ll observe Underscores’ file structure and use it as a starting point, including its extra but unnecessary files.

Root Files

As you read through the article, open the files when we cover them. Look through the code.

Do not be intimidated by the number of files in the theme root. Many of them are self-explanatory based on the file names. Others can be grouped together because they behave similarly. Let’s observe those groupings.

The main HTML structure files handle the site header, footer, content column, and sidebar column.

The names given to these files are more about semantics than positioning. While the header is usually at the top of a website, the footer on the bottom, and the content and sidebar columns configured side-by-side, that is not a must. The natural HTML flow of these elements are stacked one on top of the other.

You’ll find this structural HTML in a series of files. The header.php, footer.php, and sidebar.php are exactly what you expect them to be. They build the site header, footer, and secondary container referred to as the sidebar.


layoutThe content container is where things get tricky. The WordPress Template Hierarchy takes over and the “content” portion of the HTML structure uses specific files based on what kind of WordPress page is being loaded.

The default file to fill this position is the index.php file. It includes the container that typically sits beside the sidebar and displays the page’s main content.

However, WordPress knows to use this file as a last resort. Instead, it looks for other files in your theme root by name and uses them if they have a specific purpose.

WordPress Posts

When a single WordPress Post is loaded, WordPress will look for the single.php file to serve as the content column. Because it exists, it will be used. Plain and simple.

However, this file only codes the content container shell. Nested within it is the WordPress loop. It’s inside of the loop that the actual HTML elements responsible for displaying the single post content is called, and that HTML is found in the content-single.php file.

Don’t let that setup confuse you. single.php and content-single.php basically behave as one file. You’ll learn how later in this course.

WordPress Pages

Moving on, when a WordPress Page is loaded, WordPress will look for the page.php file to serves as the content column. Because it exists in our theme, it will be used in the same fashion as above. Within that file’s loop, the content-page.php file is called to display the WordPress page content.

Archives, Search Results, and Error Pages

The same functionality applies to many other WordPress template files based on the template hierarchy. The main three files outside of your posts and pages will be archive.php, search.php, and 404.php.

Those files handle all archives pages (taxonomies [categories and tags], date archives, and author archives), search results, and error pages, respectively.

Default Template File

If none of the above files existed in your WordPress theme root or the page being loaded was not specific to any WordPress template, WordPress knows to look for the aforementioned index.php. It is your generic, fallback template.

Again, you’ll want to take a good look at the WordPress Template Hierarchy for a deeper understanding of the order of operations for these files. WordPress knows exactly what to look for based solely on file names.

While there are many instances where other files will still be served before the index file, for the sake of simplicity in our theme, it’s index’s time to shine.

Within the index.php there’s a loop just like the other template files. However, this loop goes on to call the content.php which serves as the generic content file. It’s very similar to the content files called by your single and page templates. However, it is designed to cover all bases no matter the type of page being loaded.

For most themes, the blog home (where the feed is displayed) depends on the index file. That’s the case with Underscores.

layout-pagesSo what happens if the blog has no published posts yet? Instead of the index file calling the content file, it will call the content-none.php file instead.


It’s very simple logic. All of the files mentioned above create the main site structure in WordPress.

The header, footer, and sidebar are considered to be static. The content changes based on the type of page being loaded. Simple stuff.

With the entire HTML structure of your theme in place, there are a few other files that either your template files or WordPress will call on. Let’s discuss those.

Comments Template Function

The comments.php is responsible for the display of your comments, pings, and comment form. Though you typically only see comments on WordPress posts, they are prepared to display on WordPress pages as well.

In both your single.php and page.php files, the comments_template() function is used to enable comment functionality. That WordPress function knows to search the theme root for your comments.php file. Again, simple stuff.

comments

Functions File

Of course, WordPress wouldn’t be what it is without the awesome functionality that extends the software in whatever direction you desire. That’s where the functions.php file comes in.

WordPress knows to look for this file in the theme root. It is used primarily to set up theme functionality. While basic PHP can be used to extend this file’s reach to other PHP files, it is perfectly normal to build your theme details right here.

Things like registering widgetized areas, setting thumbnail sizes, and loading theme resources such as javascript files can all be done from this file. WordPress will automatically look for it so whatever you put in it will considered important.

Theme Stylesheet


style-css-comment-blockThe last (but not least) of the important files would be your stylesheet. The style.css is a WordPress theme’s main stylesheet. It must be included in a theme and it must be in the theme root. There are no exceptions.

Reason being, the very first thing that must be in this file is a comment block with important information about your theme. WordPress will look for this information and use it to output information about your theme in various places.

When you are in your WordPress dashboard and you navigate to the Themes page to see your installed themes, all information you see comes from that top comment block.

Another reason why this file is important is because your theme is nothing (to the average user) without CSS styles. This is where those style rules belong.

Another stylesheet included in Underscores that’s often overlooked is the rtl.css file. RTL means “right to left.” This file is used to adjust your theme styles for languages that read right to left. Usually, it doesn’t take much CSS to make this adjustment.

When you’re building your theme and testing it with the resources outline on the Tools page, you’ll get the opportunity to test your theme in right to left fashion. You’ll use this stylesheet to handle any necessary adjustments.

Screenshot

On the WordPress dashboard Themes page (and a few other random spots), you will also notice a screenshot image file.

Screen Shot 2014-01-22 at 5.13.37 PM

It can be branded for your theme or company. It can also be a simple screenshot of your theme. WordPress will look for a screenshot.png file. Be creative.

Root Directories

First of all, understand that WordPress does not require any directories in your WordPress theme. They are simply used for file organization and their names are 100% up to you.

That said, at the time of writing this article, Underscores comes with inc, js, languages, and layouts.

“inc” directory
This directory, short for “includes,” contains PHP files that are an extension of the functions file. As stated earlier, the functions.php file will be ran by WordPress no matter what. So “including” or “requiring” other files from the functions file will ensure their use as well. The Underscores functions file calls the files in this directory – /inc/custom-header.php, /inc/template-tags.php, /inc/extras.php, /inc/customizer.php, and /inc/jetpack.php.
Because these files are not required by WordPress nor are they part of the WordPress Template Hierarchy, we will not discuss them in detail. However, a description of each file’s purpose can be found in the top comment block of the files themselves.

“js” directory
This directory contains the theme’s custom javascript files. It includes the /js/customizer.js, /js/navigation.js, and /js/skip-link-focus-fix.js files. All Underscores code that requires a javascript file to be loaded (one that is not already included in WordPress) calls to the appropriate file in this directory.
“languages” directory
Depending on whether or not you are releasing your theme for distribution, you may need to prepare it for use in other languages besides English.The languages directory is a place to provide instructions and necessary files for translation. Again, this directory can be placed anywhere as long as the PHP looking for it knows where to find it.
“layouts” directory
This directory contains two simple stylesheets for the configuration of the aforementioned content and sidebar columns. Underscores knows that most blogs either have a content/sidebar configuration or sidebar/content. So these two files provide sample CSS to use in order to easily configure those columns. Personally, I like to delete this directory immediately as well as the /layouts/content-sidebar.css and /layouts/sidebar-content.css files in it. I’ll either write my own layout CSS or I’ll copy the CSS from these files and put it in my style.css file in the root.
Seeing the Big Picture

That’s a ton of information, right? Eh… not as much as it seems. The way it all comes together is fairly simple and once you understand how WordPress treats theme files, it becomes incredibly easy to understand any theme’s file setup.

If necessary, go back through this article one more time and make sure you’re opening files and skimming through them as I point them out. You will notice many similarities between multiple files and recognize basic HTML structures.

If you haven’t already, install Underscores as-is on your development WordPress install so you can see that it is a fully functioning, style-less theme.

Once you understand everything in this article, it’s time to break things down… the good stuff. Let’s go.