Friends RSS Aggregator

UPDATE Feb 10 2007: I’m currently working on fixes so that FRA works with WP 2.1, along with a new release of the plugin that should have some new features. I’ll make a post on this page and my weblog once its ready. Sorry for any inconvenience.

Friends RSS Aggregator (FRA) Wordpress plugin was built to enable a Wordpress installation to have a livejournal.com-like friends page. By creating a group of friends’ weblog links with RSS/Atom URIs in a particular link category, a user can display an aggregated list of posts by date or name. The word ‘Friends’ in the plugin is also a bit of a misnomer since the plugin is by no means limited to aggregating just friends’ weblogs; FRA allows aggregation of any group of links (that specify RSS URIs) in one or more link categories.

Friends RSS Aggregator 0.3.1 is available for download. Check out my Friends page for an example of the Friends RSS Aggregator in action.

Requirements

  • FRA uses and includes MagpieRSS for all RSS/Atom fetching and parsing. Look to MagpieRSS 0.72 for PHP requirements and dependencies.
  • FRA was developed for Wordpress 1.5.2 but may work with other versions. It has been reported that it works with WP 2.0 but I have not tested it personally.

Support

This page and the distribution files offer most of the support, but if you have problems that can’t be answered after reading the entire page, email me. I don’t answer questions pertaining to anything MS Windows related. This software is free and is provided as-is. I am in no way responsible for any damage that may occur as a result of using this.

[back to top]

Installation and Setup

  1. Download the plugin.
  2. Unpack, and if necessary upload, the plugin in the wordpress plugins directory. This is usually something like $WP/wp-content/plugins where $WP is the Wordpress installation directory. There should now be a ‘friends-rss’ directory in the plugins directory.
  3. In the new friends-rss directory, make the cache directory writable by the webserver process-user. The easiest way to do this (and most insecure) is to issue the command `chmod 777 cache` from within the ‘friends-rss’ directory.
  4. In WP admin UI, activate the plugin by going to the ‘Plugins’ section and selecting the activate link in the Friends RSS entry.
  5. In WP admin UI, go to ‘Options -> Friends RSS’ and specify the absolute path to the cache directory (e.g. /home/foobar/public_html/wp-content/plugins/friends-rss/cache).
  6. If there isn’t one yet, in the WP admin UI, create a link category with a few links in it. Although it is not required, you can name the category ‘Friends’ to make later setup easier. Important: Make sure that each of the links in the category has an RSS URI specified in the RSS URI field (not the Link URI field) so that the RSS feed can be fetched.
  7. Copy linkfeeds_by_date.php from the example_templates directory into the current WP theme directory. If you want the posts listed by name of link, copy linkfeeds_by_name.php, instead.
  8. In WP admin UI, write a new page. Specify the page template as ‘Link RSS Feeds By Date’. When you fill in the ‘Page Title’ and ‘Page Content’ fields they will appear at the top of the viewed page.
  9. If your link category name is not ‘Friends’, you will have to edit the template that was copied into the theme directory to pass the category name in the display function. See the template file for further details.
  10. View the page after editing to ensure that posts are being retrieved and that you like how the page looks. If you don’t like how the page looks and feels, check out customizing look and feel. If the page does not function as it should, read the general problems section.

[back to top]

Customizing Look and Feel

The linkfeeds_by_date.php and linkfeeds_by_name.php template files each contain a call to a PHP display function. These functions are parameterized to allow customization of things like date format, number of posts, and link categories displayed. Within each template file, there is an explanation of all the arguments of the display function and their default values. If you’re not familiar with PHP function arguments, read the Wordpress How-To. The display_feeds_by_date() function in the linkfeeds_by_date.php template has up to seven arguments. Each argument is explained below in the order of specification.

  1. Number of posts to display at a time. default = 10
  2. Name of link category, or array of link category names to be displayed. Multiple categories can be specified like array('friends','enemies'). You can also display all categories by specifying the value -1. default = 'Friends'
  3. Index of post to display first. 0 is most recent post. This argument should not need to be modified. default = 0
  4. Displays the full content of each post when true, else displays summary. default = true
  5. Includes a feed image if available when true. default = true
  6. Displays navigation links to older and newer posts when true. default = false
  7. Format string for post date of each post, used as parameter for strftime(). default = '%A %B, %d %Y %I:%M %p %Z

If your look and feel problems go beyond the display functions, there are three places to look: The HTML and code in the template file you are using, the styles in the current theme’s style.css file and the HTML generated by the display function. First, take a look at your styles in style.css and HTML in the template file (e.g. linkfeeds_by_date.php) to see if the problems can be fixed there.

If the problem lies in the HTML generated by the display function, your best option is to forego using the current template and display function and use the custom_linkfeeds_by_date.php template, which allows the customization of how the HTML is generated for each feed post. This approach is only recommended for those comfortable editing PHP code.

Customization Questions

How do I “hide” a link from displaying its posts while keeping it in my links?

Update the link in the admin UI and make it not visible.

[back to top]

Got Problems?

When I install or upgrade WP, I get an error on my main Admin Dashboard (or a blank dashboard) once the plugin is activated.

This is because WP 1.5.x and 2.0.x include an older version of MagpieRSS (version 0.51). The index.php page in the wp-admin directory includes the rss-functions.php file which is essentially MagpieRSS 0.51. Just comment out the line that includes this file (with ‘//’) in index.php.

To permanently solve this problem I’d have to change all class-function, file and constant names in FRA’s version of MagpieRSS. I considered doing this, but decided not to in favor of waiting until WP is released with a newer version of MagpieRSS. Unfortunately, if you have other plugins that include/require rss-functions.php, then you’d have to comment out the include/require line in those plugin files (and possibly add an include of FRA’s version of MagpieRSS). It’s all very annoying.

When I view my page of link feeds, it loads slow or doesn’t fully load, sometimes leaving me with a blank page or page not found error.

This can happen on a page load when many or all RSS feeds are being initially retrieved or refreshed. PHP is configured to execute scripts for a maximum period of seconds, so if your script exceeds this period it will not fully load the page. For more information read the manual entry on maximum execution time. If you can’t configure php on the hosting server, you must address this issue with your hosting provider.

The best solution is to avoid RSS refreshes when the page loads altogether. To do this, you can use the wp-cron-refresh-cache.php plugin or you need to setup a cronjob that runs the refresh-rss-cache.php script periodically. Installation instructions are in each file which are located in the main friends-rss and scripts directories, respectively.

I get “Warning: MagpieRSS: …” warning messages when I view my feed page. How can I get rid of them?

These warnings are usually a result of a badly-formed feed or bad feed URL. If you find these messages just plain annoying, you can stop them from displaying by uncommenting the //error_reporting(E_USER_ERROR); line in friends-rss.php.

All my feed dates are showing up in 1969 (or something equally old). What a year!!!!

That probably because the feeds you are fetching and parsing don’t have a date associated with each post/item. There’s not much you can do about this if you don’t have control over the feed, other than ask the feed owner.

[back to top]