mitcho Michael 芳貴 Erlewine

Postdoctoral fellow, McGill Linguistics.

blog

Using Templates with YARPP 3

I am no longer maintaining the information here. It is out of date. Please see the Developing with YARPP section of the YARPP readme.

If you have a YARPP support question not directly related to the templating feature, please use the YARPP support forums.

Version 3 of Yet Another Related Posts Plugin is a major rewrite which adds two new powerful features: caching and templating. Today I’m going to show you how you can use templates to customize the look of your related posts output.1

Previously with YARPP you were relatively limited in the ways you could present related posts. You were able to set some HTML tags to wrap your posts in and choose how much of an excerpt (if any) to display. This limited interface worked great for many users—indeed, these options still exists in YARPP 3.0. However, there’s also a new option for those of you who want to put your PHP skills to work and have complete control over your related posts display. The option will let you choose any files in the templates subdirectory of YARPP.

templates interface

The structure of a YARPP template

Let’s take a look inside the example template, included with YARPP 3 (yarpp-template-example.php):

  1. <h3>Related Posts</h3>
  2. <?php if (have_posts()):?>
  3. <ol>
  4. 	<?php while (have_posts()) : the_post(); ?>
  5. 	<li><a href="<?php the_permalink() ?>" rel="bookmark"><?php the_title(); ?></a></li>
  6. 	<?php endwhile; ?>
  7. </ol>
  8. <?php else: ?>
  9. <p>No related posts.</p>
  10. <?php endif; ?>

There are two basic parts to this (and most all) YARPP template: (a) what you display when there are related posts and (b) what you display when there aren’t. We make this switch with the conditional on line 6. If there are related posts, we introduce an ordered list and use the while loop to loop over all the related posts. For each post, we use the snippet the_post(); to load the appropriate post data, then print the line item.

You’ll notice that we’re using familiar template tags here such as the_permalink() and the_title(). If you’ve ever had to tweak or build a WordPress theme before, you’ll immediately feel at home. I’ll touch on this again later.

The power of PHP

One big advantage of this new templating system is that you can control exactly how the posts are listed, breaking out of all of the previous structural limitations. For example, in the template-list.php template, we put the information for each related post in an array and then concatenate the strings with implode. This way, we produce a comma-separated list for our readers without any stray commas before or after the list, which was impossible until now.

  1. $postsArray = array();
  2. while (have_posts()) : the_post();
  3. 	$postsArray[] = '<li><a href="'.get_the_permalink().'" rel="bookmark">'.get_the_title().'</a></li>';
  4. endwhile;
  5.  
  6. echo implode(', ',$postsArray); // print out a list of the related items, separated by commas

You can also run any arbitrary PHP in the template file—even roll another WP_Query, as in the case of template-random.php, where a random post is returned when there are no related posts.

Familiar template tags

As mentioned before, the tags we use in these YARPP templates are the same as the template tags used in any WordPress template. In fact, any WordPress template tag will work in the YARPP Loop. You can use these template tags to display the excerpt, the post date, the comment count, or even some custom metadata. I’ve also written two special template tags which only work within a YARPP Loop: the_score() and get_the_score(). As you may expect, this will print or return the match score of that particular related post.

In addition, template tags from other plugins will also work. For an example, take a look at the yarpp-template-photoblog.php file:

  1. <?php while (have_posts()) : the_post(); ?>
  2. 	<?php if (function_exists('yapb_is_photoblog_post')): if (yapb_is_photoblog_post()):?>
  3. 	<li><a href="<?php the_permalink() ?>" rel="bookmark"><?php yapb_get_thumbnail(); ?></a></li>
  4. 	<?php endif; endif; ?>
  5. <?php endwhile; ?>

In this template’s YARPP Loop, we use some template tags introduced by the Yet Another Photoblog plugin. If you have the Yet Another Photoblog plugin installed, you can use this template to display thumbnails of related posts in lieu of the titles. Notice that here we’re checking first whether each related post is indeed a photo post or not using yapb_is_photoblog_post() and then using the Yet Another Photoblog yapb_get_thumbnail() template tag to get the location of the thumbnail.

Templating in YARPP 3.0 enables the blog admin to uber-customize their related posts display using the lingua franca of PHP and template tags. Feel free to comment here with ideas, comments, and of course links to your YARPP-powered blogs. I look forward to seeing what the WordPress community does with this new feature!


  1. For those of you interested in the WP and SQL voodoo used to make this happen, I’ve posted a more technical article

Tags: , , , , , , ,

