Making a theme for WordPress | Tutorial Freak – Online Tutorials

Making a theme for WordPress


Making a theme for WordPress is easier than ever these days (in theory, an index.php file and a style.css file is all you need!). But if you plan to be the creator of a good theme, a perfect WordPress theme, you need to train hard.

What Makes a Theme Great?
Seriously, what makes a theme great?
Good design? Yes, but I’ve seen many WordPress themes that almost made me cry because of their beauty. But when I bought and downloaded it, I saw that it lacked even the basic coding standards and it immediately broke my WordPress installation.

So, is code structure important? Sure, but I’ve stumbled upon very sophisticated code in WordPress themes – the beauty of object-oriented PHP, readable CSS, brilliantly documented code blocks, and so on. But it broke the minute I installed it on WordPress 3.6 – it seemed that it only worked up to version 3.2.

What about maintenance? Of course, but this one time, I had to buy a theme for my client that utilized the latest WordPress features for that version. It was a good theme, but I just couldn’t move a block to another place – it didn’t even let me avoid using it! The website had to be the same as the demo website or it would fall apart.

So, flexibility? Yeah, but…

You get the idea – there’s not just one thing that makes a theme great.

Customer care, valid code, secure code, compatibility with major plugins, and it has to be distributed properly with respect to the licensed products it includes.
So Much to Learn…

Indeed, there’s so much to learn.

We need to go through some of the APIs offered by WordPress first – maybe not all of them, but a theme developer must learn about the Options API, the Settings API, the Theme Customization API and so on. Then, we’ll see the importance of localization, and have a look at licensing options for various marketplaces like ThemeForest, Creative Market, or your own website.

Next, we will learn to write better code. WordPress coding standards are important and the marketplaces are strict. Proper code commenting is also important for every bit of code we use. Validating the code is also crucial, as is its security.

After that, we’re going to have a look at bad practices – worst practices, really. From reinventing the wheel (by duplicating core features) to having the most bloated theme ever (with five thousand fonts and tons of shortcodes!), we will see what not to do and avoid these.

Finally, we’re going to grasp the importance of compatibility, maintenance and customer care. Supporting various plugins like bbPress or WooCommerce is a huge plus, but regularly updating your theme and providing excellent support are more than that. Way more.

Specifically, we’ll be covering some basic stuff like the APIs, localization, and licensing.
Learning the APIs by Heart

I think it’s safe to say that WordPress is the best platform because of the APIs: The APIs alone give WordPress its speciality of flexibility. Can you imagine an “inelastic” content management system?

I mean it: If WordPress is used by tens of millions of websites today, it’s because of its flexible nature all of which is due to its APIs.

Anyway, it’s important to know what WordPress APIs are and which ones you need to learn every bit of.

You can check all of the WordPress APIs here. While I suggest you learn and study every single API, I can’t say that you’ll need APIs like the HTTP API, the Filesystem API or the XML-RPC API regularly. Your themes should not contain hardcore functionality and invade the territory of WordPress plugins.

Here are the ones you’ll need the most:

Options API – It’s the standardized way of storing and retrieving your theme’s options. While you don’t see too much of it, it works together with the Settings API, so it’s important that you learn it well.
Settings API – This API is the backbone of your “Theme Options” panel. You can choose to write your own panel or search for options panel frameworks, but you will definitely need to study how the API works. If you don’t, you might wonder why there are some weird curly braces inside the option you retrieved, or do it all wrong and save every theme option in another database table row. Learn it! Learn it from a series called “The Complete Guide to the WordPress Settings API” or a Tuts+ Premium course called “Using the WordPress Settings API“, both created by Tom McFarlin. If you’re interested in the theme options frameworks, you might want check out Kyla Glover’s review on WPExplorer about five free options frameworks.

Theme Customization API – If you want to give your users the liberty of previewing the theme customizations, this is the API for you. It allows the users to change the look and feel of your theme and see the changes in real-time (or sometimes, with a Preview button).

There’s an excellent series you can check out: “A Guide to the WordPress Theme Customizer“. Written by Tom McFarlin, this series will teach you everything about the Theme Customization API.
Shortcode API – This is a very helpful API and by far my favorite one! It allows you to create snippets with square brackets that do stuff, basically. You can check out Rohan Mehta’s article, “Getting Started With WordPress Shortcodes“.

