export default "data:image/svg+xml;base64,PHN2ZyBhcmlhLWhpZGRlbj0idHJ1ZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgNjAgNzUiPjxkZWZzPjxzdHlsZT4uYXtmaWxsOiNmZmY7fTwvc3R5bGU+PC9kZWZzPjx0aXRsZT5UUlEtTEdPLVEtUkdCPC90aXRsZT48cGF0aCBjbGFzcz0iYSIgZD0iTTkuNzEsOS41NGEyOC44LDI4LjgsMCwwLDAsMCw0MC42NGwuMTMuMTJoMEwzMy43NCw3My44NlY1OC4yNWExOS43LDE5LjcsMCwwLDAsMi4zOS0uMzUsMjguMjksMjguMjksMCwwLDAsMTQuMTYtNy43MkEyOC43MiwyOC43MiwwLDAsMCw5LjcxLDkuNTRaTTQyLjQ0LDQyLjMyYTE3LjQ2LDE3LjQ2LDAsMCwxLTguNzcsNC43NVY1OFMxOC4wNSw0Mi44LDE3LjU2LDQyLjMxYTE3LjYsMTcuNiwwLDEsMSwyNC44OCwwWiIvPjwvc3ZnPg=="
Torque

Best Practices for WordPress Theme Development

Filed Under

Featured

Published

August 25, 2014

6 Comments

WordPress is slightly addictive. I always thought of it as a gateway drug into the world of web development.

Maybe you started off just needing a simple website. You figured out how to install WordPress on your server, chose a theme that suited most of your needs, set up some widgets, maybe installed some plugins, and that was it for the beginning.

Then came the day you really wanted something on your page but couldn’t find a plugin for it, and it wasn’t part of the theme options either. Or maybe someone told you about Firebug and showed you how to change the color for an element on your website and it completely blew your mind.

So you became a little more curious.

An intense googling session later, you managed to change some lines of code in the stylesheet of your small, innocent website. As FileZilla pushed back the modified file onto your server — you waited, biting your nails — fearing that your website would be irreversibly ruined. Maybe you would even break the internet.

But lo and behold, instead the site did exactly what was promised by that anonymous forum post.

That’s when you became hooked.

What followed was a blur of setting up your first child theme, changing the header image without using the theme options, setting up post templates, pasting some PHP code in your functions file, registering a new widget area, and wondering when exactly you became fluent in css.

As the dust settled and you leaned back in your chair, you realized that by now the site had nothing to do with the original setup anymore. The color was changed, all the headings were customized with new typography, and you even got rid of that secondary navigation that always bothered you.

By the love of God. . . Did I just create my own theme?

You sure did. Even the person who made the original wouldn’t recognize it anymore.

Maybe by now you’re ready to take it to the next level. You’re done merely modifying other people’s work and instead want to go for the big one: your own theme in the WordPress theme directory.

You want to do it right, right? Not just throw it together so that it just barely works? In that case it’s important to become familiar with a few best practices for theme development, so you produce a beautiful work of art and not a crude hack job, even if you don’t want to make your theme available for other people.

Respect WordPress Coding Standards

As anyone who was ever hired to work on a website that was created by someone else can attest, it can be painstaking if the other person has their own special way of writing code. Not only do you have to understand the architecture of the site in general, but you also first need to figure out how to read it.

To avoid this type of situation, WordPress has well-established coding standards for PHP, HTML, and CSS. The standards have been agreed upon by the WordPress community as best practices. Following these standards will make it much easier for other developers to read and modify your code.

The reason why they exist is to create a baseline for collaboration. This is fundamental because (as you know) WordPress is open source, and therefore has contributions from many different sources. Same goes for themes and plugins, which are written by individuals and then made available to everyone else.

The coding standards help avoid common errors, improve readability, and make modifications easier. They also ensure congruity across all files. Following the standards means your code can be read, understood, and modified by anyone regardless of when it was written and by whom.

Example:

To ensure legibility of CSS, WordPress coding standards recommend the following structure:

  • Use tabs, not spaces, for indentation.
  • Give each selector its own line, ending in either a comma or an opening curly brace. Property-value pairs should each have their own line. The closing brace should be using the same level of indentation as the opening selector.

Correct:

#selector-1,
#selector-2,
#selector-3 {
    background: #fff;
    color: #000;
}

Incorrect:

#selector-1, #selector-2, #selector-3 {
    background: #fff;
    color: #000;
    }
 
#selector-1 { background: #fff; color: #000; }

Much better, right? You can find the coding standards in the WordPress Core Handbook:

Keep Your Theme Files Organized

Every web project is different and requires a different set of resources. Some applications run on desktop computers and manage with a single language. Some need a second one and aim for mobile devices.

Other projects — such as WordPress Themes — can include anywhere from three to four (HTML, CSS, PHP, and JavaScript) languages. Moreover, theme components can run on the side of the client or server, and communicate directly with WordPress or the database.

Due to these complexity concerns, keeping your resources organized is vital. Failing to do so just makes it messier than necessary, and hard for those who want to build upon your work — be it other designers, developers, or users. WordPress suggests certain standards for organizing your PHP template files, stylesheets, JavaScript sources, and images, which are easily followed and can be found in the WordPress Developer Handbook.

Theme file organization in short form:

  • Set up template files for individual page components (header.php, footer.php, sidebar.php etc.) instead of cramming it all into one file.
  • Keep your main template files within the theme’s root directory.
  • Give JavaScript, page templates, CSS, image and language files (more on that below) their own directory.
  • Be unambiguous in file naming, prefix page template “page-about-template.php” or nest inside “page-templates” folder.

More on this topic:

Adhere to Template Hierarchy

