LoopBuddy

(Difference between revisions)
Jump to: navigation, search
(Hooks)
(Change OLDER POSTS and NEWER POSTS pagination text)
(43 intermediate revisions by 4 users not shown)
Line 1: Line 1:
'''Release date:''' July 19, 2011
 
 
 
 
 
==LoopBuddy Overview==
 
==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.
 
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===
 
===Query Editor===
Line 23: Line 20:
  
 
[[File:Query_editor_options.png|400px|border|Query Editor Options]]
 
[[File:Query_editor_options.png|400px|border|Query Editor Options]]
 +
  
 
===Layout Editor===
 
===Layout Editor===
Line 33: Line 31:
  
 
[[File:Layout_editor_options.png|500px|border|Layout Editor Options]]
 
[[File:Layout_editor_options.png|500px|border|Layout Editor Options]]
 +
  
 
===Global Settings===
 
===Global Settings===
Line 43: Line 42:
  
 
[[File:Loopbuddy_settings.png|500px|border|General Settings]]
 
[[File:Loopbuddy_settings.png|500px|border|General Settings]]
 +
  
 
===Import/Export===
 
===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.
+
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===
 
===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.
 
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===
 
===LoopBuddy Shortcode===
Line 61: Line 65:
 
[loopbuddy query_id='0' layout_id='0']
 
[loopbuddy query_id='0' layout_id='0']
 
</pre>
 
</pre>
 +
 +
 +
===LoopBuddy Full 1 Hour Webinar===
 +
 +
