What we’re going to take a look at here next is the anatomy of the Custom Loop API. First, we’ll be looking at the way the Thesis theme does its loop and secondly, we’ll look at different examples in the user guide about how to use the custom loops.
How Thesis Constructs Loops Based on the Main Query Condition
The best way to look at the Thesis theme loop is to really do so from the code itself. What I’m doing here is opening up thesis_185, library, classes and loop.php. Here is the Thesis loop and this is really what is controlling everything that goes on here. The way it starts off is that it has one of these two constructors, probably none of you are using PHP4 anymore so it’s probably just PHP5 so you’re using this PHP5 constructor which grabs the main query and equates that main query to a certain kind of loop.
For example, if the query is page, if it’s the front page then use the front query, otherwise, use the page query. If it’s home, use the home query, if it’s an attachment use the attachment query, if it’s not, use the single query. It’s just relating the main page query to a function and that function shows up here in the class so it’s this function ‘front’ and page is this function ‘page’ and you can scroll down here and see how the Thesis theme constructs its loops based on the main query condition.
Define Methods in Queries
What it’s doing here is essentially defining a method in classes. These functions are called methods so it’s defining a method for each of the types of queries available so we’ve got a front, a page, a home, single, an image, an attachment, category, tag, taxonomy, archive, day, month, year, author and search. There are a bunch of different types of potential queries and we have a method for each of those kinds of queries.
Define a Filter for the Methods
Now, it also defines a filter for each of these methods. You can see this call_user_func(apply_filters(‘thesis_custom_loop’, array(‘thesis_loop’, ‘page’))). What this filter does is it allows for the calling of this other class, the thesis_custom_loop class to come in and change this method. You don’t really need to understand how that works, just as long as you understand that it does work.
What it does is this thesis_custom_loop creates a filter and that’s this add_filter(‘thesis_custom_loop’ and with this filter, when you call the thesis_custom_loop, it runs back up here to the main Thesis loop and applies that filter to the given method. That sounds way more complicated than it actually is and you’ll see how it actually works here in just a minute but that’s the mechanics. What we’ll do is when we create our own custom loop, we will extend the thesis_custom_loop class that creates a filter which filters this next Thesis theme loop.
Four Definitions of Loops
Now, this Thesis theme loop really defines a whole bunch of different loop possibilities, image, attachment, category, tag, taxonomy. There really only has 4 definitions of loops. It has the page loop, the home loop, the single loop and the archive loop. You can see that if it’s a taxonomy query, what this does is this uses the archive loop. If it’s a tag query, it uses the archive loop, if it’s a category query, it uses the archive loop so there’s a whole bunch of things in here that are going to use the archive loop.
Same thing is true with this single loop. If it’s an image, it’s going to use the single loop, if it’s an attachment, it uses the single loop, if it’s a single, of course it is the single loop. There are lots of different query types and therefore lots of different loops available. Most of those loops point back to one of these 4 default loops, that is the page loop, the home loop, the single loop and the archive loop. These are the ones that we’re going to be monkeying around with when it comes a time for us to make a change here.
The way this works is that when you request a page in WordPress, say you request a specific category page, that’s specific page request comes in the form of a query. That query is called and in that case, if(is_category), so we come over here to our construct and it says, if the query is category, then use the category loop so now it comes down here with the category method. It comes down here to the category method and it says, okay here’s the category method and it says, use the archive loop then it comes down and processes the archive loop when a specific category is called. It’s the way this whole thing works.
Different Parts of the Custom Loop API
Now, we are going to be creating a custom loop and what we’ll do is run over here to the user manual on DIY themes. Over the user guide, we’re just going to start off simply by taking a look at the custom loop API. The custom loop API really has a couple of different parts. The first part is this extended class and what it’s doing is it’s defining a class my_loops which extends the thesis_custom_loop class and inside of that, you have all your functions.
Define a Class
The first most important part of using the Thesis custom loop API is to define yourself a new class that extends the thesis_custom_loop class which is this class down here. It extends the thesis_custom_loop class and the thesis_custom_loop class filters the thesis_loop class. That was the first part of this.
Instantiating the Loops
The second part of it is instantiating your loop and that’s the way you refer to creating another copy of a class. We haven’t really talked about class or object oriented programming because most of what you’re doing doesn’t really require that but if you’ve created this class, class my_loops, you need to instantiate a copy of this class or an instance of this class.
That’s what instantiate means, to specify an instance of this class and you do that by describing a variable name and you say equals new which is a new copy of my_loops and that is done here. These are two parts, you are instantiating the class which is essentially this thing, “a command from Thesis specifying which loop to run” then you are creating a class which extends the thesis_custom_loop class. Those are the two basic parts of this.
Direct Replacements for Defined Methods
Now, an extended class can contain either direct replacements for defined methods. For example you can see here it says, function home, in this case, function home is going to be a direct replacement for this function home. You know it’s a direct replacement because it is using exactly the same method name, “home”. If it didn’t use that method name “home”, it wouldn’t replace this.
If this thing said, function custom_home then it wouldn’t stand in as a replacement for that “home”, you have to name the replacements exactly the same and as a replacement, it entirely replaces whatever the default loop had. In this case, function home takes all of the homepage content, removes it and replaces it with echo “Hi mom!”; so that’s what’s happening here. You can define a replacement for existing methods.
Using New Methods Inside the Custom Loop
You can also add new methods. This example here doesn’t show you any examples with new methods but we’re going to be demonstrating how to use new methods inside of this custom_loop as we work our way through this process. Nevertheless, you can have those two kinds of methods. You can have the replacement method where the method name is exactly the same as the parent method or you can have a replacement method where you can name anything you want it to be named and it’s going to do something specific but not replace an existing method inside the main loop and we’re going to do both of those things.
The Thesis User Guide has a couple of examples. The first example is just this custom loop API and they’ve got that silly example where class my_loop extends thesis_custom_loop. The only thing this custom_loop does is it replaces all the homepage content with “Hi mom!”. This is probably a better example of this where inside of this class my_loop extends thesis_custom_loop below function home, what exist is this function category and in this case, it calls the thesis_archive_intro and it just changes it up a bit.
What happens in this case is that you have this extended classes instantiated, that’s $loopty_loop = new my_loops; and you’re extending the class by saying my_loops extends thesis_custom_loop and you’ve got the one hello world function for “home”.Then you have another one for category. In this case, when you do this thing here, this is going to apply to every single category page and the category method that exists in the main class will be replaced with this content.
Right off the bat, if we look at this category method for a second, category method uses the archive remember so it calls the archive_intro then it tests to see whether or not design options has this set of titles. If it has its set of titles, then it’s just going to display the titles and it may display the post image depending upon what is set so here’s that headline area which is where the title is.
Otherwise, if it’s not set to titles, it’s going to be the same as the homepage, whatever that homepage happens to be. Those are essentially your two choices in this archive setup and what it’s doing is it’s replacing all of these with this new code which puts the archive_intro in, puts the post_box top, format_text, ul. It has the posts, it just gets the title, that’s all it does, gets the title, gets the permalink, prints out the title and that completely replaces the standard things for every category.
Available Replacement Loops
I want to say one thing, each of these things, these are the available custom loops that is, these are the available methods that have already been defined, front, page, home, single, attachment, category, taxonomy, tag, day, month, year, author, archive, search, fourohfour and nothing. You can see those directly correspond to, function fourohfour, function nothing, search, author, year, month, day. Directly corresponds to each of these method names. You can change anyone of these loops on any given time this loop is called so these are the available replacement loops.
There’s another example though of the Thesis custom loop being used and that’s in this Thesis Skin Starter Kit. We’re going to come over and take a look at the Thesis theme skin example. This Thesis skin really is an example of this Thesis custom loop where it says, class thesis_skin_example extends thesis_custom_loop and it comes down here at the bottom and you can see there’s this instantiating of that class new thesis_skin_example.
In this case now, it’s got some additional functions. It’s got this public function__construct which relates directly then to the constructor function in the thesis_custom_loop class. It has this public function init which is being called by the constructor function, it has this public function actions which is being called by init, it has public function filters which is also being called by init, it has a private function switch_skin and this is also being called by init then it has the replacement loops and it has the home loop and the archive loop. This is an example of where this custom loop is creating its own functions plus using replacement functions.
Defining a Function
Now, as you look at this really, it’s not actually replacing these functions at all. It’s replacing the function with the same behavior so it’s not really replacement but if you’re going to, you could put the replacement information in here. If we come down and take at look at their advanced example, here’s this constructor, here’s an init, here are actions that he specified inside the action section, here’s a filter specified inside of filter and it’s got this function css which is applied to the thesis_css filter and. The thesis_css filter, he’s finding the example of this css then removing it.
He’s also got another function nav and that is setting up the primary menu inside of this loop and it’s got this switch_skin thing again. So he’s got a more extensive definition of each of these functions but they’re all sitting inside of this extension of the thesis_custom_loop. That’s really intending to show you that you can do a lot of things inside of your loop class besides simply modifying or replacing the pre-defined methods. You can also add other things.