How To: Create a Sub-Loop in Thesis

This is part 3 of a never-ending-series about advanced ninja Thesis coding. You can get up-to-speed by reading, How To: Create a Custom Page Template and How To: Create Additional Page Templates.

The WordPress Loop

You’ve read about The WordPress Loop in other tutorials in other Themes; how you can “add/subtract post meta-data, tags, etc…” all you have to do is “edit ____ in the WordPress Loop” blah blah blah.

Not with Thesis you can’t.

Rule #1, never edit core Thesis files. It’s not that you’ll break Thesis, but you will however, take away one of the biggest selling points: “Thesis is future proof”. Alas, we still have our secret Thesis weapons:

custom.css? Check.
custom_functions.php? Check.
Custom Page Templates? Check.
Greg Rickaby’s awesome tutorials? Check.

The Everyday Scenario

Client XYZ want’s to feature one category of posts on the homepage. The problem is, the client also wants a jQuery slider and no sidebars. Easy enough, just create a Custom Page Template and then create a custom sub-loop in home.php. (For a great example, check out this conversion I did using a custom sub-loop. Look at the “News” box on the homepage).

The Query

Once you’ve created home.php and attached it to Thesis, we need to do three things to make this all work:

1. Specify a category
2. Query the database
3. Print the post data

<?php
$sub_loop_1 = new WP_Query("cat=1&showposts=3");
while ($sub_loop_1->have_posts()) : $sub_loop_1->the_post();
$category_link = get_category_link('1');
?>

In the code above, I said “Hello database, I’d like to pull 3 posts from Category ID #1, and while you’re in there I’ll take the permalink to Category #1 as well…”

This is exactly the same as The WordPress Loop. When you create a sub-loop, you get to pull ALL the same post data as the regular WordPress Loop, you’re just doing it outside, thus it’s called the “sub-loop”. Now, let’s start printing the data with what WordPress calls, “Template Tags”. Template Tags are just variables that become available to you when you query the database. Here is the official list.

For example:

<?php the_title(); ?> will show us the Post Title.

<?php the_permalink(); ?> will gives us the Post’s Permalink

<?php the_exceprt(); ?> will show us the Excerpt

The “Teaser” Box

Let’s put this code into a real world situation. Using CSS and some of those “Template Tags” you can create your own “Teaser” box.

<div id="news"> <-- Start the "Teaser" box

<div class="headline"> <-- Start the Post Title
   <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
</div>

<div class="thumb"> <-- Start the Post Thumbnail
  <?php the_post_thumbnail( array(100,100) ); ?>
</div>

<div class="excerpt"> <-- Start the Post Excerpt
  <p><?php the_excerpt(); ?>...<br />
    <a href="<?php echo $category_link; ?>"><?php $category = get_the_category(); echo $category[0]->cat_name; ?><?php $category = get_the_category(); echo $category[1]->cat_name; ?></a> | <a href="<?php the_permalink(); ?>"><?php echo thesis_teaser_link_text(); ?></a> | <a href="<?php the_permalink(); ?>#respond">Comments { <?php comments_number('0','1','%'); ?> }</a>
  </p>
</div>

</div> <-- End the "Teaser" box
<?php endwhile; ?> <-- End the sub-loop

Here is how all that works. I created a new <DIV ID> to encompass the entire “teaser”. Then I created a new <DIV CLASS> for the headline, post thumbnail, excerpt, permalink, and comment data. If you slow down and actually look at the PHP code you will see how easy it is. WordPress gives us all the tools (variables) we need with Template Tags.

I want to take a sec to talk about pulling out the Thumbnail. Since WP 2.9.0, the programmers of WordPress created awesome new functionality that has not yet been made available in Thesis (at press time, Thesis 1.6). So, in order to pull out thumbnails; YOU MUST add this line of code ANYWHERE in custom_functions.php: add_theme_support( 'post-thumbnails' ); You can learn all about the new WP 2.9+ Thumbnail features by reading Justin Adocks blog post.

The Final Output

<?php
$sub_loop_1 = new WP_Query("cat=1&showposts=3");
while ($sub_loop_1->have_posts()) : $sub_loop_1->the_post();
$category_link = get_category_link('1');
?>
<div id="news">

<div>
   <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
</div>
<div>
<?php the_post_thumbnail( array(100,100) ); ?>
</div>

<div>
<p><?php the_excerpt(); ?>...<br />
<a href="<?php echo $category_link; ?>"><?php $category = get_the_category(); echo $category[0]->cat_name; ?><?php $category = get_the_category(); echo $category[1]->cat_name; ?></a> | <a href="<?php the_permalink(); ?>"><?php echo thesis_teaser_link_text(); ?></a> | <a href="<?php the_permalink(); ?>#respond">Comments { <?php comments_number('0','1','%'); ?> }</a>
</p>
</div>

</div>
<?php endwhile; ?>

See it in action: here, here, and here, (yeah I do this a lot)

Closing Statement

When people call me for PSD Conversions they often comment, “We’re not sure we can do this with Thesis…” and it usually involves a custom page template and a sub-loop. Learning these skills will not only help you as a programmer, but being a hero too.

You see, when a client throws up a brick-wall-deal-breaker about making Thesis not LOOK LIKE Thesis, you can say with confidence, “Bring it on!” And that is all.