If you enjoyed this post, make sure you subscribe to my RSS feed (optionally with tweets from my Twitter)!

  • http://www.dissertationprovider.co.uk Michael Lawrence

    Hi, This is great work and very good information. This post will really help beginners, although it is basic but, it will help others in great deal in future.

    Buy Dissertation

  • http://www.flasherblog.com Yagiz Gurgul

    I can't see my templates files. It's blank. What is the problem? ( I have latest version installed )

    • http://intensedebate.com/people/mitchoyoshitaka mitcho

      Is it one of the bundled templates or a custom one?

  • http://www.code-pal.com Sumeet Chawla

    This is a very interesting plugin and am going to use this instead of my old plugin :P Thank you very much for creating it !

  • http://www.decorkitchens.com.au kitchen renovation

    Hi, Great plugin.
    I had a couple of issues setting it up, but now it works perfectly Very useful Love it

  • http://www.softwarevenue.com Free Download

    Have been using this plugin since the first time blogging. The custom template feature is really great. Really appreciate for the hard work. Thanks

  • http://web-hosting.ro.im gazduire

    Thanks, good works… bravo! :)

  • Eric

    I have a wordpress site with constant feed of shopping items. I would like a side bar widget to show seasonal offers such as Christmas product posts. Is there a plugin or bit of code to achieve this easily?

    • http://intensedebate.com/people/mitchoyoshitaka mitcho

      There may be, but YARPP would not be what you want. Try checking http://wordpress.org/extend/ .

  • Pingback: Lorem ipossum opossum « gavia . gráfia()

  • Pingback: Wordpress Plugin: Yet Another Related Posts Plugin | HiTechBlog()

  • Pingback: Must Have SEO Plugins for Wordpress - Wordpress Geeks()

  • http://www.leanphysiquesecrets.com Kurt Williams

    I am trying to use filezilla to move the template files to the wordpress theme folder. Will you please explain this in detail as if you were trying to teach a child? I don't get it. I have tried uploading the files from my desk top, I have tried dragging them directly from the right side of filezilla into the wordpress theme. I have double clicked on that wordpress theme to find another file with the theme's name on it and tried uploading and dragging it into that file and nothing makes a difference, except I now get this message:

    No YARPP template files were found in your theme (/home/kurtwill/public_html/myssite.com/wp-content/themes/republic/republic) so the templating feature has been turned off.

    Kurt

    • http://mitcho.com/blog mitcho

      What you want to move to your theme’s folder are the files which are named yarpp-template-....php rather than the yarpp-templates folder itself. I hope that helps.

  • Pingback: Wordpress相关文章插件Yet Another Related Posts Plugin - 大海个人网站()

  • Source astrology

    Thanks Mitcho for providing a really great tool and now with the updated version, it seems to be even better.

    Unfortunately I was also one of the ones who didnt understand how to get the thumbnails to work and am not a PHP expert and I couldnt quickly find the information here relevant for a total newbie. So, I did a search on Google and found a site which gives step-by-step instructions and voila, the thumbnails showed up. It was just a matter of creating a new PHP with the code they gave and adding CSS to the stylesheet.

    Of course you still need a thumbnail generator (I use timthumb) and have the path for the thumbnail image in the page/posts in order for the image to display, plus you have to select the template you want to use in the settings for YARRP. They have screenshots and all the information needed to do this properly.

    Anyway, I found the information on this page totally useful, without which I had no clue how to make it work. Just thought I would share it so that others could benefit too (hope it's okay to post): http://archondigital.com/studio/wordpress/plugins

    And I have no affiliation with this site, just found it incredibly useful for me and thought that others would benefit too, as it provides step-by-step instructions for total PHP newbies like me to enable the thumbnails to work. And now they do and it looks really good!

    • http://intensedebate.com/people/mitchoyoshitaka mitchoyoshitaka

      Thanks for the link. Looks great!

  • http://franchise-indo.co.cc Waralaba

    Great plugin. Is there anyway to put the related posts list on wordpress sidebar ? Is there any widget for this ?

    • http://mitcho.com/blog mitcho

      A “Related Posts” widget is included with the plugin.

  • http://audiodecoders.blogspot.com ac3filter download

    I was already using timthumb.php on my theme to generate post thumbnails and using it on the related posts loop made it much easier as I only have to specify one custom field for all my thumbnails

  • http://bagosbanget.web.id bagosbanget

    Yes, i upgraded and there was a notification : "The plugin generated 896 characters of unexpected output during activation. If you notice “headers already sent” messages, problems with syndication feeds or other issues, try deactivating or removing this plugin." Is it related with template with yarp3?

    • http://mitcho.com/blog mitcho

      This was fixed with version 3.1.9. :)

  • Pingback: Making it Lovely | Transforming the so-so. » Blog Archive » Adding Related Posts()

  • Tiger

    Fantastic Work - Really great stuff - also got the error about headers but everything seems to be working fien though

    well done - will be donating for sure

  • http://www.graphic-instinct.com Jo Graphiste

    Thank you for this nice script. I'ma try it on my new WP website. :) But I think this is a little bit advanced for me, my developer will do it for me. :)

  • http://suhanto.net/ Agus Suhanto

    YARPP is the one of the plugins I never deactivate since I use it. It is very effective in retrieving related posts. Related with templating, I have create a sample of YARPP template that uses post-thumbnail or featured image feature of WordPress >2.9. The thumbnail is also overlaid with title post on top of transparent background. Here is the implementation details: http://suhanto.net/yarpp-template-post-thumbnails….

    I hope it is useful!

  • http://codemyconcept.com Puscifer

    Hi, Great plugin you have here!!!! I used it and works like a charm. Rated: 5stars!

  • http://www.vouchersmarter.co.uk/retailer/tesco.com Tesco voucher codes

    Every other mention of this table in your plugin includes the prefix, except for the create. Changing the table create statement to: {$wpdb-&gt;prefix}yarpp_related_cache fixed everything for me.