From iThemes Codex
Revision as of 20:25, 9 September 2011 by Bes (talk | contribs) (Added LoopBuddy FAQ: section, LoopBuddy does not work on static Posts page: faq and fixed Additional Resources: links ordering)
Jump to: navigation, search

Release date: July 19, 2011

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.

LoopBuddy Query Editor

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...

Query Editor Options

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.

LoopBuddy Layout Editor

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.

Layout Editor Options

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.

General Settings


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']

LoopBuddy Full 1 Hour Webinar

Learn the ins and outs of LoopBuddy with the following 1 hour Webinar, made by our very own Webdesign.com

EmbedVideo was given an illegal value for the alignment parameter "363". Valid values are "left", "center", or "right".

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">
		/* 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' );
<?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 of TwentyTen Using the Loop Standard

Here's an example TwentyTen Loop converted to using the Loop Standard

	<?php if ( have_posts() ) while ( have_posts() ) : the_post(); ?>

			<div class="loop-content">
				<div id="nav-above" class="navigation loop-utility loop-utility-above">
					<div class="nav-previous"><?php previous_post_link( '%link', '<span class="meta-nav">' . _x( '←', 'Previous post link', 'twentyten' ) . '</span> %title' ); ?></div>
					<div class="nav-next"><?php next_post_link( '%link', '%title <span class="meta-nav">' . _x( '→', 'Next post link', 'twentyten' ) . '</span>' ); ?></div>
				</div><!-- #nav-above -->

				<div id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
					<div class="entry-header">
						<h1 class="entry-title"><?php the_title(); ?></h1>
						<div class="entry-meta">
							<?php twentyten_posted_on(); ?>
						</div><!-- .entry-meta -->
					</div><!-- .entry-header-->
					<div class="entry-content">
						<?php the_content(); ?>
						<?php wp_link_pages( array( 'before' => '<div class="page-link">' . __( 'Pages:', 'twentyten' ), 'after' => '</div>' ) ); ?>
					</div><!-- .entry-content -->
					<div class="entry-footer">
<?php if ( get_the_author_meta( 'description' ) ) : // If a user has filled out their description, show a bio on their entries  ?>
						<div id="entry-author-info" class="entry-meta entry-meta-below">
							<div id="author-avatar">
								<?php echo get_avatar( get_the_author_meta( 'user_email' ), apply_filters( 'twentyten_author_bio_avatar_size', 60 ) ); ?>
							</div><!-- #author-avatar -->
							<div id="author-description">
								<h2><?php printf( esc_attr__( 'About %s', 'twentyten' ), get_the_author() ); ?></h2>
								<?php the_author_meta( 'description' ); ?>
								<div id="author-link">
									<a href="<?php echo get_author_posts_url( get_the_author_meta( 'ID' ) ); ?>">
										<?php printf( __( 'View all posts by %s <span class="meta-nav">→</span>', 'twentyten' ), get_the_author() ); ?>
								</div><!-- #author-link	-->
							</div><!-- #author-description -->
						</div><!-- #entry-author-info -->
<?php endif; ?>
						<div class="entry-utility">
							<?php twentyten_posted_in(); ?>
							<?php edit_post_link( __( 'Edit', 'twentyten' ), '<span class="edit-link">', '</span>' ); ?>
						</div><!-- .entry-utility -->
					</div><!-- .entry-footer-->
				</div><!-- #post-## -->
				<div class="loop-footer">
					<div id="nav-below" class="navigation loop-utility loop-utility-below">
						<div class="nav-previous"><?php previous_post_link( '%link', '<span class="meta-nav">' . _x( '←', 'Previous post link', 'twentyten' ) . '</span> %title' ); ?></div>
						<div class="nav-next"><?php next_post_link( '%link', '%title <span class="meta-nav">' . _x( '→', 'Next post link', 'twentyten' ) . '</span>' ); ?></div>
					</div><!-- #nav-below -->
				</div><!-- .loop-footer-->

				<?php comments_template( '', true ); ?>
			</div><!-- .loop-content-->

<?php endwhile; // end of the loop. ?>

After updating the template files, go through the theme's style.css file in order to update class references to match the new ones. Here are some basic replacements to make:

  • .page-title → .loop-title
  • .title → .entry-header
  • .post-title [h1, h2, h3, etc] (any instance of .post-title followed by a header tag) → .entry-title
  • .post-title → .entry-title
  • .post-meta → .entry-meta
  • .post-content → .entry-content
  • .meta-top → .entry-header
  • .meta-bottom → .entry-footer
  • .post → .hentry
  • .paging → .loop-utility

Showing LoopBuddy Theme Support

After you've modified your theme's loops, show LoopBuddy that your theme supports it by adding in the following line to your theme's functions.php file:

// Add support for the Loop Standard
add_theme_support( 'loop-standard' );

Adding the Dynamic Loop Function to Your Theme

The Dynamic Loop function must be added to your theme's function.php file. This is achieved by adding the following code to the end of the function.php file:

// Add dynamic_loop function for LoopBuddy

Copyright 2011 iThemes (email: support@ithemes.com)

Written by Chris Jean
Version 0.0.1

Version History
	0.0.1 - 2011-02-28 - Chris Jean
		Initial version

if ( ! function_exists( 'dynamic_loop' ) ) {
	function dynamic_loop() {
		global $dynamic_loop_handlers;
		if ( empty( $dynamic_loop_handlers ) || ! is_array( $dynamic_loop_handlers ) )
			return false;
		ksort( $dynamic_loop_handlers );
		foreach ( (array) $dynamic_loop_handlers as $handlers ) {
			foreach ( (array) $handlers as $function ) {
				if ( is_callable( $function ) && ( false != call_user_func( $function ) ) ) {
					return true;
		return false;

if ( ! function_exists( 'register_dynamic_loop_handler' ) ) {
	function register_dynamic_loop_handler( $function, $priority = 10 ) {
		global $dynamic_loop_handlers;

		if ( ! is_numeric( $priority ) )
			$priority = 10;
		if ( ! isset( $dynamic_loop_handlers ) || ! is_array( $dynamic_loop_handlers ) )
			$dynamic_loop_handlers = array();
		if ( ! isset( $dynamic_loop_handlers[$priority] ) || ! is_array( $dynamic_loop_handlers[$priority] ) )
			$dynamic_loop_handlers[$priority] = array();
		$dynamic_loop_handlers[$priority][] = $function;

LoopBuddy Downloads

Example TwentyEleven Theme

Here's an example TwentyEleven theme that has been modified to be compatible with LoopBuddy.

TwentyEleven Loop Standard

Example Layout Tag

Check out the LoopBuddy Marquee Plugin: LoopBuddy Marquee as an example of creating custom tags.

Example Queries/Layouts

Please see below for a ZIP file of some sample layouts and queries that can be imported.

LoopBuddy Export File


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.

To create the custom tag, you must use the following hooks.

Creating a new Custom Tag

	add_filter( 'pb_loopbuddy_custom_tags', 'my_custom_tag_add' );
	function my_custom_tag_add( $custom_tags ) {
		//Always return $custom_tags
		$custom_tags[ 'start_wrap' ] = array( 
			'My Tag Label',
				'wrap' => 'div',
				'custom_class' => 'default class'
		return $custom_tags;	
	} //end my_custom_tag_add
	//Start off with the tag name, give the tag a label, and pass it which items it supports (all should ideally contain the 'wrap' and 'custom_class' items

Here are some built in tag items that you can choose from:

  • link_text
  • custom_url
  • custom_class
  • link_title
  • before_text
  • after_text
  • meta_key
  • max_width
  • max_height
  • shortcode
  • author_link_destination
  • user_profile
  • permalink
  • attachment_link_display
  • separator
  • text
  • date_format
  • comment_number_zero
  • comment_number_one
  • comment_number_more
  • post_date
  • bloginfo
  • content_more
  • url_display
  • image_size

Creating a new custom tag item

add_filter( 'pb_loopbuddy_tag_items', 'my_custom_item_add' );
function my_custom_item_add( $loopbuddy_items ) {
	//Always return $loopbuddy_items
	$loopbuddy_items[ 'my_custom_item' ] = array( 
		'function' => 'callback_function',
		'args' => array(
			'label' => __( 'Link Text', 'LION' ),
			'tip' => __( 'Optional text for link.  Leave blank to use link as the text.', 'LION' ),
			'options' => array( 'option1', 'option2' )
	return $loopbuddy_items;
} //end my_custom_item_add

/* $settings are the arguments passed for the tag item and looks like this 
 [label] => HTML Wrapper
    [tip] => Choose which HTML element to wrap around the item
    [options] => Array
            [0] => none
            [1] => span
            [2] => div
            [3] => p
            [4] => h1
            [5] => h2
            [6] => h3
            [7] => h4
            [8] => h5
            [9] => h6

    [key] => wrap
    [settings] => Array
            [image_size] => thumbnail
            [max_width] => 
            [max_height] => 
            [wrap] => p
            [before_text] => 
            [after_text] => 
            [custom_url] => 
            [custom_class] => attachment
            [tag] => wp_get_attachment_image

function callback_function( $settings ) {
	$defaults = array(
		'key' => '',
		'label' => '',
		'tip' => false,
		'settings' => array(),
		'options' => array()
	extract( wp_parse_args( $settings, $defaults ) );
	//Output HTML for the item
} //end callback_function


Callback function for displaying the tag - pb_loopbuddy_tag_callback-{tag_name}

/*$settings contains the tag items and the tag item's value
		    [image_size] => thumbnail
		    [max_width] => 
		    [max_height] => 
		    [wrap] => p
		    [before_text] => 
		    [after_text] => 
		    [custom_url] => 
		    [custom_class] => attachment
		    [tag] => wp_get_attachment_image
//Add header code
add_action( 'pb_loopbuddy_tag_header-mytagname', 'my_custom_tag_header' );
function my_custom_tag_header( $settings ) {
	echo "my header, notes, or other code";
	//Render your tag based on its settings
} //end my_custom_tag_header

//Add footer code
add_action( 'pb_loopbuddy_tag_footer-mytagname', 'my_custom_tag_footer' );
function my_custom_tag_footer( $settings ) {
	echo "my footer, notes, or other code";
	//Render your tag based on its settings
} //end my_custom_tag_header

add_filter( 'pb_loopbuddy_tag_supports-mytagname', 'my_custom_tag_supports' );
//Return an array of what tag items the tag supports
function my_custom_tag_supports( $support_tag_items ) {
	return array( 'wrap', 'link_text', 'before_text', 'after_text', 'custom_class' );
	//Render your tag based on its settings
} //end my_custom_tag_supports

Rendering the Tag on the Front-end - pb_loopbuddy_render-{tag_name}

add_filter( 'pb_loopbuddy_render-mytagname', 'mytagname_frontend', 10, 2 );
function mytagname_frontend( $post_object, $tag_items ) {
	/* $tag_items look like this
    [wrap] => none
    [link_text] => Edit Post
    [before_text] => 
    [after_text] => 
    [custom_url] => 
    [custom_class] => 
    [tag] => edit_post_link
	$return = false; //Populate the $return variable
	$return = pluginbuddy_loopbuddy_render_slotitems::get_output( $return, $post_object, $tag_items, true ); //The last argument is skip_before text 
	return $return;
} //end mytagname_frontend

Ignoring Post Types in the Layout Editor

There will be certain post types that are public and have a public user interface, but the user would still not like to be able to configure override settings in the LoopBuddy Settings page.

A plugin author can use the following hook to remove these post types:

	add_filter( 'pb_loopbuddy_exclude_post_types', 'myplugin_exclude_post_types' );
	function myplugin_exclude_post_types( $post_types_to_exclude ) {
		$post_types_to_exclude[] = 'my_custom_post_type';
		return $post_types_to_exclude;

LoopBuddy FAQ

Here are some frequently asked or encountered LoopBuddy questions and setups, and their answers.

LoopBuddy does not work on static Posts page

  • LoopBuddy will NOT work on pages set as Static Posts Page in WordPress --> Settings --> Reading --> Front Page Displays --> Posts Page section. There is a good reason for it and a great workaround.
    • Reason
      • The Reading Screen in the WordPress Settings Settings --> Reading Screen Settings is necessary when you want to tell WordPress that your blog content doesn't reside on the home page.
      • For example, you have selected a Front Page, which will tell WordPress, "Use this page instead of showing a default blog layout."
      • Since there is technically no longer a blog layout, WordPress wants to know, "Where can I find your blog content?"
      • This is how WordPress works, and not a LoopBuddy bug. There is a great flawless way to get exactly what you want with the below workarounds, though.
    • Workaround (any one of this will work - we recommend the PREFERRED LoopBuddy way to do it!)
      • Not have a section on your site with your blog content (readers will only be able to access your posts via category and date archives).
      • Create a page to point WordPress to, and WordPress will take care of the rest and display the appropriate blog content.
      • PREFERRED: With LoopBuddy, however, you don't have to specify a "Blog" section in WordPress.
        • You can create a regular page.
        • Allow LoopBuddy to create a blog section for you either via LoopBuddy --> Settings option OR by choosing the LoopBuddy options in the Post/Page Editor page for the page you just created.
        • WordPress doesn't need to know about it in this particular case, and it won't hurt your site in the least. You do NOT have to change the WordPress --> Settings --> Reading --> Front Page Displays --> Posts Page settings for this option to work perfectly.
  • Threads and pages with more detailed info of the setup and info related to the above exact solutions

Additional Resources

  1. Purchase BackupBuddy
  2. PluginBuddy Tutorials
  3. PluginBuddy.com
  4. Support Forums