WordPress Theme Structure the right way

WordPress is a very extendible platform. You can create almost everything using WordPress as an web app framework. In my WP developing experience i have evolved over time the way how i develop themes.

My first themes where not the best ones viewed from the point of view of code organization, files and folder structure, etc. From the end-users point of view this might not look like much since the end-user only sees the front-end but a developer puts more value to the code that creates the front-end then the front-end itself.

Whenever i start working on a WP project, first thing i check is, if its a rework or starting from scratch. I do love to create themes from scratch since it gives me the freedom i need to work on my own terms, on my own rules and following the practices that i will describe below. On the contrary working over someone’s else work its sometime a big headache since first thing you need to do is to check their code, how files/folders are structured, etc … but this does not necessarily have to be like this.


Before you start creating the theme analyze the project

This is probably one of those things that are very very important and need to be done correctly. Its not like this cant be rechecked later, even if you do a project analysis and then you recheck and change it, it still can work … but if you mess up things badly in the first project analysis it will be hard for you while rechecking.

You need to focus on your project analysis on graphical and functional implementations and first of all, you need to be clear on how each and every functionality or graphical element will be implemented. The ones that are not clear to you in that moment set them to be researched. You need to know exactly how each element will function, if possible where will the “form save the data”, where does the “select get its data from”, etc. Small details like this might look non important but you need to know exactly at the beginning what functionalities will be incorporated in the theme, what will be done using plugins, etc. Knowing this … it helps knowing how to structure your theme files and folders.

Start with a good starter theme

I’m a big fan of Underscore starter theme. Its a starter theme built and backed from the guys at Automattic (the guys after WordPress) so its built following the latest standards in WP theme development, its always updated, etc. As its name says its a starter theme so what you get is just the basic functionalities but no graphics at all … if you activate it, it will look bad (its not a bug/problem … that’s how its supposed to look, its a starter theme).

Also im a big fan of Bootstrap and Foundation and i love to develop themes with either one of these frameworks since it helps developing themes mobile-ready by default. I would recommend using Understrap theme (Underscore + Bootstrap) or FoundationPress.

I have worked with both of them and they have both a solid setup over the which you can build almost everything. I usually like to customize their files/folders structure but will talk about that a bit later.

Clean and minimize everything

So ok, you have until done a project analysis, you have chosen your starting theme of choice. Now its time to start cleaning up your starting theme and adapt it to your own implementation for the current project. You might say, how and why should i clean an already minimial/cleaned starter theme?

Usually starter themes (as all themes in general) are suited to be fit for a universal end-user experience … but some of them might include features you might not need (for example Understrap includes a hero slider features which i dont use that much). So you now know what are the requisites for your current project … so lets say for example you dont need comments on your website. Clean all the code that references comments, you need an extra menu … add an extra menu, you need another widget area, create another widget area, etc.

So clean everything un-needed and add all whats needed to make your project work. Create the basic structure (widgets, menu) for your project.

Check all php files and clean everything that is not needed for your project, the less code you have the better it is.

Optimise folders structure

Some themes have css, js, img folders right in their root, this is not a problem in the wp world but i love to keep things organised. So almost always first thing i do is to create an assets folder, move inside that folder css, js, fonts, img folders and modify functions.php (or whatever file that enqueues scripts) to change the file paths.

Next thing i do is to create an includes folder (if it does not already exist) and add there 3-4 new folders based on my project. For example i create folders like:

  • admin
  • extras
  • vendor
  • shortcodes
  • setup
  • etc

Like to divide all includes in folders since this way its easier to know whats inside each of the folder and know how to find stuff more easily. For example if i want to know where a shortcode is declared … i just open the shortcodes folder and thats it.

This makes thing much more scalable … no matter how big or small my project is the code is already scalable by default. No reason to use MVC, OOP to make code scalable, just by using a right combination of folders/files structure you give the idea of a scalable application.

By having this scalability by default approach always in mind, it helps the project a lot. The code in this approach is not all contained in 1 single file (usually functions.php) but its divided in sections (files) all included in the main functions.php.

