Good morning everybody and welcome to Lesson 16 of the Customize Thesis Like a Pro tutorial series. Today, we are going to be talking about how to use the Thesis Custom Loop API. Before we really dive into that, I want to talk about what the Thesis Custom Loop API is.
What is the Thesis Custom Loop API?
In previous lessons, we’ve talked about custom secondary loops but the Thesis Custom Loop API is the way in which you can interact with the main loop on any page that is generated by the Thesis theme. A lot of themes or the standard WordPress way of dealing with templates is to have a variety of templates for a variety of contexts and each of those templates will have their own loop inside of them. In the absence of the correct template or a specific template, WordPress defaults to a more general template and a more general loop.
The Thesis theme really only has three templates. It has the default template, the archives template and the custom template. Since it has really only one template that it uses for all of the pages, posts, archives, authors, attachments, all of the different possible permutations of WordPress generated output, it has different loops that it uses in the case of different queries. That’s the way in which it handles the differences that you might want to have from an archive page or obviously do have from a regular page, from an archive page and from the homepage. It doesn’t change up the templates but it changes up the loop.
The Thesis Custom Loop API is the means by which you can write code that will change one of those primary loops. A secondary loop that happens in addition to the primary loop – we talked about secondary loops a few weeks ago. This is on this page here, this is my primary loop and it’s really just displaying the content of the page but then I have a couple of secondary loops so I have the secondary which shows all of the current lessons in this course and another loop that shows all of the different lesson subjects that relate to customizing the Thesis theme. We have these two different secondary loops sitting on top of this page.
Changing the Primary Loop Output
If you want to affect the primary loop from this page, the way you would do that is by using the Thesis Custom Loop API and that’s really when you’re going to use it. You’re only going to use the Thesis Custom Loop API when you want to change the primary loop output for any given post, page, archive, type or whatever. Really, one of the most common examples of the use of this is going to be either in the home page display or in an archive page display. Those are the examples that we’re going to look at today.
Chances are, you don’t really need to change the loop in a regular page and you probably don’t need to change the loop in a single page but there are lots and lots of examples of where you might want to change loop on a given set of categories or on a given category or on the homepage only but let all of your category archive pages be the same or something like the kind. Those are the kinds of things we’ll be looking at here today.
The way it works is when a main query is called, Thesis looks at that query, asks some questions about that query and decides which loop to run based on the information in that query.