Overview
The purpose of this document is to help you get your first Blogroll Z up and running. I will also spend a little time with how to get it prepared for use by all of your friends.
Getting Blogroll Z
You can download the current version from my download page. You can also email me at zeptoblog at zeptoworld dot com.
Installing Blogroll Z
To install the software all you have to do is unzip the file and drop all of the contents into the directory from which it will run. This will give you a working version, but you will need to make some adjustments before you give access to the public.
Setting Up Blogroll Z
Cache
There are a couple of things that need to be done before Blogroll Z is ready for primetime. First is the cache. The first time that Blogroll Z reads a feed, it creates a cached version of the feed. The cache is much faster to read on subsequent requests for the same feed and if we didn’t cache the feed then your site would likely get banned from many blogs for fetching the feed too often. The cache is set to refresh each feed on an hourly basis. I will address how to change that in the Fine Tuning section. You will need to set the feed location in the ma.props file which can be found in the config directory. There is a parameter in the ma.props file called cacheDirectory set this to a directory that can be written to by the web server. You will be able to tell if it works if you see a set of files in that directory (after you run the app) with names that are made up of 32 character names (an md5 hash is used on the feed URI to get the cache file name.)
ma.props
Here are the parameters that you can set up in ma.props:
- summaryLength
- If you are going to display a summary from the feed, you will find that each feed has a different length. I added this parameter to allow you to set a uniform length for the summaries that you display on your page. Default value = 80 (characters)
- channelSliceSize
- This is the number of posts to return from the call to Channel->getSlice(). You can override this by providing a number as the first parameter of getSlice(10). Default value = 15. Use 0 to get all aggregated posts.
- feedSortSliceSize
- This is used to limit the number of posts that will be aggregated from each feed. Default value = 0. Use 0 to include all posts from each feed.
- cacheDirectory
- see Cache section above.
- useRedirect
- If this is set to true, ChannelItem->link will return a link that looks like the following: redirectfile?url=posturl&feedurl=feedurl&type=post/feed. The name of the redirectfile is the name specified by the redirect parameter in ma.props. You can use this to do preprocessing/logging of URLs when the user clicks on a link. Default value = false
- redirect
- The file to use in redirects. Default value = redirect.php
Fine Tuning
One thing that will really improve the performance of your site will be to not allow the cache to get updated by a user accessing the site. When you start getting a large number of feeds this can take quite a long time. It takes even longer if some of the feeds you are retrieving are not available and there are timeouts involved. To help with this I have included two php pages that you can use to update the cache: refresh.php and RefreshComments.php. refresh.php will run through the entire feedConfig.xml file and update all of the feeds. RefreshComments.php will only refresh the category with the name “comments” (you may want to refresh the comments aggregation more often than the posts.) What you can do is set up an automated process (e.g. cron) to access refresh.php on a schedule of your choice (be careful how often, some high volume servers will ban you if you fetch the feed too often.) If your schedule is less than the default 1 hour, then your users should never see the delay caused by refreshing the cache. To further protect your users from feed problems, you can add this line to the top of your php files:
define(’MAGPIE_CACHE_ONLY’, true);
This will tell the page to only use the cache and never try to fetch a feed directly.