Learn the ins and outs of LoopBuddy with the following 1 hour Webinar, made by our very own [http://www.training.ithemes.com Webdesign.com]
 +
{{#ev:vimeo|26482158|580|363}}
 +
  
 
==The Loop Standard==
 
==The Loop Standard==
 +
 
The Loop Standard divides a loop into two main concepts: a loop and one or more entries.
 
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.
 
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 Loop Explained===
Line 142: Line 155:
 
 
 
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.
 
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===
 
===Modifying a Theme to Use LoopBuddy===
Line 162: Line 176:
  
 
When <code>dynamic_loop()</code> 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.
 
When <code>dynamic_loop()</code> 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===
 
===Example of TwentyTen Using the Loop Standard===
 +
 
Here's an example TwentyTen Loop converted to using the Loop Standard
 
Here's an example TwentyTen Loop converted to using the Loop Standard
 
 
Line 237: Line 253:
 
* .post → .hentry
 
* .post → .hentry
 
* .paging → .loop-utility
 
* .paging → .loop-utility
 +
  
 
===Showing LoopBuddy Theme Support===
 
===Showing LoopBuddy Theme Support===
Line 246: Line 263:
 
add_theme_support( 'loop-standard' );
 
add_theme_support( 'loop-standard' );
 
</pre>
 
</pre>
 +
  
 
===Adding the Dynamic Loop Function to Your Theme===
 
===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:
+
 
 +
The Dynamic Loop function must be added to your theme's functions.php file. This is achieved by adding the following code to the end of the function.php file:
  
 
<pre class='brush:php'>
 
<pre class='brush:php'>
Line 306: Line 325:
  
 
</pre>
 
</pre>
 +
  
 
==LoopBuddy Downloads==
 
==LoopBuddy Downloads==
 +
  
 
===Example TwentyEleven Theme===
 
===Example TwentyEleven Theme===
Line 314: Line 335:
  
 
[[Media:twentyeleven-loopstandard.zip|TwentyEleven Loop Standard]]
 
[[Media:twentyeleven-loopstandard.zip|TwentyEleven Loop Standard]]
 +
  
 
===Example Layout Tag===
 
===Example Layout Tag===
  
 
Check out the LoopBuddy Marquee Plugin: [[Media:Loopbuddy_marquee.zip|LoopBuddy Marquee]] as an example of creating custom tags.
 
Check out the LoopBuddy Marquee Plugin: [[Media:Loopbuddy_marquee.zip|LoopBuddy Marquee]] as an example of creating custom tags.
 +
  
 
===Example Queries/Layouts===
 
===Example Queries/Layouts===
Line 324: Line 347:
  
 
[[Media:Loopbuddy_export.zip|LoopBuddy Export File]]
 
[[Media:Loopbuddy_export.zip|LoopBuddy Export File]]
 +
 +
You can import any Query or Layout into LoopBuddy via the [[#Import/Export|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:
 +
 +
{{#ev:youtube|4snQn7PDylE|580|363}}
 +
*[http://pluginbuddy.com/loopbuddy-1-2-released/ Blog Post announcing Advanced Meta Queries in LoopBuddy 1.2]
 +
 +
 +
===Advanced Taxonomy Queries===
 +
 +
With LoopBuddy 1.2, LoopBuddy Queries now allow you to perform some very powerful advanced Taxonomy queries. Here is a video explaining and giving some examples of the advanced Taxonomy queries:
 +
 +
{{#ev:youtube|ta0GZA5jz9g|580|363}}
 +
*[http://pluginbuddy.com/loopbuddy-1-2-released/ Blog Post announcing Advanced Taxonomy Queries in LoopBuddy 1.2]
 +
  
 
==Hooks==
 
==Hooks==
Line 330: Line 377:
  
 
To create the custom tag, you must use the following hooks.
 
To create the custom tag, you must use the following hooks.
 +
  
 
===Creating a new Custom Tag===
 
===Creating a new Custom Tag===
Line 447: Line 495:
 
?>
 
?>
 
</pre>
 
</pre>
 +
  
 
===Callback function for displaying the tag - pb_loopbuddy_tag_callback-{tag_name}===
 
===Callback function for displaying the tag - pb_loopbuddy_tag_callback-{tag_name}===
 +
 
<pre class='brush:php'>
 
<pre class='brush:php'>
 
<?php
 
<?php
Line 489: Line 539:
 
?>
 
?>
 
</pre>
 
</pre>
 +
  
 
===Rendering the Tag on the Front-end - pb_loopbuddy_render-{tag_name}===
 
===Rendering the Tag on the Front-end - pb_loopbuddy_render-{tag_name}===
Line 513: Line 564:
 
?>
 
?>
 
</pre>
 
</pre>
 +
  
 
===Ignoring Post Types in the Layout Editor===
 
===Ignoring Post Types in the Layout Editor===
Line 529: Line 581:
 
?>
 
?>
 
</pre>
 
</pre>
 +
 +
 +
==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.
 +
 +
[http://ithemes.com/codex/page/General_WordPress_Related#Editing_or_Adding_Stuff_to_Functions.php Info on editing or adding stuff to Functions.php]
 +
 +
===Current Limitations (LoopBuddy 1.2.x and earlier)===
 +
 +
Loopbuddy does not process shortcodes with parameters, such as <code>[pb_slideshow group="2"]</code>. 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 <code>[pb_slideshow group="2"]</code>, to show a slideshow) to a custom field in your post. In this example, the custom field is named <code>post-slideshow</code>.
 +
 +
Then, add the following code at the end of your functions.php file (but before the closing <code>?></code>, if any).
 +
 +
====Code====
 +
 +
<pre class="brush:php">
 +
function insert_my_custom_field_shortcode() {
 +
    global $post;
 +
   
 +
    return do_shortcode( get_post_meta( $post->ID , "post-slideshow" , true ) );
 +
}
 +
add_shortcode('insert-slideshow-in-post', 'insert_my_custom_field_shortcode');
 +
</pre>
 +
 +
====Usage====
 +
Drag a shortcode into the LoopBuddy layout of your post, and add the <code>[insert-slideshow-in-post]</code> shortcode. The function will retrieve the contents of the custom field (<code>post-slideshow</code>) 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, <code>[pb_videoshowcase group="0"]</code>, to show a videoshowcase group), add the following code at the end of your functions.php file (but before the closing <code>?></code>, if any).
 +
 +
====Code====
 +
 +
<pre class="brush:php">
 +
function get_preloop_videos() {
 +
 +
    return do_shortcode( "[pb_videoshowcase group='0']" );
 +
   
 +
}
 +
add_shortcode('my-videos', 'get_preloop_videos');
 +
</pre>
 +
 +
====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):
 +
<pre class="brush:php">add_action( 'init', 'lb_cat_init' );
 +
function lb_cat_init() {
 +
add_shortcode('taxdescription', 'lb_the_description');
 +
} //end lb_cat_init
 +
function lb_the_description() {
 +
global $post;
 +
if ( !is_object( $post ) ) return;
 +
$terms = get_post_meta( $post->ID, 'description_terms', true );
 +
$taxonomy = get_post_meta( $post->ID, 'description_taxonomy', true );
 +
$return = '';
 +
if ( $terms && $taxonomy ) {
 +
if ( !is_array( $terms ) ) {
 +
$terms = explode( ',', $terms );
 +
}
 +
foreach ( $terms as $term_name ) {
 +
$term = get_term_by( 'slug', $term_name, $taxonomy );
 +
if ( !$term ) continue;
 +
$description = get_term_field( 'description', $term->term_id, $term->taxonomy );
 +
if ( empty( $description ) || !$description ) continue;
 +
$return .= apply_filters( 'pb_the_content', $description );
 +
}
 +
}
 +
return $return;
 +
} //end lb_the_description</pre>
 +
**2 : In the posts you want to show the category description, add the following 2 custom field names and values:
 +
'''Custom Field Name'''  -----        '''Custom Field Value'''
 +
 +
description_taxonomy      -----        category
 +
 +
description_terms        -----        books '''''(OR any category name you have)'''''
 +
 +
**3 : Add a Shortcode Tag to your LoopBuddy layout which has the following shortcode in it:
 +
 +
<code><strong>[taxdescription]</strong></code>
 +
 +
That will show the category description anywhere you put the shortcode.
 +
 +
*Links with related info:
 +
**[http://ithemes.com/forum/index.php?/topic/18153-use-of-category-description/ Use of Category Description - LoopBuddy Forums]
 +
**[http://codex.wordpress.org/Function_Reference/category_description category_description on WordPress Codex]
 +
**[http://codex.wordpress.org/Function_Reference/term_description term_description on WordPress Codex]
 +
 +
 +
===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:
 +
<pre class="brush:php">
 +
function return_title() {
 +
return '<h1>'.get_the_title().'</h1>';
 +
}
 +
add_shortcode('pg_title', 'return_title');</pre>
 +
**2 : Add
 +
<code><strong>[pg_title]</strong></code>
 +
 +
anywhere in the LoopBuddy Layout where you want to show the custom page title.
 +
 +
That will show the custom page title just for that specific post/page where the Layout is being shown.
 +
*Related links:
 +
**[http://ithemes.com/forum/index.php?/topic/18046-displaying-the-page-title-on-which-i-am-using-loop-buddy/ LoopBuddy user Bruce asking about and then sharing the code to show custom Page Titles on each Page where the same LoopBuddy Layout is used]
 +
 +
 +
===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 <code>?></code>, if any).
 +
 +
====Code====
 +
 +
<pre class="brush:php">
 +
function my_previous_next_post() {
 +
    // retrieve the value for next post link
 +
    $next_string = "Next post &amp;rarr;";
 +
    ob_start();
 +
    next_post_link("%link", $next_string);
 +
    $next_link = ob_get_clean();
 +
   
 +
    // retrieve the value for previous post link
 +
    $previous_string = "&amp;larr; Previous post";
 +
    ob_start();
 +
    previous_post_link("%link", $previous_string);
 +
    $previous_link = ob_get_clean();
 +
   
 +
    // build output
 +
    $return = PHP_EOL . '<div id="next-previous" class="navigation clearfix">' . PHP_EOL;
 +
 +
    // display previous link if any
 +
    if ($previous_link) {
 +
        $return .= '<div class="nav-previous alignleft">'. PHP_EOL;
 +
        $return .= $previous_link. PHP_EOL;
 +
        $return .= '</div>'. PHP_EOL;
 +
    }
 +
 +
    // display next link if any
 +
    if ($next_link) {
 +
        $return .= '<div class="nav-next alignright">'. PHP_EOL;
 +
        $return .=  $next_link . PHP_EOL;
 +
        $return .= '</div>'. PHP_EOL;
 +
    }
 +
 +
    $return .= '</div>';
 +
 +
    return $return;
 +
}
 +
add_shortcode('previous-next-post-links', 'my_previous_next_post');
 +
</pre>
 +
 +
====Usage====
 +
 +
Insert the shortcode <code>[previous-next-post-links]</code> in your LoopBuddy layout where you want the Previous and Next post links to appear.
 +
 +
====Customize the Appearance====
 +
 +
* you may have to add some styling, using css you can target the classes used in this example
 +
* you can change the appearance of the links by changing the following lines in the code:
 +
 +
<pre class="brush:php">
 +
    $next_string = "Next post &amp;rarr;";
 +
</pre>
 +
 +
and
 +
 +
<pre class="brush:php">
 +
    $previous_string = "&amp;larr; Previous post";
 +
</pre>
 +
 +
 +
===Add the post author avatar===
 +
 +
If you want to show the post author avatar on a page, add the following code at the end of your functions.php file (but before the closing <code>?></code>, if any).
 +
 +
====Code====
 +
 +
<pre class="brush:php">
 +
function my_insert_avatar() {
 +
    global $post;
 +
    return get_avatar($post->post_author, 64 );
 +
}
 +
add_shortcode('insert-author-avatar', 'my_insert_avatar');
 +
</pre>
 +
 +
====Usage====
 +
 +
Insert the shortcode <code>[insert-author-avatar]</code> in your LoopBuddy layout where you want the Avatar to appear.
 +
 +
====Customize the Appearance====
 +
In this example, the avatar is displayed as a 64px by 64px image. Change this value if you want the avatar in another format.
 +
 +
====Additional documentation====
 +
[http://codex.wordpress.org/Function_Reference/get_avatar get_avatar function reference from WordPress Codex]
 +
 +
 +
===Add navigation from the wp_page navi plugin===
 +
 +
LoopBuddy includes support for the [http://wordpress.org/extend/plugins/wp-pagenavi/ 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 <code>?></code>, if any).
 +
 +
====Code====
 +
 +
<pre class="brush:php">
 +
function my_insert_pagenavi() {
 +
    return wp_pagenavi();
 +
}
 +
add_shortcode('insert-page-navi', 'my_insert_pagenavi');
 +
</pre>
 +
 +
====Usage====
 +
 +
Insert the shortcode <code>[insert-page-navi]</code> 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 <code>?></code>, if any).
 +
 +
====Code====
 +
 +
<pre class="brush:php">
 +
function my_insert_comments_link() {
 +
    return '<a href="' . get_comments_link() . '">Comments to this post</a>';
 +
}
 +
add_shortcode('insert-comments-link', 'my_insert_comments_link');
 +
</pre>
 +
 +
====Usage====
 +
 +
Insert the shortcode <code>[insert-comments-link]</code> in your LoopBuddy where you want the link to appear.
 +
 +
====Customize the Appearance====
 +
In this example, the link will show as clickable text "Comments to this post". You can change this to any text, or an image.
 +
 +
====Additional documentation====
 +
[http://codex.wordpress.org/Function_Reference/get_comment_link get_comment_link function reference from WordPress Codex]
 +
 +
 +
===Add post comments to a single post, or to posts in the post list (archive page)===
 +
 +
If you want to add comments, and a comment form to a post, add the following code at the end of your functions.php file (but before the closing <code>?></code>, if any).
 +
 +
====Code====
 +
 +
<pre class="brush:php">
 +
function my_insert_comments() {
 +
 +
    ob_start();
 +
    global $withcomments;
 +
    $withcomments = true;
 +
    comments_template();
 +
    $my_comments = ob_get_contents();
 +
    ob_end_clean();
 +
 +
    return $my_comments;
 +
   
 +
}
 +
add_shortcode('insert-comments', 'my_insert_comments');
 +
</pre>
 +
 +
====Usage====
 +
 +
Insert the shortcode <code>[insert-comments]</code> in your LoopBuddy layout where you want the comments to appear.
 +
 +
====Additional documentation====
 +
[http://codex.wordpress.org/Function_Reference/comments_template comments_template function reference from WordPress Codex]
 +
 +
 +
===Add comment form to a single post, or to posts in the post list (archive page)===
 +
 +
If you want to show just a comment form with your post on a single post page or archive page, add the following code at the end of your functions.php file (but before the closing <code>?></code>, if any).
 +
 +
====Code====
 +
 +
<pre class="brush:php">
 +
function my_insert_comment_form() {
 +
 +
    ob_start();
 +
    comment_form();
 +
    $my_comment_form = ob_get_contents();
 +
    ob_end_clean();
 +
 +
    return $my_comment_form;
 +
     
 +
}
 +
add_shortcode('insert-comment-form', 'my_insert_comment_form');
 +
</pre>
 +
 +
====Usage====
 +
 +
Insert the shortcode <code>[insert-comment-form]</code> in your LoopBuddy layout where you want the comment form to appear.
 +
 +
====Additional documentation====
 +
[http://codex.wordpress.org/Function_Reference/comment_form comment_form function reference from WordPress Codex]
 +
 +
 +
===Add content from a custom field to a layout===
 +
 +
If you want to add the content of a custom field to your layout, add the following code at the end of your functions.php file (but before the closing <code>?></code>, if any).
 +
 +
====Code====
 +
 +
<pre class="brush:php">
 +
function get_my_custom_field() {
 +
    global $post;
 +
   
 +
    // example 1: return an image in image tags
 +
    return '<img src="' . get_post_meta($post->ID, "my_custom_field_image", true) . '" class="custom-image" />';
 +
 +
    // example 2: return just the contents of the custom field
 +
    return get_post_meta($post->ID, "my_custom_field_name", true);
 +
 +
    // example 3: return the result of a shortcode
 +
    return do_shortcode( get_post_meta($post->ID , "my-shortcode" , true) );
 +
}
 +
add_shortcode('insert-custom-field', 'get_my_custom_field');
 +
</pre>
 +
 +
====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 <code>my_custom_field_image</code> 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 <code>my_custom_field_name</code> and will return that value. Insert the shortcode <code>[insert-custom-field]</code> 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 <code>my_shortcode</code> and insert that in your layout. The custom field contents should include the shortcode brackets, so <code>[my_shortcode]</code>.
 +
 +
====Additional documentation====
 +
[http://codex.wordpress.org/Function_Reference/get_post_meta get_post_meta function reference from WordPress Codex]
 +
 +
==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.
 +
 +
*Related links
 +
**[http://wordpress.org/extend/plugins/custom-post-type-ui/ Custom Post Types UI plugin]
 +
**[http://codex.wordpress.org/Post_Types Creating Post Types in WordPress]
 +
 +
 +
===Page Navigation===
 +
 +
At this time, WP-PageNavi is the only supported plugin in LoopBuddy for having custom page navigation. We strongly recommend you try it for any of your custom page navigation needs.
 +
 +
*Related link
 +
**[http://wordpress.org/extend/plugins/wp-pagenavi/ WP PageNavi WordPress Plugin]
 +
 +
 +
===Customize Excerpts===
 +
 +
At this time, Advanced Excerpt is the only supported plugin in LoopBuddy for allowing custom lengths and formatting for excerpts in WordPress.
 +
 +
*Related link
 +
**[http://wordpress.org/extend/plugins/advanced-excerpt/ Advanced Excerpt WordPress Plugin]
 +
 +
 +
==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 [http://codex.wordpress.org/Settings_Reading_Screen 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
 +
**http://ithemes.com/forum/index.php?/topic/17845-unable-to-get-loopbuddy-working/
 +
**http://codex.wordpress.org/Settings_Reading_Screen
 +
 +
 +
===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: <code><a href="</code>
 +
**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: <code>"></code>
 +
**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.
 +
**5 : Another Text tag (3rd Text tag) with the following content: <code></a></code>
 +
That's it!
 +
*Related thread
 +
**http://ithemes.com/forum/index.php?/topic/16971-text-before-single-custom-field-and-url/
 +
 +
 +
===Search within a LoopBuddy Query===
 +
 +
You can have search widgets which actually search specific LoopBuddy queries for the parameters you specify. There are many different ways of achieving this with LoopBuddy.
 +
 +
Check out the forum thread [http://ithemes.com/forum/index.php?/topic/16606-searching-within-a-loopbuddy-query/ Searching Within a LoopBuddy Query] for more details.
 +
 +
 +
===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 1429 and 1430. They will look like the following:
 +
 +
<pre brush="php">
 +
div class="nav-previous"><?php next_posts_link( __( '<span class="meta-nav">&larr;</span> Older posts', 'it-l10n-loopbuddy' ) ); ?></div>
 +
<div class="nav-next"><?php previous_posts_link( __( 'Newer posts <span class="meta-nav">&rarr;</span>', 'it-l10n-loopbuddy' ) ); ?></div>
 +
</pre>
 +
 +
Only change the "'''Older posts'''" and "'''Newer posts'''" text in the above to say anything else you wish.
 +
 +
*Related forum thread
 +
**http://ithemes.com/forum/index.php?/topic/19863-pagination-text/
 +
 +
==Convert Any Theme to Support LoopBuddy==
 +
 +
This step-by-step process is built from the prior WebDesign.com training webinar that occured on September 17th, 2012.
 +
 +
There are two main things you need to do when converting any WordPress theme to support LoopBuddy.
 +
# You need to add the necessary support in the functions.php file
 +
# You need to wrap the 'original' loop with a conditional tag that checks for the dynamic_loop() function
 +
 +
 +
===Two key code snippets that support LoopBuddy===
 +
 +
Both of these code snippets go in the active theme's functions.php file.
 +
 +
The first code snippet adds theme support to the theme:
 +
<pre class="brush:php">
 +
add_theme_support('loop-standard');
 +
</pre>
 +
 +
The second code snippet adds two functions that define the dynamic_loop():
 +
<pre class="brush:php">
 +
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;
 +
}
 +
}
 +
</pre>
 +
 +
 +
===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.
 +
<pre class="brush:php">
 +
<?php if (!dynamic_loop()) : ?>
 +
ORIGINAL LOOP
 +
<?php endif; ?>
 +
</pre>
 +
 +
 +
===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.
 +
# [http://ithemes.com/forum/index.php?/topic/18160-loop-buddy-placement/#p85184 Show custom static homepage content and 3 latest blog excerpts under it]
 +
 +
 +
==Release Notes==
 +
 +
[[:Category:LoopBuddy/Release_Notes|Release Notes]]
 +
  
 
==Additional Resources==
 
==Additional Resources==
# [http://pluginbuddy.com/purchase/backupbuddy/ Purchase BackupBuddy]
 
  
 +
# [http://pluginbuddy.com/purchase/backupbuddy/ Purchase BackupBuddy]
 
# [http://pluginbuddy.com/tutorials/ PluginBuddy Tutorials]
 
# [http://pluginbuddy.com/tutorials/ PluginBuddy Tutorials]
 
# [http://pluginbuddy.com/ PluginBuddy.com]
 
# [http://pluginbuddy.com/ PluginBuddy.com]

Revision as of 16:55, December 20, 2012

Contents

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


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



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 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() ); ?>
									</a>
								</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 functions.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

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:



Advanced Taxonomy Queries

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



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.

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


Creating a new Custom Tag

	<?php
	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',
			array(
				'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

<?php
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}

<?php
/*$settings contains the tag items and the tag item's value
	Example
			Array
		(
		    [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}

<?php
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:

<?php
	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;
	}
?>


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.

Info on editing or adding stuff to Functions.php

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

Code

function insert_my_custom_field_shortcode() {
    global $post;
    
    return do_shortcode( get_post_meta( $post->ID , "post-slideshow" , true ) );
}
add_shortcode('insert-slideshow-in-post', 'insert_my_custom_field_shortcode');

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

function get_preloop_videos() {

    return do_shortcode( "[pb_videoshowcase group='0']" );
    
}
add_shortcode('my-videos', 'get_preloop_videos');

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):
add_action( 'init', 'lb_cat_init' );
function lb_cat_init() {
	add_shortcode('taxdescription', 'lb_the_description');
} //end lb_cat_init
function lb_the_description() {
	global $post;
	if ( !is_object( $post ) ) return;
	$terms = get_post_meta( $post->ID, 'description_terms', true );
	$taxonomy = get_post_meta( $post->ID, 'description_taxonomy', true );
	$return = '';
	if ( $terms && $taxonomy ) {
		if ( !is_array( $terms ) ) {
			$terms = explode( ',', $terms );
		}
		foreach ( $terms as $term_name ) {
			$term = get_term_by( 'slug', $term_name, $taxonomy );
			if ( !$term ) continue;
			$description = get_term_field( 'description', $term->term_id, $term->taxonomy );
			if ( empty( $description ) || !$description ) continue;
			$return .= apply_filters( 'pb_the_content', $description );
		}
	}
	return $return;
} //end lb_the_description
    • 2 : In the posts you want to show the category description, add the following 2 custom field names and values:

Custom Field Name ----- Custom Field Value

description_taxonomy ----- category

description_terms ----- books (OR any category name you have)

    • 3 : Add a Shortcode Tag to your LoopBuddy layout which has the following shortcode in it:

[taxdescription]

That will show the category description anywhere you put the shortcode.


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:
function return_title() {
return '<h1>'.get_the_title().'</h1>';
}
add_shortcode('pg_title', 'return_title');
    • 2 : Add

[pg_title]

anywhere in the LoopBuddy Layout where you want to show the custom page title.

That will show the custom page title just for that specific post/page where the Layout is being shown.


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

Code

function my_previous_next_post() {
    // retrieve the value for next post link
    $next_string = "Next post &rarr;";
    ob_start(); 
    next_post_link("%link", $next_string);
    $next_link = ob_get_clean(); 
    
    // retrieve the value for previous post link
    $previous_string = "&larr; Previous post";
    ob_start(); 
    previous_post_link("%link", $previous_string);
    $previous_link = ob_get_clean(); 
    
    // build output
    $return = PHP_EOL . '<div id="next-previous" class="navigation clearfix">' . PHP_EOL;

    // display previous link if any
    if ($previous_link) {
        $return .= '<div class="nav-previous alignleft">'. PHP_EOL;
        $return .= $previous_link. PHP_EOL;
        $return .= '</div>'. PHP_EOL;
    }

    // display next link if any
    if ($next_link) {
        $return .= '<div class="nav-next alignright">'. PHP_EOL;
        $return .=  $next_link . PHP_EOL;
        $return .= '</div>'. PHP_EOL;
    }

    $return .= '</div>';

    return $return;
}
add_shortcode('previous-next-post-links', 'my_previous_next_post');

Usage

Insert the shortcode [previous-next-post-links] in your LoopBuddy layout where you want the Previous and Next post links to appear.

Customize the Appearance

  • you may have to add some styling, using css you can target the classes used in this example
  • you can change the appearance of the links by changing the following lines in the code:
    $next_string = "Next post &rarr;";

and

    $previous_string = "&larr; Previous post";


Add the post author avatar

If you want to show the post author avatar on a page, add the following code at the end of your functions.php file (but before the closing ?>, if any).

Code

function my_insert_avatar() {
    global $post;
    return get_avatar($post->post_author, 64 );
}
add_shortcode('insert-author-avatar', 'my_insert_avatar');

Usage

Insert the shortcode [insert-author-avatar] in your LoopBuddy layout where you want the Avatar to appear.

Customize the Appearance

In this example, the avatar is displayed as a 64px by 64px image. Change this value if you want the avatar in another format.

Additional documentation

get_avatar function reference from WordPress Codex


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

function my_insert_pagenavi() {
    return wp_pagenavi();
}
add_shortcode('insert-page-navi', 'my_insert_pagenavi');

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

Code

function my_insert_comments_link() {
    return '<a href="' . get_comments_link() . '">Comments to this post</a>';
}
add_shortcode('insert-comments-link', 'my_insert_comments_link');

Usage

Insert the shortcode [insert-comments-link] in your LoopBuddy where you want the link to appear.

Customize the Appearance

In this example, the link will show as clickable text "Comments to this post". You can change this to any text, or an image.

Additional documentation

get_comment_link function reference from WordPress Codex


Add post comments to a single post, or to posts in the post list (archive page)

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

Code

function my_insert_comments() {

    ob_start();
    global $withcomments;
    $withcomments = true; 
    comments_template();
    $my_comments = ob_get_contents();
    ob_end_clean();
 
    return $my_comments;
    
}
add_shortcode('insert-comments', 'my_insert_comments');

Usage

Insert the shortcode [insert-comments] in your LoopBuddy layout where you want the comments to appear.

Additional documentation

comments_template function reference from WordPress Codex


Add comment form to a single post, or to posts in the post list (archive page)

If you want to show just a comment form with your post on a single post page or archive page, add the following code at the end of your functions.php file (but before the closing ?>, if any).

Code

function my_insert_comment_form() {

    ob_start();
    comment_form();
    $my_comment_form = ob_get_contents();
    ob_end_clean();
 
    return $my_comment_form;
       
}
add_shortcode('insert-comment-form', 'my_insert_comment_form');

Usage

Insert the shortcode [insert-comment-form] in your LoopBuddy layout where you want the comment form to appear.

Additional documentation

comment_form function reference from WordPress Codex


Add content from a custom field to a layout

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

Code

function get_my_custom_field() {
    global $post;
    
    // example 1: return an image in image tags
    return '<img src="' . get_post_meta($post->ID, "my_custom_field_image", true) . '" class="custom-image" />';

    // example 2: return just the contents of the custom field
    return get_post_meta($post->ID, "my_custom_field_name", true);

    // example 3: return the result of a shortcode
    return do_shortcode( get_post_meta($post->ID , "my-shortcode" , true) );
}
add_shortcode('insert-custom-field', 'get_my_custom_field');

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

get_post_meta function reference from WordPress Codex

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.


Page Navigation

At this time, WP-PageNavi is the only supported plugin in LoopBuddy for having custom page navigation. We strongly recommend you try it for any of your custom page navigation needs.


Customize Excerpts

At this time, Advanced Excerpt is the only supported plugin in LoopBuddy for allowing custom lengths and formatting for excerpts in WordPress.


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.
    • 5 : Another Text tag (3rd Text tag) with the following content: </a>

That's it!


Search within a LoopBuddy Query

You can have search widgets which actually search specific LoopBuddy queries for the parameters you specify. There are many different ways of achieving this with LoopBuddy.

Check out the forum thread Searching Within a LoopBuddy Query for more details.


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 1429 and 1430. They will look like the following:

div class="nav-previous"><?php next_posts_link( __( '<span class="meta-nav">←</span> Older posts', 'it-l10n-loopbuddy' ) ); ?></div>
<div class="nav-next"><?php previous_posts_link( __( 'Newer posts <span class="meta-nav">→</span>', 'it-l10n-loopbuddy' ) ); ?></div>

Only change the "Older posts" and "Newer posts" text in the above to say anything else you wish.

Convert Any Theme to Support LoopBuddy

This step-by-step process is built from the prior WebDesign.com training webinar that occured on September 17th, 2012.

There are two main things you need to do when converting any WordPress theme to support LoopBuddy.

  1. You need to add the necessary support in the functions.php file
  2. You need to wrap the 'original' loop with a conditional tag that checks for the dynamic_loop() function


Two key code snippets that support LoopBuddy

Both of these code snippets go in the active theme's functions.php file.

The first code snippet adds theme support to the theme:

add_theme_support('loop-standard');

The second code snippet adds two functions that define the dynamic_loop():

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;
	}
}


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

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

  1. Show custom static homepage content and 3 latest blog excerpts under it


Release Notes

Release Notes


Additional Resources

  1. Purchase BackupBuddy
  2. PluginBuddy Tutorials
  3. PluginBuddy.com
  4. Support Forums
Personal tools
Namespaces
Variants
Actions
iThemes Codex
Codex Navigation
Toolbox