Quicktags API – This relatively simple API allows you to introduce new buttons for the WordPress editor (Text mode) on the writing screen. You can use this to let your users include your theme’s shortcodes, for example. Doesn’t hurt to learn it, right?
Widgets API – This might be one of the most important APIs of WordPress for you, if you plan to enrich your theme with neat widgets in the sidebars (or footers). It’s not actually hard to implement if you have a basic understanding of Object-Oriented Programming (OOP) with PHP, but I can personally recommend the “WordPress Widgets: Front to Back” Tuts+ course created by Tom McFarlin.

The Importance of Localization

WordPress is huge. You know why it’s huge? Because it’s not only in English, it comes with Macedonian, Turkish, Slovenian, Chinese and Persian, too (to name just a few). Looking at the list of translations for WordPress 3.6 at, we see that there are over 80 translations that are finished or more than halfway through.

I don’t know if you realized this already, but there’s an enormous WordPress market in countries that don’t speak English natively. There’s no national marketplace for digital products, and ThemeForest is generally our first choice to find premium WordPress themes.

I’m pretty sure this is the case for most countries and that’s why you must think about making your theme translatable, at the very least. To take it one step further, you can make deals with people to prepare translation files in their languages. You could pay them or let them use your themes freely, it’s up to you and the deal you make.

Trust me, if a French web design agency sees a phrase like “Already translated into French!”, they will definitely move your theme to the top of their “themes to buy” list.
Licensing Options and Using Licensed Products Inside Your Theme

I can’t stress this enough, so here comes a solid warning: If you don’t know what licenses are and how they work, your themes will not be accepted in any marketplace.

Luckily, there’s a website called TL;DR Legal which helps us understand the legalese language by simply summarizing license types like “If you use this license type, you grant people permission to use your stuff in commercial projects” or “If you’re going to use a product licensed with this one, you must give credit to the original author of the work”. You can even filter features to find out which license type is the best for you, or list licenses that have the features you seek.

For example; if you’re going to use a free slider in your premium theme (meaning that you intend to make money from your theme), you must look for sliders with licenses that allow “commercial use”.

If you’re going to sell your themes on ThemeForest, you’ll need to learn about Envato’s licensing options, too. Like TL;DR Legal, Envato’s license types for ThemeForest are really easy to understand. The “SimpleLicense” for Creative Market is also very simple to learn.

We’re going to focus on code: We’ll see how to code with WordPress coding standards, how to properly comment our code and how to validate and test the theme.

WordPress Coding Standards

Yes, I know, you have your own preferred style of coding: you like to compress a big function with a single line of code, you don’t like whitespace that much – Ah, I was once just like that.

But if you’re going to develop for other people and literally sell your code, you have to make your code understandable. And while you may think that your code is “clear enough”, there are universal standards for coding to help everyone code with the same style, and all serious theme marketplaces and download centers (from to ThemeForest) require you to code with standards.

There are four main programming and markup languages needed to develop WordPress themes: HTML, CSS, JavaScript and of course, PHP. Let’s have a look at each:

HTML Standards

There are relatively simple rules for writing standards-compliant HTML code:

Validate your code with W3C. Always. We’ll come to that later.
Be careful with self-closing elements: You have to end the element with a space, a slash and the “greater than” sign.
When typing attribute values, type them all in lowercase – unless it is for humans.
Always wrap your attribute values with quotes. Both single and double quotes are acceptable.
Indentation must be logical and readable. PHP code mixed within the HTML shouldn’t be an exception.

Check out the WordPress HTML Standards page at Make WordPress for more information.
CSS Standards

The list is a bit longer, but again, there are easy rules for proper CSS coding:

Properties should be indented with tabs.
You can group selectors but every selector must have its own line for readability.
Name all your class and id selectors with lowercase letters and don’t forget to separate words with hyphens.
Use readable selectors. .c6 is not a good name – name it .column-sixth!
No overqualifying. div.column is meaningless when you can just use .column.
Properties and their values should be in lowercase too, except for font names and vendor-specific properties.
Ordering for the properties needs to be “display, positioning, box model, colors, typography and other”.
You should also order the vendor prefixes from longest (-webkit-) to shortest (no prefix).
Keep your media queries at the bottom of your stylesheet.
Comment your CSS code as you comment in PHP. More on that later.

See the WordPress CSS Standards page at Make WordPress for a more detailed explanation.

JavaScript Standards

Since nowadays JavaScript is becoming crucial for many WordPress themes, we need standards and rules for it, too:

