Understanding the WordPress Theme Structure - WordPress Responsive Theme Design (2015)

WordPress Responsive Theme Design (2015)

Chapter 2. Understanding the WordPress Theme Structure

As we have already installed and set up WordPress and our starter underscores theme, we are now continuing our journey and, in this chapter, we will learn about the WordPress theme architecture and the purpose of the most important template files.

Without further ado, in this chapter we will cover:

· The WordPress permalinks functionality

· WordPress theme structure

· WordPress template files

Setting WordPress permalinks

When users come to our page, for example, http://localhost/topcat/about, they usually see the permalink that is set as a post name, or they just see the post ID. It all depends on the current settings in wp-admin. The permalinks section can be reached by going to Settings | Permalinks. Default settings are always set on a post ID, but recommended settings should be set to the post name because of Search Engine Optimization (SEO) purposes. The aboutpost name makes more sense than p=123 in http://localhost/topcat/p=123.


With SEO, we are optimizing the website properties in order to make our website more appealing to search engines. With permalinks, we are making our URL readable and searchable by humans. It is easier to find the term dejan markovic wordpress if we have a page for it, as in the dejanmarkovic.com/wordpress example, rather than dejanmarkovic.com/page=?123.

Here is an example of the permalinks settings in wp-admin:

Setting WordPress permalinks


Please note that permalinks in the preceding screenshot are set to Post name.

Then again, when the user comes to our page, http://localhost/topcat/about, and the about permalink is recognized in the backend as the post ID (as that's how the posts are stored in the database), the database will figure out whether the page is of the post type, page, or something else.

Refer to the following figure for an explanation of the steps numbered from top to bottom:

Setting WordPress permalinks

In this case, because the about page is of the page type, page.php is loaded.


Note that WordPress saves posts, pages, categories, and menu items with their custom IDs in the database system, so the database can check the type of the item by ID.

What is a WordPress theme?

WordPress theme is a group of files (template files) that are working together to display the content to end users. Themes are extensions, like plugins, to the WordPress core file and their purpose is to customize the front-end of the website. They also allow users who have access to the dashboard (usually admins) to customize the look of the website.


Note that WordPress admin themes have been gaining popularity in 2015 and these themes are used to change the look of the WordPress dashboard (admin).

Template files

The style.css file is a CSS file where theme information is stored. There are a number of variables in this file, as we can see in the following screenshot:

Template files

Let's examine each of these variables. They are as follows:

· Theme Name: This is the name of the theme.

· Theme URI: This is the location of the theme. I am using the location on my http://dejanmarkovic.com/ website until my theme gets approved by the theme team at WordPress.org. Then I will move the theme to a location on the WordPress.org website.

· Author: This is the name of the author of the theme (in this case, yours truly).

· Author URI: This is the author's website URL.

· Description: This is the place where we should describe the theme with as many details as we can, because this value will attract our users/customers. As we have just started, I have provided only the basics. I highly recommend that you update this value when you complete your journey in order to make your theme more interesting and unique.

· Version: This is our current version of this theme. When our theme gets published, we should change the version number each time we make a substantial change.


Note that we should not change the version number for every simple change but for each commit.

For example, if we fix the bug, that fix will contain multiple changes, but we will commit the code to WordPress.org only once. Just before committing the code to WordPress.org, we should change the version value.

· License: We should state the license we are using for this theme. As we are going to submit our theme to WordPress.org, it should have the same license as WordPress: GNU General Public License v2.

· License URI: This is the location of the LICENSE file.

· Text Domain: This is used for localization (making your theme translation ready). We will make our theme translation-ready, and we will cover that in more detail later in this book.

· Tags: This variable is where you can choose the tags that describe your theme features/options. For this option, we should only use the tags that are allowed on WordPress.org. Please use the https://wordpress.org/themes/tag-filter page as a reference and click on the Feature Filter option in order to see the tags. If your theme has the same features as mine, please feel free to use the tags that I've used.

When we complete the settings of our variables, we can see the results by going to Appearance | Themes and then clicking on the Active: TopCat option on TopCat's area in wp-admin, as you can see in the following screenshot:

Template files

A software license is a legal instrument (usually by way of contract law, with or without printed material) governing the use or redistribution of software. Under the United States copyright law, all software is copyright protected, except material in the public domain. A typical software license grants an end user permission to use one or more copies of software in ways where such a use would otherwise potentially constitute copyright infringement of the software owner's exclusive rights under copyright law.

- http://en.wikipedia.org/wiki/Software_license

Then, we can click on the Customize button in order to be forwarded to the theme details page, as shown in the following screenshot:

Template files

