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 lists pages, you can export/import the items so you can use the same Queries/Layouts on a different site.

This is the same page as where you create new Queries or Layouts.

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">
<?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

You can import any Query or Layout into LoopBuddy via the Import/Export section.

LoopBuddy Query

The LoopBuddy Query is where you create Queries, which in turn create and produce the Loops you want in WordPress. From showing certain posts to the number of posts, categories, posts with specific meta values and more, the LoopBuddy Query area is where you specify exactly what should be shown, and exactly what should not be shown, in a LoopBuddy output.

Advanced Meta Queries

With LoopBuddy 1.2, LoopBuddy Queries now allow you to perform some very powerful advanced Meta queries. Here is a video explaining and giving some examples of the advanced meta queries:

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

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.

Shortcodes

Shortcodes basically allow almost any plugin or custom code to be plugged in anywhere in WordPress.

LoopBuddy supports shortcodes, allowing you to put any shortcode, whether from a plugin or your own, into any place in LoopBuddy Layout, including the Pre-Loop Text / HTML, Post-Loop Text / HTML and No Results Text / HTML sections. This probably makes the already powerful LoopBuddy the only most powerful way to control all your content, loops and display on your site.

Current Limitations (LoopBuddy 1.2.x and earlier)

Loopbuddy does not process shortcodes with parameters, such as [pb_slideshow group="2"]. There is a workaround, following are examples on how to add such a shortcode to the layout for each post, and an example on how to add this to the Pre-Loop or Post-Loop fields (ironically, using another shortcode). The methods described in the next two examples will work for all shortcodes that use parameters, e.g. DisplayBuddy plugins, Gravity forms etc.

Add a Shortcode with parameters to a layout

Add the shortcode (in this example, we will use [pb_slideshow group="2"], to show a slideshow) to a custom field in your post. In this example, the custom field is named post-slideshow.

Then, add the following code at the end of your functions.php file (but before the closing ?>, if any).

Usage

Drag a shortcode into the LoopBuddy layout of your post, and add the [insert-slideshow-in-post] shortcode. The function will retrieve the contents of the custom field (post-slideshow) and insert it where defined in the layout.

Add a Shortcode with parameters in the Pre-loop or Post-loop fields

If you want to add a shortcode for the entire page (or if you want to add the same shortcode to each post layout) (in this example, [pb_videoshowcase group="0"], to show a videoshowcase group), add the following code at the end of your functions.php file (but before the closing ?>, if any).

Code

Usage

You can then add the shortcode [my-videos] to the LoopBuddy layout editor. Note that the name of the shortcode can be anything you want, as long as it matches the code in your functions.php.

Show Category/Taxonomy Description on NON-Archive pages via Shortcode

Category Descriptions are a little more sophisticated than other post related variables because if there is more than one category being used, then it will be hard for WordPress to display ALL descriptions nicely OR one category (which one?).

Outside of archive pages, to display Category Descriptions (or any taxonomy description) you have to do the following:

1 : Put the following anywhere (usually near the end of the file) in your theme's custom functions.php file (it creates a shortcode you'll use to display the description of a Category or any Taxonomy):

Show Custom Page Title for Same LoopBuddy Layout on Different Pages via Shortcode

One awesome example of using Shortcodes with LoopBuddy is to show a custom page title, along with any LoopBuddy Layout content, where different pages use the same LoopBuddy Layout. Our awesome LoopBuddy customer Bruce provided the following info to help you all with that:

1 : Put the following anywhere (usually near the end of the file) in your theme's custom functions.php file:

Add previous and next post links on single post pages

If you want to show a Previous or Next Post link on a single post page, you can do so using a shortcode. Add the following code at the end of your functions.php file (but before the closing ?>, if any).

Customize the Appearance

Additional documentation

Add navigation from the wp_page navi plugin

LoopBuddy includes support for the wp_pagenavi plugin. Loopbuddy will insert the navigation at the bottom of the page, if you have installed and activated the plugin, and if you have ticked "Enable Paging" in the Query editor. However, if you want more control over when and where the wp_pagenavi navigation will appear, you can do so using a shortcode. Note that if you want to use a shortcode to insert the navigation, you should untick the "Enable Paging" setting, otherwise, it will show up twice. Add the following code at the end of your functions.php file (but before the closing ?>, if any).

Code

Usage