Since we are talking about file organization: The different components of WordPress fit together like a big puzzle. In order to generate a website, templates and files are used to produce its different parts. Some of them are displayed on every page (think header or footer), others (such as category or search pages) appear only under certain conditions.

There is a hierarchy in place that determines which template the WordPress platform will use for each. If the first choice is not available, WordPress will then use the second on the list and so forth. For theme development, a proper understanding of this hierarchy is vital and you need to familiarize yourself with it to ensure that what you’re developing is using the correct templates in the intended places.

It can be a complex topic. However, in order to make it a little easier, in 2013, WordCamp Minneapolis put together this poster:

Alternatively, there is of course official documentation on template hierarchy in the WordPress Codex, which provides an explanation for how theme files fit together, and how each is rendered by WordPress. ‘Stepping into Templates‘ also provides a detailed breakdown of template files and their structure.

Internationalize/Localize Your Theme

This might come as a shocker, but WordPress is no longer a niche product used by a small group of developers who are all hanging out in the same online newsgroup. It has become a worldwide phenomenon. I know, I’m as surprised as you are.

That also means that not all WordPress users come from English-speaking countries. In fact, two-thirds of users live outside the US.

And because the platform has been so widely adopted, the market for themes isn’t limited to a single language.

On top of that, WordPress makes it incredibly easy to localize your theme, and requires only little extra effort. If that’s not enough reason to make your themes translation ready, I don’t know what is.

Internationalization vs. Theme Localization

Making your theme accessible for non-English speakers comes down to two acronyms: “i18n” and “l10n.” I18n is an abbreviation for internationalization and is called i18n because there are 18 letters between “i” and “n.” Similarly, l10n is the numeronym for localization (as in “L” followed by ten more letters, and then “N”).

Internationalizing your theme means you make it ready for translation. What it basically comes down to is changing the text strings inside the theme into functions so they become translatable. Localization is the actual transfer of theme strings from one language to another. If you are fluent in another language, you might translate your theme yourself. Otherwise you can at least give others the chance to do it for you.

To achieve this, WordPress uses the GNU gettext localization framework. Developers wrap translatable strings in special gettext functions. The source code files are then parsed by special tools and the translatable strings extracted into POT files (which stands for Portable Object Template).

The second step involves translating the text inside the POT file into the target language, saving both the original and the translated strings in a PO (Portable Object) file. PO files are identical to POT files except for their purpose, which is being compiled into binary MO (Machine Object) files in step three. These files provide faster access to the strings for machines.

Resources on this topic:

Tools for creating  POT files:

  • Poedit – a free gettext translations editor
  • Launchpad – a software collaboration platform which can be used for WordPress theme translation
  • Pootle – tool for community localization
  • GNU Gettext – the original GNU Translation project

If you want to offer your help localizing WordPress itself and its subprojects, you should swing by GlotPress, the official translation tool for the WordPress project.

Test Your Theme

As with every good piece of software — a WordPress theme being nothing else — a considerable amount of time has to go into validating that everything works as it should. There is nothing more frustrating than installing something that is full of flaws, and nothing will make people stop using your creation quicker.

That being said, testing is a mandatory part of theme development before releasing your work to the public. In addition, if you are planning to put your theme into the WordPress directory, the validation team there will do the same and will reject your theme if it doesn’t measure up. Rejection hurts, so you might as well address errors beforehand.

In case the goal is for your theme to be added to the directory, it must pass the guidelines laid out in the Theme Review section. However, even if you are using the theme for yourself or a client, you should run it through a testing regimen similar to the following:

  1. Find and fix PHP and WordPress errors. Enable debug settings by adding “define(‘WP_DEBUG’, true);” (without the quotation marks) to your wp-config.php to see deprecated function calls and other WordPress-related errors.
  2. Check template files against the Template File Checklist to make sure they meet WordPress standards.
  3. Validate HTML and CSS. WordPress provides an extensive list of code validation tools.
  4. Check for JavaScript errors if you have used it in your theme.
  5. Run the Theme Unit Test: Download the WordPress export file from this page, import it into your installation, and follow the instructions for a thorough theme test.
  6. Test theme with all your target browsers. For example, IE7, IE8, IE9, Safari, Chrome, Opera, and Firefox.
  7. Test-drive with real people. Ask friends, relatives, and co-workers to try out your theme before making it public.
  8. Clean up comments, debug settings, and other items that have no place in the final product.

Other Useful Tips

Follow WordPress Development News

Since WordPress is constantly changing, anyone interested in developing with the platform is well-advised to stay up to date on the latest news and announcements related to WordPress development. This way you can make sure you are aware of new features, security fixes, and other aspects of WordPress that might affect your work.

Some helpful sites include:

General Resources for WordPress Theme Development

Do you have anything to add to this list? Share your thoughts in the comments below!

Nick_Schäferhoff_square_smallNick Schäferhoff is an entrepreneur and writer/blogger from Germany. He learned WordPress when he needed a website for his first business venture and instantly fell in love. He is passionate about health, productivity, and continuous learning, which he writes about on his lifestyle blog. When not building websites, he likes to travel the world, experience other cultures, and learn new languages.

Author

Nick Schäferhoff

Nick Schäferhoff is an entrepreneur, online marketer, and professional blogger from Germany. He found WordPress when he needed a website for his first business and instantly fell in love. When not building websites, creating content or helping his clients improve their online business, he can most often be found at the gym, the dojo or traveling the world with his wife. If you want to get in touch with him, you can do so via Twitter or through his website.

More articles by Nick Schäferhoff

Tagged:

Reader Interactions

There are 6 comments

How do you stay on top of your WordPress game?

A good way to start is to sign up for our weekly newsletter. We keep you up to date by bringing you the freshest WordPress content from the brightest minds in the industry.