As we can see in the preceding screenshot, the name, author, description, and tags are displayed.


Please note that we have an image on the left-hand side that looks like the chessboard. This is actually the default image's screenshot.png file provided with the theme. We will change this image later on to display our theme layout.

The page structure of template files

Here is a screenshot showing the files in our template directory:

The page structure of template files

WordPress pages are made from the following sections, which are actually all separate files:

· header.php

· Content files such as index.php, page.php, single.php, and so on

· footer.php

· sidebar.php (optional)

The page structure of template files

The header.php page contains all the elements that are needed at the top of each HTML page, including doctype, opening HTML, meta, title tags, blog info, style sheets, and website navigation.

The content files are scaffolding files, which have a scaffolding code that calls the header, footer, and other files based on the content type.

The footer.php file contains the information that goes at the bottom of your page (closing tags and, in some cases, calls to footer sidebars/widgets).

The sidebar.php file is where sidebar information is found (this is an optional file, as some themes may not have sidebars).

The index.php file is one of the most important scaffolding template files. Its purpose is to show the blog's index page or any other index page. It is also used if the system can't locate the designated template page, such as page.phpand single.php, that we are going to cover further.

In cases where we have a blog, we just go to the root of the blog (the index page) and it will load content.php in the loop for each blog post, like the one shown in the following screenshot:

The page structure of template files

As you can see in the preceding screenshot, we have function calls to get_header(), get_footer(), and get_sidebar(). With these calls, we are calling the header.php, footer.php, and sidebar.php files. We can also check whether there are posts in the database with the if( have_posts() ) code. If there are posts, then it will call the content template, the content.php page, with the get_template_part( 'content', get_post_format() ); code. If there are no posts in the database, then it calls the content-none.php template.

There is another interesting call in our code and that is topcat_paging_nav(). This is the call for pagination. It has our theme name, topcat, in it. This prefix was added on the http://underscores.me/ page when I chose the theme name. The prefix (topcat) was added to all theme functions and it is supposed to make them unique and avoid causing conflicts. Here is an excerpt that explains this from the WordPress codex:

All the functions in your Plugin need to have unique names that are different from functions in the WordPress core, other Plugins, and themes. For that reason, it is a good idea to use a unique function name prefix on all of your Plugin's functions. A far superior possibility is to define your Plugin functions inside a class (which also needs to have a unique name).

- http://nacin.com/2010/05/11/in-wordpress-prefix-everything/


More information on this provided by Andrew Nacin, who is one of the lead developers for WordPress, is available at http://nacin.com/2010/05/11/in-wordpress-prefix-everything/.

If you want to publish your theme, then you should make sure to change the topcat prefix to something else that is unique.

The content files are described as follows:

· page.php: This is a scaffolding file for pages and it has similar code to index.php. It has the_content(); call that calls content-page.php.

· single.php: This is the scaffolding file that will be used if our about permalink (mentioned previously) links to a post instead of the page, and it will load the content from content-single.php.

· search.php: This is a scaffolding file where search results are shown.

· archive.php: This is a scaffolding file that displays archived pages.

· comments.php: This is a scaffolding file that displays comments.

· 404.php: This is a scaffolding template for 404 pages.

· rtl.css: In the root folder, we also have rtl.css, which is the CSS file for right-to-left languages (languages that are written from right to left).

· LICENSE: This file is obviously used for licensing purposes. As we are going to publish this theme on WordPress.org, the license should be GPLv2 (the same as the WordPress license).

· README.md: This file is used for project descriptions on GitHub.

· functions.php: This is a file where we are able to add our own functionality to a theme that is not a part of the WordPress core. In order to do this, we can also call the WordPress core functions.

As the file is too big for this book, I have extracted the code into small excerpts, which we will analyze together:

The page structure of template files

On line 11 of the preceding screenshot, we have a conditional statement that means: 'if the content width is not set, we are setting it to 640 px'. The code for this is as follows:

if ( ! isset( $content_width ) ) {

$content_width = 640; /* pixels */


We need to have the setup function for our theme and, on line 15 of the following screenshot, we check whether the topcat_setup function is already declared somewhere else:

The page structure of template files

On line 21 of the following screenshot, we are setting up the topcat_setup function, which sets the theme's defaults and adds support for some features that we will cover in detail later in this chapter.

The page structure of template files

On line 31 of the next screenshot, we are adding support for localization (support for our theme to be translated into other languages):

The page structure of template files

On line 34 of the following screenshot, we are adding links to RSS feeds from comments and posts to the header:

The page structure of template files

On line 45, we are registering our theme's primary menu, as shown in the following figure:

The page structure of template files


Note that adding links to RSS feeds from comments and posts to the header is good for SEO purposes as we should insert as much information as we can for search engines such as Google to pick that information. If more information is provided, our site will be easier to find.


Also note that WordPress themes can have multiple menus.

On line 45 of the following screenshot, we are adding HTML5 support for search forms, comments, and so on. This means that HTML5 tags will replace the old HTML tags for these elements.

The page structure of template files

In the following code screenshot, support for post formats such as video, image, and others is enabled:

The page structure of template files


A Post Format is a piece of meta information that can be used by a theme to customize its presentation of a post. The Post Formats feature provides a standardized list of formats that are available to all themes that support the feature.

- https://codex.wordpress.org/Post_Formats

On line 65, we are adding the support for the custom background in wp-admin. This option can be reached by going to Appearance | Background, as shown in the following screenshot:

The page structure of template files

On line 78 of the following screenshot, we are setting up our first sidebar:

The page structure of template files


Please note that WordPress themes can have multiple sidebars.

We will add more sidebars later in this book.

On line 94 of the following screenshot, we are adding the call for our default styles style.css and scripts such as navigation:

The page structure of template files

If we want to add some custom CSS and JavaScript, we should use the wp_enque_style() and wp_enque_script() functions, respectively, as shown next:

wp_enqueue_style( 'topcat-style', get_stylesheet_uri() );

wp_enqueue_script( 'topcat-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '20120206', true );

wp_enqueue_script( 'topcat-skip-link-focus-fix', get_template_directory_uri() . '/js/skip-link-focus-fix.js', array(), '20130115', true );

if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {

wp_enqueue_script( 'comment-reply' );


In the next section, we are performing the following steps:

1. Adding support to the custom header (this code is commented out as the functionality is optional).

2. Adding template tag functionality.

3. Adding the extras.php file for custom functions that are not associated with template files.

4. Making additions to the theme customizer.

5. Adding support for the Jetpack plugin.

These steps are shown in the following screenshot:

The page structure of template files

Theme subfolders

In this part, we will cover the subfolders of the _s theme. Let's go from the bottom to the top.

In the layouts folder, we have two CSS files, content-sidebar.css and sidebar-content.css, which are layout templates. In this book, we will use content-sidebar.css, as our sidebar will be on the right-hand side on some pages.

The languages folder is used for localization (language) files that have the .pot extension.

In the js folder, we should store any of our JavaScript files. We already have some files that are there by default:

· navigation.js: This file is used for navigation.

· customizer.js: This file is used for theme customizer functionality.


Since Version 3.4, WordPress has added support for the theme customizer. This option allows the user to change the theme's looks and settings by just going to the customize section of their theme by navigating to Appearance | Customize.

· skip-link-focus-fix.js: Users of Opera and WebKit browsers that use the keyboard instead of a mouse when click on a skiplink the browsers don't properly move the focus to its target. This file fixes the focus problem in the Opera and WebKit browsers when using skip links.

· skip links: This is a functionality that we implement on a page if the page has multiple sections. When the user clicks on that link, the page jumps to the designated section.

· inc folder: This is the place where we should put the files that extend the functionality of the theme. We already have some files there, as follows:

o custom-header.php: This is the file containing our custom header functionality (this file is optional)

o customizer.php: This contains extensions for the theme customizer mentioned previously

o extras.php: This contains custom functions not associated with template files

o jetpack.php: This is the file where support for the Jetpack plugin is added


What is Jetpack? Jetpack is a group of features and plugins that are used on WordPress.com and can be installed on self-hosted websites. The good thing about it is that all these features were tested on high-traffic websites such as WordPress.com and they are optimized for best performance. Because of all that, they are less buggy too. Usually, if someone has a problem/conflict with Jetpack on his/her website, it's because other custom plugins or a theme have conflicts with it and not because Jetpack itself is a problem. If we need a feature for our website that is covered with Jetpack, I would suggest that you use Jetpack rather than a custom plugin that has not been tested as Jetpack. On the other hand, I would strongly recommend that you use only features that you need rather than enabling all features, as that will really slow down your website.

Template tags, which are contained in the template-tags.php file, are actually WordPress functions that we can call in order to have some functionality. For example, topcat_posted_on() will display the time and author information for the post. The topcat_post_nav() function will display the previous/next functionality.


At the beginning of this chapter, we covered the permalinks functionality of WordPress. Then we covered template files and the page structure of those files. We also covered the functions.php file in detail. Finally, we analyzed the theme subfolders and files in it, including support for the Jetpack plugin and its functionality.

In the next chapter, we are going to start customizing our theme files, such as functions.php and style.css, and making our theme responsive.