In the latest release of the Thesis theme for WordPress a new feature for advanced theme customization was added called the Thesis Custom Loop API. The Thesis User’s Guide explains the basics of how to use the Custom Loop API. This article expands on that documentation, offering additional context to explain what the Custom Loop API is, what it’s good for, and examples of how to use it.
Wait! There’s more! I’ve written a follow-up to this article, Thesis Custom Loop Starter Template, which provides a complete custom loop class ready for you to customize, along with useful helper methods and additional explanations.
A Bit of WordPress and Thesis Background
To understand what the Thesis Custom Loop is, we need to take a step back, and look at just WordPress. Setting aside plugins for a moment, before the Thesis theme, there was only one way to alter the HTML and contents of your site’s theme: hack away on the theme files themselves. And once you started hacking on your copy of a theme’s files, it became a real challenge to update to a newer version of that theme.
Among other innovations, the Thesis theme made it possible to customize the theme extensively without altering the theme’s files. By isolating theme customizations into a few files in the
thesis/custom directory, it became easy, almost trivial to update to newer versions of the theme. (These days child theme functionality is built into WordPress, but it works differently than Thesis, overriding theme files directly, rather than with an API, so it’s not relevant here.)
Thesis achieved this by moving the vast majority of the theme’s code out of standard WordPress theme files and into libraries and classes in the Thesis core code, and weaving into it the Thesis API–the hooks and filters we know and love.
With Thesis, you don’t hack away on the theme files, because there is nothing there. (Check out the
thesis/index.php file, it has one line of code.) Instead of altering the HTML and WordPress Loop code directly, you use the hooks and filters to re-order, remove, or alter the various pieces of the Thesis HTML, post content, metadata about those posts (tags, categories, author, etc.), and so on.
What is the Thesis Custom Loop API?
If you have worked with Thesis much, at this point you’re thinking “I know all this, but what does it have to do with the Custom Loop API?”
Standard WordPress theme files don’t merely contain HTML and content tags, they also contain The Loop. The Loop is the heart of WordPress output, and it is how WordPress acquires, processes, and iterates through a set of posts (or pages, etc.) to convert them from database table rows to e.g. your blog’s home page.
When Thesis moved the contents of theme files from the files themselves to functions and classes inside Thesis, it also moved The Loop. While you can use hooks and filters to alter the HTML that Thesis generates when processing The Loop, before Thesis 1.8 there was no (good) way to use anything but a standard WordPress Loop on a Thesis site.
The Thesis Custom Loop API opens that up again. A cynic might say it just returns a built-in WordPress feature that was taken away by earlier versions of Thesis, but actually the Thesis Custom Loop can be a much cleaner way to work with The Loop. We’ll see how in a bit.
Continue reading “How to Use the Thesis Custom Loop API”