Organizing WordPress Content Types and Libraries

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:

  • Templates
  • Partials
  • 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_post_format and 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 inc or includes directory.

Libraries (Third-Party Utilities, Scripts, and So On)

Instead, I tried inc or includes (depending on how you name your directory) to store libraries, third-party scripts, or other server-side utilities.

Mayer Helpers and 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 inc or 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 lib or 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.

8 Replies to “Organizing WordPress Content Types and Libraries”

  1. Good to know I’m not just going crazy and over complicating things. That makes the late night brainstorming sessions I’ve been doing lately seem more worthwhile :)

    I’m glad my comment inspired this post, it fleshed things out a bit more for me and I think I’ll be using the /lib/ folder to better organize things that I’m using from third-parties.

    For the get_template_part part, it looks like you keep the content- files directly in the main folder of the theme, correct? I currently have mine in the /inc/ folder, which I think I’ll be moving soon to a new /inc/loop/ folder. Might not work best for everyone, but for me, visually, I like to see things broken down into folders as best as possible so I think this might work best for me.

    But then again, I doubt I’ll ever be done testing and reorganizing things, and that’s ok too :)

    1. Good to know I’m not just going crazy and over complicating things. That makes the late night brainstorming sessions I’ve been doing lately seem more worthwhile :)

      Welcome to the club :).

      For the get_template_part part, it looks like you keep the content- files directly in the main folder of the theme, correct?

      When it comes to themes, I usually do because it makes the code much easier to read when writing something like get_template_part( 'content', 'image' );; however, when it comes to plugins or application-esque projects, I’ll break things down a bit differently into other directories (like partials, for example).

      1. Thanks for the clarification on the get_template_part, makes more sense and I might adopt that in future themes I create, or at least test it once or twice to see if it feels like a better fit for me.

  2. Super interesting (as always) and does help explain your logic.

    I have a strong preference for having /inc (my code) and /lib (3rd party code) both in the root rather than nested. I think putting 3rd party libraries in /inc/lib/vendor just buries them too deep.

    Also I for me, and I’m a novice here, I think of /inc just including functional code, not templates/template parts. If I had a lot of template parts or loops I’d probably give them their own directory instead keeping them in root, but that’s rare in the work I do.

    1. I can definitely understand the notion of having things nested too deeply into directories – at some points, it’s like “how far down do I have to drill to find the code?” so there’s certainly a balance to be struck.

      As far as inc, templates, partials, and all of that is concerned, I normally break it down like this:

      • inc
      • templates
      • templates/partials

      But that’s just me – I know plenty of other developers have kept their partials in the root of their theme directory, and that works fine too especially if the code is easy to read :).

  3. I have toiled with this for a good month just a while back.

    After much angst, I wound up settling on using:

    • inc for internal project dependencies, like broken out functions.php actions / hooks and such

    • lib for external project dependencies, like things I pull in with Bower or Composer and then copy only what I want to use and commit to GitHub into lib

    • templates for full page custom templates

    • templates/partials for all little reuseable parts, like dates / times, loops, meta, etc.

    1. I have toiled with this for a good month just a while back.

      As you know, welcome to the club :).

      inc for internal project dependencies, like broken out functions.php actions / hooks and such lib for external project dependencies, like things I pull in with Bower or Composer and then copy only what I want to use and commit to GitHub into lib

      I’m not using Bower of Grunt for many personal projects – at least not yet – but I’m sure that my directory structure may change once I do that.

      Maybe, at least ;).

      templates/partials for all little reuseable parts, like dates / times, loops, meta, etc.

      We’re the same page here.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.