Thesis Custom Loop API

This document is deprecated! The information on this page refers to a Thesis version that is now obsolete. Please visit the Thesis Docs for current documentation.

The Thesis Custom Loop API provides you with a simple way to serve custom markup and run custom PHP inside the #content div on any page of your site.

In other words, this is powerful stuff 😀

API Components

The Thesis Custom Loop API consists of two key parts:

1. a command from Thesis specifying which loop to run
2. a PHP class extension containing custom output for one or many types of loops

If the PHP class extension in Part 2 contains custom output for the loop specified in Part 1, then the custom output will display instead of the Thesis default.

Part 1 is a no-brainer, as Thesis handles the heavy lifting behind the scenes. Part 2, however, is where the magic happens, and that’s what we’re going to focus on next.

How It Works

The easiest way to learn how the Thesis Custom Loop API works is by way of example. To begin, let’s look at a sample custom loop that will replace the content of the home page loop:

$loopty_loop = new my_loops;

class my_loops extends thesis_custom_loop {
	function home() {
		echo "Hi mom!";
	}
}

Don’t let the size of that code snippet fool you—it packs quite a punch! Thanks to the Thesis Custom Loop API, that bit of code transforms the home page content from the Thesis default to this:

Now, that may not be the prettiest thing you’ve ever seen, but the implications are huge. Let’s take a moment to dissect the code that created the output in Figure 1.

The keen among you will no doubt have noticed the absence of any hook or filter calls, which are typically necessary to “activate” custom code in the custom_functions.php file. Instead of a hook or filter, the Thesis Custom Loop API simply requires you to instantiate a PHP class extension, like so:

$loopty_loop = new my_loops;

In the above code, the variable $loopty_loop is being assigned a new instance of the my_loops class. In order to work with the Thesis Custom Loop API, my_loops must be a special kind of class—it must be an extension of the thesis_custom_loop class. This is accomplished through the use of the extends terminology, as seen in the my_loops class declaration:

class my_loops extends thesis_custom_loop {
	function home() {
		echo "Hi mom!";
	}
}

If this API is like a business, then thesis_custom_loop is the middleman. It knows which loop Thesis wants to run, and it knows which loops you’ve defined. When there is a match between the requested loop and one of your custom loops, thesis_custom_loop will run the appropriate custom loop.

In our example snippet above, the only defined loop is the home loop, so custom output will only display on the home page. All other types of pages will be unaffected.

Available Custom Loops

• front — Front page of your site. Note: front page display must be set to a static page inside WordPress for this to have effect.
• page — Every page of your site except the front page if one is enabled.
• home — Your home page or, if a front page is enabled, your blog’s home page.
• single — All posts (often confusingly referred to as “single-entry pages”).
• attachment — Individual pages for post attachments (usually images).
• category — Category archive pages.
• tax — Taxonomy archive pages.
• tag — Tag archive pages.
• day — Daily archive pages.
• month — Monthly archive pages.
• year — Yearly archive pages.
• author — Author archive pages.
• archive — Generic archive pages; this loop is the default for category, tax, tag, day, month, year, author, and search pages.
• search — Search results pages. Note: This loop should also account for searches that do not return any results.
• fourohfour — 404 pages.
• nothing — This loop will run if there is nothing in the database to display.

Example Custom Loops

Example 1: Serving a Custom Loop on Category Pages

In this first example, our goal is to override the default loop for category archive pages with a simple list of post links. Here’s the function you’d put inside your my_loops class to achieve this:

function category() {
	thesis_archive_intro();
	echo "<div class=\"post_box top\">\n";
	echo "\t<div class=\"format_text\">\n";
	echo "\t\t<ul>\n";
	while (have_posts()) {
		the_post();
		echo "\t\t\t<li><a href=\"" . get_permalink() . "\">" . get_the_title() . "</a></li>\n";
	}
	echo "\t\t</ul>\n";
	echo "\t</div>\n";
	echo "</div>\n";
}

There are four noteworthy points here:

1. The function is named category(), and as a result, this loop will only run on category archive pages.
2. The call to thesis_archive_intro() is important because it preserves the SEO and content functionality that Thesis makes available to you in the WordPress category/tag/taxonomy editing area.
3. We just wanted to output a linked list, so what’s up with <div class="post_box top"> and <div class="format_text">? These divs are special because Thesis supplies extensive formatting for each. By including them, you’ll be able to take advantage of pre-defined spatial styles and typographic goodness that will make your job easier.
4. The while(have_posts()){} construct is the very essence of the loop—it “loops” through the posts that are currently in the query and executes the code between the curly braces {} for each post.

Example 2: Serving a Custom Loop on a Specific Post, Page, Category, Etc.

If you were using the code given in the example above, the output of every category page on your site would change. However, what if you only wanted to change the output of a particular category page?

For the purposes of this example, let’s assume that you want to serve a custom loop for the “Popular” category, but you’d like to leave the rest of the categories alone. Here’s the code to do just that:

function category() {
	if (is_category('Popular')) {
		thesis_archive_intro();
		echo "<div class=\"post_box top\">\n";
		echo "\t<div class=\"format_text\">\n";
		echo "\t\t<ul>\n";
		while (have_posts()) {
			the_post();
			echo "\t\t\t<li><a href=\"" . get_permalink() . "\">" . get_the_title() . "</a></li>\n";
		}
		echo "\t\t</ul>\n";
		echo "\t</div>\n";
		echo "</div>\n";
	}
	else
		thesis_loop::category();
}

The only difference between this code and that found in Example 1 is a conditional statement that targets the “Popular” category. Let’s take a closer look at that conditional:

if (is_category('Popular')) {
	// Actual loop code removed for clarity
}
else
	thesis_loop::category();
}

The if(is_category('Popular')) statement targets the “Popular” category, and there are three ways that you can target a particular category:

1. by its id, which is an automatically-generated number with zero semantic significance
2. by its category slug, which you can define and view in the Edit Category section of your WordPress administration panel
3. by its category name, which can be defined, edited, viewed, and also has semantic value that makes it easy to remember

In the example code here, I’ve chosen the third option, but any of the above three will work inside the is_category() conditional statement.

Next, let’s take a look at that curious call to thesis_loop::category(). If it is determined that we are not viewing the “Popular” category, then thesis_loop::category() will force Thesis to run the default loop for category pages.

For those of you who are unfamiliar with the syntax surrounding PHP classes, the class_name::function_name() construct is simply a concise way to call the function_name function that lives within the class_name class. The thesis_loop class contains all of Thesis’ default loops, so thesis_loop::category() refers to the default category loop.

Pretty neat, huh? 😀