Thesis Custom Loop Starter Template

As an addition to my article on How to Use the Thesis Custom Loop API, here is a Custom Loop starter template you can use for your own loops. Every loop you can customize in Thesis 1.8 is stubbed in, and comments before each method provide helpful reference information. All you need to do is replace the one-line stub methods with your own custom loop code. You can delete any loop method you’re not customizing, or leave them in place for the future; they simply apply the appropriate default Thesis loop.

(The comments more than double the file size. If you find them distracting, here’s a truly minimal version.)

Thesis Custom Loop Template

/**
 * These are the different Thesis loops that can be customized.
 *
 * Replace the calls to the default Thesis loops with your own code.
 * You can also delete any unused loop methods.
 *
 * @link http://codex.wordpress.org/Conditional_Tags More details of 
 *       which page requests trigger which specific loops.
 * @link https://aldosoft.com/blog/2011/01/the-thesis-custom-loop-api/ Detailed
 *       article about how to use the Custom Loop API.
 */
class my_looper extends thesis_custom_loop {
    /**
     * The loop for the blog index page.
     *
     * By default this is the home or top-level index page.
     * Can be changed to any page using Settings > Reading > Posts Page.
     *
     * This loop is used by the {@link archive()} loop (and all child loops)
     * unless Thesis > Design Options > Display Options > Archives is
     * set to Titles Only.
     */
    function home() {
        thesis_loop::home();
    }
    /**
     * The loop for the front page of the site if configured in 
     * Settings > Reading > Front Page. 
     *
     * Has no effect if no front page is set.
     *
     * By default, delegates to the {@link page()} loop.
     */
    function front() {
        thesis_loop::front();
    }
    /**
     * The loop for displaying an individual post, i.e. the 
     * one-article-per-page view of a post.
     *
     * Sometimes referred to as "single-entry pages".
     */
    function single() {
        thesis_loop::single();
    }
    /**
     * The loop for displaying an individual attachment on a post, 
     * usually an image.
     *
     * By default, delegates to the {@link single()} loop.
     */
    function attachment() {
        thesis_loop::attachment();
    }
    /**
     * The loop for a static, individual page.
     */
    function page() {
        thesis_loop::page();
    }
    /**
     * Default loop for archive-style pages.
     *
     * This loop is the default for category, tag, tax, author,
     * day, month, year, and search pages.
     *
     * Important: Delegates to {@link home()} unless 
     * Thesis > Design Options > Display Options > Archives is 
     * set to Titles Only.
     */
    function archive() {
        thesis_loop::archive();
    }
    /**
     * Loop for category pages.
     *
     * By default, delegates to the {@link archive()} loop.
     */
    function category() {
        thesis_loop::category();
    }
    /**
     * Loop for tag pages.
     *
     * By default, delegates to the {@link archive()} loop.
     */
    function tag() {
        thesis_loop::tag();
    }
    /**
     * Loop for custom taxonomy pages.
     *
     * Has no effect unless you have defined a custom taxonomy.
     *
     * By default, delegates to the {@link archive()} loop.
     */
    function tax() {
        thesis_loop::tax();
    }
    /**
     * Loop for author pages.
     *
     * By default, delegates to the {@link archive()} loop.
     */
    function author() {
        thesis_loop::author();
    }
    /**
     * Loop for year-level date archive pages.
     *
     * By default, delegates to the {@link archive()} loop.
     */
    function year() {
        thesis_loop::year();
    }
    /**
     * Loop for month-level date archive pages.
     *
     * By default, delegates to the {@link archive()} loop.
     */
    function month() {
        thesis_loop::month();
    }
    /**
     * Loop for day-level date archive pages.
     *
     * By default, delegates to the {@link archive()} loop.
     */
    function day() {
        thesis_loop::day();
    }
    /**
     * Loop for search results page.
     *
     * By default, delegates to the {@link archive()} loop IF THERE ARE RESULTS.
     * By default, just shows a search form if there are no results.
     *
     * A custom search loop needs to deal with both possibilities; see the
     * {@link thesis_loop::search()} for example of how to do so.
     */
    function search() {
        thesis_loop::search();
    }
    /**
     * Loop for the "404 Not Found" error page.
     * 
     * Runs when the URL requested could not be mapped to any page.
     */
    function fourohfour() {
        thesis_loop::fourohfour();
    }
    /**
     * Loop for page without any posts/pages (an empty query).
     *
     * Runs when the URL requested maps to a legitimate page, but there
     * is no post data to display. Should be rare.
     */
    function nothing() {
        thesis_loop::nothing();
    }
    /* PRIVATE HELPER METHODS */
    /**
     * Merge new query parameters with existing parameters.
     *
     * This preserves existing request parameters, for compatibility
     * with plugins, etc.
     *
     * New parameters overwrite existing parameters with same name.
     *
     * @access private
     * @param array $new_params Parameters for a new query via 
     *        {@link query_posts()} or a new {@link WP_Query}.
     * @global $wp_query is used to get the current request parameters.
     *
     * @return array The merged parameters array, ready for passing to 
     *               {@link WP_Query::query_posts()} or
     *               {@link WP_Query::get_posts()}.
     */
    private function preserve_query_params($new_params = array()) {
        global $wp_query;
        return(array_merge($wp_query->query, $new_params));
    }
    /**
     * Retrieve the current "paged" parameter from the request.
     *
     * This is used for "paging" through the query results. 
     * See {@link https://aldosoft.com/blog/2011/01/thesis-custom-loop-template/ 
     * for details.}
     *
     * This method deals with a WordPress idiosyncracy / inconsistency in the 
     * name of this parameter.
     *
     * @access private
     * @uses WP_Query::get_query_var()
     *
     * @return int The current paged parameter.
     */
    private function get_paged_param() {
        if(is_front_page()) {
            $paged = (get_query_var('page') ? get_query_var('page') : 1);
        }
        else {
            $paged = (get_query_var('paged') ? get_query_var('paged') : 1);
        }
        return($paged);
    }
}
$custom_looper = new my_looper;