Insert the shortcode [insert-page-navi] in your LoopBuddy layout where you want the wp-pagenavi pagination to appear. Generally, this would be in either (or both) the "Pre-Loop Text / HTML" or the "Post-Loop Text / HTML", since we usually don't want the pagination to appear in every post in a list of posts.

Add a link to post comments in the post list (archive page)

If you want to add a link to the post comments to your (archive) layout, add the following code at the end of your functions.php file (but before the closing ?>, if any).

Usage

The example shows three ways to return the content. Only one should be used.

The first example assumes that the contents of the custom field my_custom_field_image is an image URL, so it will return the image url in html <img> tags, so that the image will be displayed as an image, and not the url of that image.

The second example retrieves the value of the custom field my_custom_field_name and will return that value. Insert the shortcode [insert-custom-field] in your LoopBuddy layout where you want the comment form to appear.

You can even add a shortcode to the custom field, example 3 shows how to return the results of a shortcode my_shortcode and insert that in your layout. The custom field contents should include the shortcode brackets, so [my_shortcode].

Additional documentation

External Plugins Compatibility

LoopBuddy is one of those rare plugins which can play well with many external plugins. However, any external plugin compatibility is NOT guaranteed in any manner, since external plugins are not covered nor supported by PluginBuddy in any manner or fashion.

If there is a problem when any other plugin is used with LoopBuddy, it does not mean there is a bug in LoopBuddy. First you should check if there is a problem in the other plugin (since LoopBuddy already currently works without any issues in each and every aspect of its publicized features). Then you have to see if the problem exists when the other plugin is de-activated and LoopBuddy is kept activated. Only after such steps and more analysis can we at PluginBuddy devote any time or resources to see whether or not there is something in LoopBuddy that can be fixed, enhanced or improved to make it work better with the external plugin in question, if that external plugin is not the source of the problem.

Custom Post Types

At this time, Custom Post Types UI is the only supported plugin in LoopBuddy for creating custom post types. We recommend you try and use that to create post types.

Otherwise, you should add custom post types directly to your functions.php file in your current theme.

Customize Excerpts

LoopBuddy FAQ

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

Sort Custom Field Values by Meta Value (Character or Numeric)

Custom Field values can be sorted by meta value (character or numeric).

Only ONE meta item can be used to sort at one time.

Using multiple meta items will assume you would like an advanced meta query, and sorting will be ignored in such a case. This is a WordPress limitation.

Sort Custom Field Values via the following steps (assuming you already have several posts with the same custom field):

1 : Change the Order By parameter to either "Meta Value" or "Numeric Meta Value".

2 : Go to Post Meta Parameters and click "Add Meta".

3 : Set the Meta Key and Meta Values you would like to search for and sort by.

4 : Save the query.

5 : Assign the query to a post or section and observe the results.

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

Make a Custom Field (or almost anything) Clickable

With the power of different tags in LoopBuddy Layout, you can make almost anything clickable without editing a single file. This is extremely useful when you want to make something like a Custom Field, which is text by default, clickable automatically in any or every loop.

Steps to perform in your LoopBuddy Layout:

1 : Start with a Text tag (first Text tag) which has the content: <a href="

2 : Next comes anything, including a Custom Field tag. This is the link.

3 : Now comes another Text tag (second Text tag) which has the content: ">

4 : Now comes anything to show the link. It can be the same Custom Field tag again as #2 above, another custom field, or any text or image you wish.

Change OLDER POSTS and NEWER POSTS pagination text

You can change the "Older posts" and "Newer posts" text to say anything by editing those words in your wp-content/plugins/loopbuddy/loopbuddy.php file on lines 1336 and 1337. They will look like the following:

Wrap the original loop with a conditional tag

This tag only uses the original loop that comes with your WordPress theme if the dynamic_loop (LoopBuddy) isn't being used.

<?php if (!dynamic_loop()) : ?>
ORIGINAL LOOP
<?php endif; ?>

Other Notes abour Conversions

You can extract a loop and put it into a separate file and then call that original loop (inside the dynamic_loop() conditional tag) by using the get_template_part() WordPress function.

Video Tutorials and Tips

These different video tutorials and tips can help you figure out more things about LoopBuddy. Remember, these videos show LoopBuddy and related things that were the most recent/updated as of the date of that video. Things may have changed in actual LoopBuddy since then.