Customizing Blogroll Output: Tutorial

First of all, I extended my navigation bar to display a little text beneath the randomly extracted blogroll saying how many items are extracted and how many there are in total. The text links to my blogroll page, too, and states the update frequency. Here's the code:

Update: The ul tags surrounding the blogroll list have been moves inside the formatter class to provide valid HTML.

<?php
if (function_exists("rbr_output"))
{
// Custom formatter class
class rbr_nOutOfmFormatter
{
   var $frequency;
 
   function rbr_nOutOfmFormatter($freq)
   {
      $this->frequency = $freq;
   }
 
   function format(&$items, $tagBefore, $tagAfter)
   {
      global $rbr_items;
      $ret = "<ul>"; // NEW!
 
      // Build the blogroll first
      $defaultFormatter =& new rbr_DefaultFormatter();
      $ret .= $defaultFormatter->format($items, $tagBefore, $tagAfter);
      $ret .= "</ul>"; // NEW
 
      // Only add a comment if the random blogroll is a subset
      $countOutput = $items->count();
      $countInput = $rbr_items->count();
      if ($countOutput < $countInput)
      {
         $ret .= '<p class="rbr_noutofm">' . $countOutput .
              ' links taken <a href="http://dev.wp-plugins.org/wiki/RandomizedBlogroll"' .
              ' title="Done with Randomized Blogroll plugin">randomly</a> out of' .
              ' <a href="" . get_bloginfo('url') . '/blogroll.php" title="View my complete blogroll"> ' .
              $countInput . ' total</a>. Updated every ' . $this->frequency . ' minutes.</p>';
      }
 
      return $ret;
   }
}
?>
<li id="blogroll"><?php _e('Blogs I read'); ?>
<!-- <ul> REMOVED -->
<?
$rbr_formatter =& new rbr_nOutOfmFormatter(30);
rbr_output('wp-content/export.xml', 25, 30);
?>
<!-- </ul> REMOVED -->
</li>
<?php
}
?>

If you compare this to the example code given in the readme, you'll notice that I added a class declaration for rbr_nOutOfmFormatter. This class actually does the work. But to make sure the plugin uses this class for output formatting rather than the default one, it has to be set as the current Formatter. This is done by setting the global variable $rbr_formatter:

$rbr_formatter =& new rbr_nOutOfmFormatter(30);

What does rbr_nOutOfmFormatter actually do? Let's have a deeper look.

First of all it takes the update frequency as a constructor argument and stores it in a member variable called frequency. Second it provides a function "format". This function has to be defined for all Formatter classes, since it is invoked by the plugin.

The format fucntion takes the collection of extracted blogroll items as first parameter. It passes this along to the default formatter, which generates the list of links to be displayed. After that, the function reads the number of entries from both the randomly extracted list and the original input, which is stored in the global variable $rbr_items. If there is only a subset to be displayed, it finally adds some text to the generated output like this:

25 links taken randomly out of 112 total. Updated every 30 minutes.

The text contains two links, one to the plugin page (Advertise! Advertise!) and one to the blogroll page which is to be covered right now.

How do I make a single, static page? Well, The easiest way is to do a copy of "index.php" and remove the loop. Here's how you do it for an out of the box "index.php":

• Make a copy of index.php and rename it to "blogroll.php". Put the copy in the same directory then "index.php"
• Open "blogroll.php" in a text editor.
• Delete everything between <div id="content"> and <div class="post">
• Delete the line that starts with <div class="meta">
• Delete everything between <div class="feedback"> and <?php include(ABSPATH . 'wp-comments.php'); ?> including these lines.
• Delete everything between <?php endforeach; else: ?> and <?php endif; ?> including this lines.
• Now change the line that starts with <h3> to look like this:
  <h3 class="storytitle">My Blogroll</h3>
• Replace <?php the_content(); ?> with some custom text like:
  <p>Just a test</p>

Your new page now should contain code like this:

<div id="content">
<div class="post">
  <h3 class="storytitle">My Blogroll</h3>
  <div class="storycontent">
    <p>Just a test</p>
  </div>
</div>
</div>
Open the page in the browser to verify if everything is OK. You maybe need to replace "h3" with "h2" in the above code to make it look better.

Everything set up? Then let's hack the blogroll into it. To do this replace <p>Just a test</p> with this code:

<php
if (function_exists("rbr_output"))
{
  ?>
  <p>These are the blogs I frequently read:</p>
  <?php
 
  // read the subscriptions
  rbr_readOPML("wp-content/export.xml");
 
  if ($rbr_items->count() > 0)
  {
    echo "<ul>";
 
    //Output list
    for ($rbr_items->reset(); $item = $rbr_items->current(); $rbr_items->next())
    {
      echo "<li>";
      echo $item->getAnchorHTML();
      if (! empty($item->feedURL) )
      {
        ?>
        (<a href="<?php echo $item->feedURL; ?>" title="Feed Syndication for this site">Feed</a>)
        <?php
      }
      echo "</li>";
    }
 
    echo "</ul>";
  }
  else
  {
    // No items in subscription
    ?>
    <p>For some reasons, I don't read any other blog at this time. Or maybe an error occured. Check back later.</p>
    <?php
  }
}
else
{
  ?>
  <p>Sorry, this functionality is not available at the time.</p>
  <?php
}
?>


Let's quickly step trough it.

• It starts with a safety condition, so PHP will not fail if the Randomized Blogroll plugin is disabled. I described this technique here.
• If the plugin is installed, a paragraph is outputted saying "These are the blogs I read:".
• After that, the subscription OPML file is read using the according function from the plugin.
• This function stores its result in the global variable $rbr_items, so this is checked to contain any content.
• If so, we step through all items and output them accordingly, including a link to the rss feeds, if any (Note: There is a bug in version 0.2, so this won't work. Be sure to have at least version 0.2.1. You can download it here).

To see the results, browse to my blogroll site.