bioneural.net

Having settled on SimplePie as a solution for embedding iStockPhoto feeds, I decided to see if I could use it to parse the latest posts from multiple sites in my OPML file (blogroll if you prefer). Would it really be as simple to cook as it sounded? There were qualifiers, however. I wanted to show only a selection of headlines at any one time. I wanted to vary the order in which the sites were listed. And I wanted to automatically fetch and display the favicon for each site. Armed only with copy-and-paste level PHP know-how, I was going to need help in the kitchen—that much was clear at the outset.

Update 18.08.06: Ryan has added error handling for feeds which specify no author; this eliminates most of the fatal errors I was getting with some feeds. If a particular feed doesn't work for you there are several things to try: Is it specified in the page (required for auto-discovery) or must you specify the full feed URL cf. the domain name? Is the feed valid? If a site offers RSS and Atom feeds (WordPress sites do by default) try varying the feed format. Also, specifying the actual feed path rather than relying on auto-discovery should reduce display time. Many thanks Ryan!

Link lists

Lists of links to other sites are just plain boring. But they can be functional, potentially serving a number of purposes:

• Bookmarks that the siteowner uses to track sites of personal interest;
• Serving readers by linking to sites with related news or resources;
• Reciprocal link exchange (with the aim of increasing one's PageRank/ Google listing);
• Giving credit (e.g. services or software used in site construction);
• Social bookmarking (e.g. my del.icio.us);
• Content for a sideblog or asides using RSS syndication.

WordPress includes a links manager, which has the option to tag links with XFN metadata using the "rel" link attribute. Such link relationships may involve self-identification/ site ownership, friendship type, a record of physical meetings (!), professional associations, geographic location, family or romantic ties. XFN is a tool for social networking much as Del.icio.us and Digg are tools for social bookmarking. Personally, I think this is taking link lists a bit far (and I like to be organized!).

Link lists can still be more functional than mere lists, even without tagging them with such metadata. Why list a site by name day-after-day? It doesn't change, yet the content of the site does. Sometimes, so does the author. And how do you know when it last had new content? But what is function without form, right? We also want our link lists to be aesthetically pleasing (OK, pretty).

So the aim here is to improve on the basic link list: to make it both more functional and more attractive.

Prepare your ingredients

We don't need much actually:

• An installation and activation of the SimplePie WordPress plugin (but you don't need WordPress or if you do have WordPress, you don't need to install the plugin if you follow these instructions);
• A WordPress page template for the K2 theme (this is how I chose to implement it; again you don't need WordPress, and if you do have it but don't use K2 you can create your own page template);
• An OPML file from which to extract the links (easy to export from NetNewsWire);
• Some generic PHP code to shuffle and pick from a list. I found a snippet I thought would do at Scriptygoddess;
• A Guru. I am indebted to Ryan Parman, one of the two SimplePie developers, for his patience and much-appreciated assistance via the SimplePie Support Forum.

Every pie needs a good base

I didn't even realize WordPress page templates existed until I read Kristin's post. There are two steps: first we create a template, then we create a new WordPress page and tell it to use the template we just created.

Here's a skeletal page template that you can adapt (or not) for your own use:

<?php
/*
    Template Name: Baking
*/
?>

<div class="content">

    <div class="primary">

        <?php if (have_posts()) : while (have_posts()) : the_post(); ?>

            <div class="item">

                <div class="pagetitle">
                    <h2 id="post-<?php the_ID(); ?>"><a href="<?php the_permalink() ?>" rel="bookmark" title='Permanent Link to "<?php the_title(); ?>"'><?php the_title(); ?></a></h2>
                </div>

                <div class="itemtext">

                </div><!-- Close itemtext -->

            </div><!-- Close item -->

        <?php endwhile; endif; ?>

    </div><!-- Close primary -->

    <?php get_sidebar(); ?>

</div><!-- Close content -->

<?php get_footer(); ?>

Save this as baking.php and upload to your WordPress themes folder.

In WordPress Admin, choose Manage > Pages > Create New Page... Give the page a title but leave the content area blank and choose "Baking" from the Page Template: control:

Save the new page and you're good to go. There's nothing on this page yet of course; we'll address that shortly. Let's first consider two other elements we want to build into the page: randomness and favicons.

Mix well before baking

Here is the Scriptygoddess random blogs list script:

<?
$array = file("/path/to/your/file/bloglinks.php");
shuffle($array);
for ($i=0; $i<10; $i++) {
echo $array[$i];
}
?>

First the code loads the links (from an external file) into an array, then it shuffles them, selecting 10 (in this case) to output to the screen. Sounds good; we'll see it adapted below.

Favicon topping

I'm a big fan of favicons. They're easy to make and I've used them in my blog in conjunction with "blockquote" since my CSS reboot in 2004. For example:

Instant recognition. A 16x16 pixel image is a valuable visual aid to source attribution and can confer authority on the cited wisdom. The markup is extremely simple:

<blockquote>
<img src="http://9rules.com/favicon.ico" alt="favicon" width="16" height="16" />
blah blah blah...
</blockquote>

I use CSS to have the favicon display as a fixed-size block element so it sits on a line of its own. Other folk use favicons in lists, presumably for partly decorative and partly navigational reasons. Here are some examples:

• 9rules.com Communities;
• Kristin Pishdadi's Low End Theory;
• Ben Gray's Open Switch.

A 9rules.com favicon pick-list

Ben tells me he maintains his link list manually, and pointed me towards Kristin's inspirational how-to post. But I'd prefer to automate favicon-finding if possible.

There is WP plugin, Favatars, that does automatically gather and cache favicons. Caching is probably necessary since, as Ben also pointed out, page load times would otherwise increase (and storing permanent local copies might not reflect the favicon in use at the site). Unfortunately the plugin only works inside the WordPress "comment loop". There's an alternative PHP script that tries to guess the favicon URL here, but my skills were not up to repurposing this either.

However, we can (in most cases) display a favicon much more simply using SimplePie and a neat PHP concatenation trick—the tying together of multiple strings into a single string. You'll see this in the code below; it was a bugger of a job to get all the punctuation right—and you can stop smirking if you've been coding PHP for years—this was all new to me!

It wouldn't be pie without filling

We have our base, the mixer is on stand-by, and we've decided how to prepare the topping. On to the filling...

The best way to present this is to see the finished page. It went through several earlier iterations, but this version has been re-worked by Ryan so that the code is more efficient (not so much jumping in-and-out of PHP blocks) and so that it loads only one feed into memory at a time (apparently PHP is readily exhausted). The page is commented so your can hopefully follow what's going on, and I've left in some of the lines that you will need to uncomment (and edit) if you are not using the WordPress plugin:

<?php
/*
    Template Name: Baking v4
*/

// Require simplepie.inc not necessary as already called via WP plugin
// require($_SERVER['DOCUMENT_ROOT'] . '/wp-content/plugins/simplepie.inc'); 

// Set cache folder to non-default location as used by WP plugin
$cache = $_SERVER['DOCUMENT_ROOT'] . '/wp-content/plugins/cache';

// Create array with any number of site URLs; SimplePie will auto-detect feed location
$myfeeds = array();

$myfeeds[] = "http://www.siteone.com";
$myfeeds[] = "http://www.sitetwo.com";
$myfeeds[] = "http://www.sitethree.com";

shuffle($myfeeds); // Randomize order of the feeds in array

// Manually setting content type and character encoding not required as set via WP get_header function
// header("Content-type: text/html; charset=utf-8");
get_header();
?>

<div class="content">

    <div class="primary">

        <?php if (have_posts()) : while (have_posts()) : the_post(); ?>

            <div class="item">

                <div class="pagetitle">
                    <h2 id="post-<?php the_ID(); ?>"><a href="<?php the_permalink() ?>" rel="bookmark" title='Permanent Link to "<?php the_title(); ?>"'><?php the_title(); ?></a></h2>
                </div>

                <div class="itemtext">
                    <h4>Recent posts elsewhere</h4>

                <?php
                for ($i=0; $i<10; $i++) { // Where 10 = number of posts to show
                    $feed = new SimplePie($myfeeds[$i], $cache);

                    if ($feed->data) {
                        echo '<div class="sploop">';

                        $max = $feed->get_item_quantity(1); // Show only 1 post, the most recent
                        for ($x = 0; $x < $max; $x++) {
                            $item = $feed->get_item($x);
                            $author = $item->get_author(0);

                            echo '<span class="spfavicon"><a href="' . $feed->get_feed_link() . '">' . '<img src="' . $feed->get_feed_link() . '/favicon.ico" alt="X" width="16" height="16" />'. '</a></span>';
                            echo '<span class="sptitle"><a rel="external" href="' . $item->get_permalink() . '">' . $item->get_title() . '</a></span>';
                            echo '<span class="spauthor">&mdash;By ' . $author->get_name() . '</span>';
                            echo '<span class="spdate"> on ' . $item->get_date('j M Y') . '</span>';
                        }

                        echo '</div>'; // Close sploop
                    }

                    unset($feed);
                }
                ?>

                </div><!-- Close itemtext -->

            </div><!-- Close item -->

        <?php endwhile; endif; ?>

    </div><!-- Close primary -->

    <?php get_sidebar(); ?>

</div><!-- Close content -->

<?php get_footer(); ?>

Making it pretty

I initially wanted to add some fancy styling (hence the classes in the markup). But then sometimes less is more. I decided not to add any CSS other than a rule for positioning the favicon:

.spfavicon img {
	display: inline;
	position: relative;
	bottom: -4px;
	border: 0;
	}

Any more images and it would look to crowded. Perhaps you don't like white space? Feel free to make some CSS suggestions!

I ended up with a link list with visual attribution and exposure of the latest content, the author, and the date the site's content was last refreshed. And lots of lovely white space:

The "live" version is here.

Caveats

• Not all sites work. I don't know why—perhaps a SimplePie bug? Several URLs in my array resulted in a fatal error. I commented them all out and uncommented them one-by-one to ID the troublemakers;
• Not all sites have a favicon at root directory level. As I mentioned I found some PHP that might help here, but didn't manage to make it work due to sheer incompetence;
• Favicons aren't cached, but caching (and automatic favicon-finding) is a SimplePie feature request.

Is there any desert?

The tweaking ain't over 'till the fat lady sings... and I ain't heard me no singing. If you want to show the feed title when hovering over the favicon, make this edit:

echo '<span class="spfavicon" title="' . $feed->get_feed_title() . '" ><a href="' . $feed->get_feed_link() . '">' . '<img src="' . $feed->get_feed_link() . '/favicon.ico" alt="X" width="16" height="16" />'. '</a></span>';

If you want to show the item description when hovering over the post title, make this edit:

echo '<span class="sptitle"><a rel="external" title="' . strip_tags($item->get_description()) . '" href="' . $item->get_permalink() . '">' . $item->get_title() . '</a></span>';

Firefox already displays an excerpt only:

Ugly missing favicons in Firefox? Safari isn't a problem as when it can't load an image you'll see this "missing image" icon:

However, Firefox renders the alt text (here "X"; "favicon" is even worse!):

We can however create a favicon-like "alt" text (still valid XHTML, although it will displease the accessibility camp) and style it so that it is inline with the existing favicons:

echo '<span class="spfavicon" title="' . $feed->get_feed_title() . '"><a href="' . $feed->get_feed_link() . '">' . '<img src="' . $feed->get_feed_link() . '/favicon.ico" alt="&curren;" style="font-size: 24px; padding-right: 6px;" width="16" height="16" />'. '</a></span>';

You'll now see this (the CSS causes the image and the alt text to be a similar size and vertically aligned):

Not perfect—but to my eye at least a whole lot better!

For your convenience, here is a SimplePie with favicon topping and the above extra ingredients that I prepared earlier. Bake in warm oven until you see a golden crust (.zip file, 4 KB)

Update 15.12.06: SimplePie 1.0 b3 introduced the get_favicon() function. You can use this to look for a favicon in the default location and, if not present, substitute a generic alternative—as per the following code:

echo '<span class="spfavicon" title="' . $feed->get_feed_title() . '"><a href="' . $feed->get_feed_link() . '">' . '<img src="' . $feed->get_favicon(true, 'http://www.bioneural.net/images/nofav.jpg') . '" alt="Favicon" style="font-size: 24px; padding-right: 6px;" width="16" height="16" />'. '</a></span>';