LoopBuddy Overview

LoopBuddy is a tool that overwrites a WordPress Loop using a combination of a custom query and a custom Loop layout. You can also create your own Loops using the LoopBuddy shortcode and LoopBuddy widget.

Query Editor

If LoopBuddy was a body, the Query Editor would be the brain, with the Layout Editor being the outside bodily appearance.

With the Query Editor, you can create Query Groups. Each Query Group defines what data a WordPress Loop is supposed to pull in.

With the Query Editor, you can define:

Which posts to gather

Whether pagination or comments are enabled

Whether to use the default post ID (if on a single post or page)

and much, much more...

Layout Editor

The Layout Editor controls how a particular WordPress Loop is supposed to be structured. At the heart of the Layout Editor is Layout Tags. There are several Layout Tags built-in, but you can use the LoopBuddy Hooks to create your own custom Layout Tag and Layout Tag Items.

With the Layout Editor, simply drag Layout Tags into the appropriate area. If you create a new Layout, there are several default tags that are added automatically.

Global Settings

The Global LoopBuddy Settings allow you to globally override a default WordPress Loop. If your theme doesn't support the Loop Standard, you'll see an error message at the top.

If your theme does support the Loop Standard, you can use the options to override the default WordPress Loops in various areas of the site.

Although LoopBuddy attempts to work without a custom Query, it is highly advisable to use a custom Query and Layout.

Import/Export

Within the Query and Layout editors, you can export/import the items so you can use the same Queries/Layouts on a different site.

LoopBuddy Widget

You can use the LoopBuddy Widget to display a LoopBuddy Query/Layout in any widgetized area of a site. Please note that you must have a Query AND a Layout for the widget to work.

LoopBuddy Shortcode

The LoopBuddy shortcode takes two attributes: a Query ID and a Layout ID. Please note that you must have a Query AND a Layout for the widget to work.

Simply insert the shortcode into a post or page:

[loopbuddy query_id='0' layout_id='0']

The Loop Standard

The Loop Standard divides a loop into two main concepts: a loop and one or more entries.

Both a loop and an entry have three sections: a header, a content section, and a footer. The header contains title information, any meta information, and any necessary navigation links. The content section contains the content relevant to that loop or entry. The footer section is a place to hold additional or duplicate meta information and navigation links.

The Loop Explained

The content of a loop is a bit more complex than the content of an entry as a loop's content contains the entries. To better visualize this, here is the basic structure described so far:

Loop

Header

title

navigation

meta

Content

Entry

Header

title

navigation

meta

Content

Footer

navigation

meta

Additional entries...

Footer

navigation

meta

The idea is that each section is broken out in a repeatable pattern. This makes styling easier as any content that follows this form can be styled without having to first read through the code in order to understand the structure.

You may notice that there are titles, navigation, and meta for both the entries and the loop. This is because some titles, navigation, and meta are relevant to the loop (the title archive, navigating between pages of posts, or information about an author in an author archive) while other titles, navigation, and meta are relevant to the entry (the blog post's title, navigating through a page split into multiple pages, or a blog post's category information). The rule of thumb is that if the information is specific to an individual post's, page's, etc content, it is an entry-level structure; otherwise, it is a loop-level structure.

Each of these sections have a specific class in the Loop Standard. Here is the structure again with the classes replacing the names:

loop

loop-header

loop-title

loop-utility

loop-meta

loop-content

hentry

entry-header

entry-title

entry-utility

entry-meta

entry-content

entry-footer

entry-utility

entry-meta

hentry...

loop-footer

loop-utility

loop-meta

Notice the "hentry" class. This looks odd but is actually generated by WordPress internally. It is produced by the post_class() function that is in 2010 and 2011 theme template files. So when you see "hentry", know that this is simply the div that looks like :

<div <?php post_class(); ?>></div>

Here is the standard loop in practice:

loop

loop-header

loop-title (page-title)

loop-content

hentry

entry-header (title)

entry-title (post-title)

entry-meta (post-meta)

entry-meta date (date)

entry-content (post-content)

entry-footer (meta-bottom)

entry-meta alignright (alignright)

entry-meta alignleft (meta-bottom-left)

hentry...

loop-footer

loop-utility (paging)

Not all the elements from above structure examples were used since not all were needed. In the end, only three elements had to be added. The rest of the changes were simply modifying or adding classes to conform to the Loop Standard structure. For some elements, such as "date", the "date" class remained while also getting the "entry-meta" class. This makes it clear what type of structure it is while still giving the additional meaning of it being a container for the date.

Modifying a Theme to Use LoopBuddy

Here's an example of TwentyTen's index.php file before it begins loading the various templates:

<?php if ( ! dynamic_loop() ) : ?>
<div class="loop">
<?php
/* Run the loop to output the posts.
* If you want to overload this in a child theme then include a file
* called loop-index.php and that will be used instead.
*/
get_template_part( 'loop', 'index' );
?>
</div>
<?php endif; ?>

When dynamic_loop() is executed, LoopBuddy searches to see if this particular loop should be overridden. If not, the normal loop executes. If so, then LoopBuddy overwrites the content of the loop with LoopBuddy content.

Example Queries/Layouts

Hooks

LoopBuddy allows you to create custom tags for the Layout editor. This is advanced functionality, so please don't attempt these steps if you are not intimately familiar with PHP and how LoopBuddy operates.