This way on the project can work more then 1 single developer since all of them add/modify/delete features/functionalities in different areas of the project without ever having to touch a work that another developer has done.

The code is much more organised, easier to find, easier to be mantained, etc … so this approach is always a WIN, noone loses here.

Loop the right way

A lot of badly programmed themes dont have different files for the loop content. This is a bad practice, old themes usualy have the loop content inside of archive.php, index.php, etc files. New themes and/or themes developed the right way always include the loop content from another file using gettemplatepart function. This way its way better, its easier to just modify that 1 file (or set of files) and the changes will be done everywhere that file is included. So instead of finding the loop in 10 different files and changing it, you only change it once and the changes are implemented everywhere.

This is something that is not really found very often since its a very old practice but there are still programmers who do this and thats why im pointing out that this is a bad practice and shouldnt be used anymore. For all the guys who followed my advice of working with Underscore, Understrap or Foundationpress, you will be happy to know that all these themes have already implemented and are using best practices so you can skip this :)

Templates (Page and Post Templates)

In wordpress you can create as much page templates as you want. Page templates permit you to create custumized templates for pages, for example if you want to have a customized Projects page in your website, you can very easily create a new file, lets say page-project.php, copy content from page.php to page-project.php and at the top of that file, right above the get_header() function, add 1 simple line of code:

Template Name: Projects

Starting from WordPress 4.7 (that will be released sometime on December 2016), WordPress will add the possibility for developers to create single post custom templates also. Do same actions as creating custom page template (only this time copy single.php not page.php) and add these 2 lines of code:

* Template Name: Custom Post Template
* Template Post Type: post

Its as simple as that to create single post custom post templates and i have already used it in practice … its a really great help and big step forward on making WordPress the best CMS there is :p

Now we know how to create page and post templates and lets say we have created 4 page templates and 3 post templates. So in total 7 custom page/post templates, which is a lot of files, counting the normal wp theme files.

Thats why i always create 2 new folders on my root theme folder and call the 2 new folders:

  • page-templates
  • post-templates


Remember to not use spaces here, always used dashes. Move the custom page/post templates inside the 2 new folders. Here it is now, we made again our code more scalable, more organised, more mantaineable, etc.

Its as easy as that to make your code look good, it might be rubbish code, it might not do what its supposed to do but at least its maintaneable, well organised, etc. At least you could do this.

Partials and Modules

There are times that in our project, in different pages we might use same modules (components) over and over again.

Let suppose for example we have a website that has 2 different headers, 1 of them is shown only in homepage and the other one everywhere. What i do in this cases is create a new folder called partials, and add there 2 new files, lets say:

  • header-homepage.php
  • header-main.php

In the header.php file in the root theme directory i include these 2 themes based on where i am (using gettemplatepart) and if/else check to check where i am.

These kind of elements are what i consider as partials. Sometimes we have components that are page elements. Not wp elements (like a header/footer, etc) but page elements. Lets say for example a custom box with a newsletter that appears in directly below the post.

There are different ways of achieveing this for sure but for the sake of this lesson im gonna use the modules abstragation to explain 1 of the ways to achieve it.

Create inside the partials folder or directly in the root theme folder (i personaly prefer to create a new folder called modules inside partials but here i wouldnt really put rules on how you should deal with this situation) and inside the modules folder create a new file called newsletter.php. Then include the newsletter.php file wherever its needed using gettemplatepart(), as simple as that.

Be consistent while coding

No matter how big or small the project is you should always be consistent on how you code. If you start the project using double quotes on echo, then go with that all along your project, same thing for commenting, same thing for everything else, be consistent. Create a set of rules you will use and follow them strictly. This will help making less mistakes, being more disciplined and beign more disciplined helps finding mistakes more easily :p.

Final notes …

I have gained this experience im sharing here over a lot of time working as wordpress theme developer, i learned not doing these mistakes sometimes in practice and sometimes by reading (so in theory). I would like to see others not do same mistakes i once did when i started developing themes.

Published 20 Nov 2016