Last week, I shared a post on how I go about organizing my WordPress theme functions.
Generally speaking, the conversation that ensued in the comments was more interesting the post itself (at least as far as I’m concerned :) because it raised some interesting points of how others organize their files, as well as raised questions as to some strategies for organizing other types of files.
Specifically, Mike said:
I did the same thing recently with the /inc/ folder and needing to add a bunch of different loop files for post types, wondering if I should add a folder within the /inc/ to separate the loop files from the other files I needed. I think I may have been over complicating things a bit, too.
I thought it was a good comment and my answer is a bit longer than a normal comment, so I thought I’d draft a post about it not only to share my thoughts, but also to allow others to chime in, as well.
After all, half the reason I end up thinking through some of the things that I do comes from opinions shared in the comment stream, in related Tweets, and so on.
WordPress Content Types
First, as it relates to organizing content types in WordPress, I usually break this down into three different types of files:
- Post Format Templates
Templates are the usual files that reside in the root of a theme directory and that are required to display content for archives, single posts, the main feed, and so on.
Partials are pieces of files that are often reused throughout multiple templates (think of things such as single post navigation links or perhaps a list of social media icons that may be displayed in both the header and the footer).
Post Format Templates are actually just partials, but they are dedicated to a specific type of post format. For example, in addition to the standard post format, WordPress offers support for images, audio, quotes, asides, and so on.
To that end, I’ve always found it much easier to create a partial for each of those formats and then call them whenever their respective post format is being used.
This can be achieved by using
get_template_part. For example:
The code comment should be clear enough as to how the files are organized, but this goes to show that I typically don’t include templates or partials (regardless of if they are post format partials or otherwise) in the
Libraries (Third-Party Utilities, Scripts, and So On)
Instead, I tried
includes (depending on how you name your directory) to store libraries, third-party scripts, or other server-side utilities.
For example, in Mayer, I use
inc to store the helper files (which are custom utilities that I’ve written), the navigation walker (which extends the WordPress core navigation walker class), the Theme Customizer code, and code specifically responsible for WordPress.com.
Then again, this may not be the best example because all of the code in this particular directory is code that I’ve written, but let’s assume that there’s a third-party server-side library that responsible for parsing, say, parsing text and formatting it a certain way.
In that regard, it can either go into
includes and then go into another subdirectory such as
vendor. My rationale for that is this:
includes are for, as we’ve mentioned, code that aids the core project in doing whatever it is that it needs to do, but most of that code is authored by us.
Adding a subdirectory, such as
vendor allows us to place-third party tools into the
includes directory while indicating that these are utilities written by someone else.
“Complicating Things a Bit”
In Mike’s original comment, he claimed that he may be complicating things a bit, but I find that this is something that almost all developers deal with. That is, we have this innate desire to make sure all of our code is as organized and as easy to understand as possible.
The challenge is that there’s no clear way to go about doing that (sure, in some cases we have standards, but not all). So instead, we’re left with working through a set of tradeoffs where we try to determine which has the largest set of pros and the smallest set of cons.
In that regard, I don’t think it’s a sign that we’re complicating anything – I think it’s a sign that we care about the way our projects are organized not only for organization, but for maintainability, as well.