About the Helper Methods

I’ve added two private methods that virtually every Custom Loop will find a way to make use of. (Lines 197-200 and 217-225.) These helpers simplify your loop code by factoring out dealing with some idiosyncrasies of WordPress request parameters.

The first helper makes preserving existing request parameters easier, and more complete:

class my_looper extends thesis_custom_loop {
    function home() {
        $new_args = array(
            'orderby' => 'title',
            'order' => 'ASC',
        );
        query_posts($this->preserve_query_params($new_args));
        thesis_loop::home();
    }
}
$custom_looper = new my_looper;

This loop is functionally (almost) identical to the first loop example in the Custom Loop API article. It changes the sort order of the home page, but otherwise leaves the formatting alone. At first blush it’s just a more complicated version of the earlier example, but let’s look at what’s different:

• Lines 4-7 define an array of query arguments, which will override existing request parameters. Recall from the earlier article that using an array is generally easier when you have more than one or two parameters to add.
• Line 8 is what’s interesting, instead of concatenating together pieces of a query string, I use the new helper method, preserve_query_params(). The cool thing about the helper is that it accesses the $wp_query global to extract all of the request parameters, not merely those that are in the query string. This is more likely to preserve compatibility with plugins, etc.
• Line 9, delegate to the built-in Thesis home() loop, just as I did before.

The preserve_query_params() method will generally be useful in any Custom Loop where you modify the existing query; it’s unnecessary in situations where you are creating a new query, unless that query needs to “copy” parameters from the default query.

The second helper method, get_paged_param(), is for use when you want to enable paging through the results of a new> query, that is, when you are adding a list of items that would not normally display on the URL requested. The portfolio page example in the Custom Loop API article is a good example of where this is useful. Here’s an abbreviated version for discussion:

function page() {
    if(is_page('portfolio')) {
        // Get request var to maintain paging through list of portfolio posts
        $paged = $this->get_paged_param();
        // Loop #1: Show the requested page's content
        while (have_posts()) { // Standard WordPress
            the_post(); // Standard WordPress
            // ... HTML output
        }
        wp_reset_query();
        // Loop #2: Add a list of portfolio posts
        $portfolio_query_args = array(
            'paged' => $paged,
            'post_type' => 'post',
            'post_status' => 'publish',
            'tag' => 'portfolio',
        );
        query_posts($portfolio_query_args);
        if(have_posts()) { while(have_posts()) {
            the_post();
            // ... HTML output
        }}
    }
    // else ...
}

The basic idea is that one page of this site is a portfolio, which will display a stylized list of posts which have been tagged as “portfolio”. The page itself contains static content to introduce the portfolio, so we’re adding a second query to get the portfolio items. The paging issue arises when we have more portfolio posts than will fit in the list (WordPress has a default of 10 here, it can be changed in Settings > Reading > Blog pages show at most).

If we want to be able to “page” backwards and see older portfolio items, we need to enable the “paging controls”, the “Previous Entries” and “Next Entries” links that appear at the bottom of the page in Thesis archive views. These links are auto-generated by Thesis and WordPress functions; all we need to do to enable them is to preserve the “paged” parameter that is part of the request, and feed it to the new query.

So, on line 4 we use the get_paged_param() helper method to grab that parameter. The helper deals with an inconsistency in WordPress, where the parameter is named one thing on most pages, and another on the front page.

Lines 7-11 handle the initial Loop, which is simply displaying the static page content. (And, obviously, line 9 hides a lot of the details; see the portfolio example for the full code.)

Line 14 starts our second Loop, and line 15 is where we add the $paged value to the parameters for the new query. This is the query that will return multiple results, potentially more than will display on one page, and which we want to page through. Adding the $paged parameter tells the query which section of the results to actually retrieve.

On line 20 we run the query, and lines 22-25 deal with looping through the results of the query and outputting the portfolio list HTML for each portfolio post.

Now, there’s additional complexity here that might not be apparent. The WordPress query_posts() documentation explicitly states that you should only use query_posts() to modify the main page Loop. That’s a good rule of thumb, and if you choose to not follow it, you should have a good reason.

In this case, the reason is pagination. If the Loop above were to use get_posts() or create a new WP_Query object manually, it would certainly retrieve the portfolio posts just as well as using query_posts(), without making the code appreciably more complicated.

But the automatic display of the paging controls will only happen for the query results last returned by query_posts(). If the above loop did not use query_posts(), the default Thesis pagination wouldn’t happen, and I would have to write my own pagination code, which would add a lot more code to the loop. This way is easier.

How does it work? WordPress pagination runs off the global $wp_query variable. When you leave your loop (or any hook affecting the “main” query), you need to leave $wp_query holding the results you want paginated and with a valid/preserved $paged parameter. If you do that, pagination runs automatically.

Anyway, to at least wrap up a long story, hopefully this starter template and the helper methods will make your Custom Loops easier to write. Happy looping!