LoopBuddy is a tool that overwrites a WordPress Loop using a combination of a custom query and a custom 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.

+

<div class="exchange-home-list">

+

==LoopBuddy Basics== __NOEDITSECTION__

+

*[[Query_Editor|Query Editor]]

+

*[[Layout_Editor|Layout Editor]]

+

*[[LoopBuddy_Global_Settings|Global Settings]]

+

*[[Import/Export|Import/Export]]

+

*[[LoopBuddy Widget|LoopBuddy Widget]]

+

*[[LoopBuddy Shortcode|LoopBuddy Shortcode]]

+

</div>

−

===Query Editor===

+

<div class="exchange-home-list">

+

==LoopBuddy Advanced== __NOEDITSECTION__

+

*[[The_Loop_Standard|The Loop Standard]]

+

**[[The_Loop_Explained|The Loop Explained]]

+

*[[Modifying_a_Theme_to_Use_LoopBuddy|Modifying a Theme to Use LoopBuddy]]

+

**[[Example_of_TwentyTen_Using_the_Loop_Standard|Example of TwentyTen Using the Loop Standard]]

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.

+

<div class="exchange-home-list">

+

==Additional Resources== __NOEDITSECTION__

+

*[http://ithemes.com/purchase/backupbuddy/ Purchase BackupBuddy]

+

*[http://ithemes.com/tutorials/ iThemes Tutorials]

+

*[http://ithemes.com/ iThemes.com]

+

*[http://ithemes.com/forum/ Support Forums]

+

</div>

−

[[File:Layout_editor.png|400px|border|LoopBuddy Layout Editor]]

+

<br />

−

+

[[:Plugins|← Back to Plugin Codex Home]]

−

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.

+

−

+

−

[[File:Layout_editor_options.png|500px|border|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.

+

−

+

−

[[File:Loopbuddy_settings.png|500px|border|General Settings]]

+

−

+

−

===Import/Export===

+

−

+

−

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

+

−

+

−

===LoopBuddy Widget===

+

−

+

−

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

+

−

+

−

===LoopBuddy Shortcode===

+

−

+

−

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

+

−

+

−

Simply insert the shortcode into a post or page:

+

−

+

−

<pre class='brush:php'>

+

−

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

+

−

</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 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 <code>post_class()</code> 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 :

+

−

+

−

<pre class='brush:php'>

+

−

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

+

−

</pre>

+

−

+

−

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:

+

−

+

−

<pre class='brush:php'>

+

−

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

+

−

</pre>

+

−

+

−

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.

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

+

−

+

−

[[Media:twentyeleven-loopstandard.zip|TwentyEleven Loop Standard]]

+

−

+

−

===Example Layout Tag===

+

−

+

−

Check out the LoopBuddy Marquee Plugin: [[Media:Loopbuddy_marquee.zip|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.

+

−

+

−

[[Media:Loopbuddy_export.zip|LoopBuddy Export File]]

+

−

+

−

==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:

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

+

−

+

−

<pre class="brush:php">

+

−

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

Shortcodes basically allow almost any plugin or custom code to be plugged in anywhere in WordPress. LoopBuddy supports shortcodes fully, allowing you to put any shortcode, whether from a plugin or your own, into any place in LoopBuddy Layout. This probably makes the already powerful LoopBuddy the only most powerful way to control all your content, loops and display on your site.

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 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 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 you want to show the custom page title.

+

−

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

+

−

+

−

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