Braces can not open and close within the same line.
Prefer single quotes over double quotes, unless a string contains single quotes.
You’re free to use whitespace as you please in your code – don’t use whitespace on blank lines, though. And don’t forget that you’re using whitespace for readability – not for fun.
Name your functions and variables using camelCase, not_with_underscores. Constructors should be in TitleCase.
You can declare multiple variables on a single line; but if you’re going to assign values, you’ll need separate lines.
The new Array() and new Object() notations are “no-no”s. Use shorthand equivalents ([] and {}) instead.
Treat conditionals and loops very delicately – they’re usually the easiest to misread. Using braces and whitespace are key to this.
If you’re going to use jQuery; define an anonymous function, and pass jQuery as the argument before doing anything else. Check the example to make sure.

The WordPress JavaScript Standards page at Make WordPress has more information, bookmark this page and use it.

PHP Standards:

This is the more difficult part. There are tons of rules to consider:

Naming conventions
Single and double quotes
Whitespace usage
Regular expressions
“Yoda Conditions”
Special guest star SQL and formatting database queries

If you don’t know what they are, then maybe your best course is to tread lightly.

There are two awesome resources for you to learn it, though:

WordPress PHP Standards page at Make WordPress
The Wptuts+ series called “The WordPress Coding Standards” by Tom McFarlin

Properly Commenting Your Code

In order to let other developers understand how you made your theme, you need to make your theme code clear and readable – and this requires commenting your code.

The best practice for PHP is to use PHPDoc, the documentation style of phpDocumentor. It’s widely used between WordPress developers and recommended in the PHP Documentation Standards page at Make WordPress. It provides a clean documentation style for your PHP code.

As for CSS, the WordPress CSS Standards page at Make WordPress recommends you to do it like PHPDoc, along with a couple of other suggestions.

As for your HTML and JavaScript code, it seems that there’s no recommended or required way to comment your code, but this doesn’t mean that you don’t have to do anything: Try to be as clear as possible with your code and provide little bits of information by commenting anywhere you find necessary.
Validating and Testing the Theme

The theme may be working as a neat website in your head, but hopefully, there will be hundreds (maybe thousands) of people that will get to use your theme and be sure that they will try to make websites that you can’t possibly think of. Plus, there are requirements for theme marketplaces and theme directories for you to pull your theme together.

That’s why you have to test your theme and validate your code. I have three ideas for that:
Validate your HTML & CSS with the W3C Validators

The first thing you need to do is validate your code with the validation services of the W3C. Both the HTML Markup Validator and the CSS Validator services are used and developed for years and they’re the best validation services available.

After you do the two things below, simply check the demo pages with these two services to make sure there are no errors or warnings.
Use the “Developer” Plugin to Correct Your Theme

Developer is a free plugin developed by Automattic which, in their words, help WordPress developers develop. It’s actually just a plugin installer: The main purpose of the plugin is to provide the essential plugins for your development environment.

Developer suggests 16 various plugins. While some of them make your development process a lot easier (like User Switching and Theme Test Drive), some of them help you debug your theme (like Log Deprecated Notices and Theme Check).

The ones I find the most useful are Theme Check, Theme Test Drive and Debug Bar but all 16 plugins provide great features. I suggest that you install all of them to test the heck out of your theme.

Test Your Theme With Test Data

You can’t just code the theme and say that it’s completed – you have to test it with some content. You can create your own content but you should consider testing with some “test data”:

Use WordPress’ sample data. This sample data contains some of the most used content types and will help you notice your theme’s shortcomings against content you forgot to consider.
Use more exhaustive test data. is a little website with a scary collection of sample WordPress content. I’m not kidding: From menu items that go 10-level deep and Amazon Store embeds, this is the most exhaustive test data I’ve ever seen. I never tested a theme with this sample content but if you succeed to make your theme work with this data, you probably don’t have to worry about your theme looking dull in any scenario.

The only downside of these two tests is you won’t be able to test your content with shortcodes or the type of specific content you had in mind while developing the theme. I suggest that you test the theme with at least WordPress’ sample data, then create your own content. After all, you’re going to need solid content when you create the demo website for your theme.


Pro Photographer, WebMaster & Writer.. Please follow us on Facebook

KeithM.. – who has written posts on Tutorial Freak – Online Tutorials.

Help keep us alive & kicking, we need coffee 24/7, please donate, thanks!

Leave a Reply

error: Content is protected !!