# CaféRSS (1.0)

CaféRSS is a simple RSS aggregator that's quite easy to integrate into your pages.
It supports RSS 0.9, 0.91, and 0.92 feeds (and RSS 0.93 shall work in a later version).
To 'install' it, just upload everything on your server, and do CHMOD 777 on the cafeRSS_cache directory so that you can use the caching.

## Usage

include('cafeRSS.php');
$rss = new cafeRSS();
$rss->display('http://example.com/rssfeed.xml');

This is the most simple way to use it. The display function makes the script render an RSS feed from an URL or a string if you pass it a string.

To set an option, use the assign function.

$rss->assign('items', 5); // would display only up to 5 items

Here are the options you can set:

- items : number, or 'all' (default is 'all')
- template_string : string that defines the template (default is an empty string, so CaféRSS would use the template file)
- template_file: URL or path to a template (default is 'cafeRSS_template.txt')
- use_cache : 0, 1 for OFF/ON (default is 0)
- cache_dir : path to a directory where the cached RSS feeds will reside; directory needs to be CHMOD 777 (default is 'cafeRSS_cache')
- refresh_time : number of seconds after which a cached feed is expired (default is 900, which is 15 minutes)
- echo : 0, 1 for OFF/ON, states whether it will echo the rendering or not, in the latter case it would return the rendering as a string (default is 1)
- debug : 0, 1 for OFF/ON, outputs some debug info (default is 0)

Hint: caching is strongly advised ;)
For example, if you want to display only 5 items and cache the RSS feed in a directory named 'mycache', here goes:

$rss = new cafeRSS();
$rss->assign('items', 5);
$rss->assign('use_cache', 1);
$rss->assign('cache_dir', 'mycache');
$rss->display('http://example.com/rssfeed.xml');

You can also make use $rss->display('somelocalrssfile.xml'); to use a local RSS file instead of a remote one.
Check example.php for a simple example of using this script.

## Template

You can modify the template used to render the RSS feed, and/or create new templates.

There are 2 template tags, and 14 template variables.
Template tags start like this: {tag}, and end like this: {/tag}. Template variables are like this: {$variable}.

Tags:

- {rss_image} if there is an image in the feed (using the <image> section), the section between the {rss_image} and {/rss_image} tags will be displayed; if there is no <image>, the section will be ignored.
- {rss_items} defines a loop to display all the RSS <item> tags and their contents.

Variables that go in the {rss_image} (<image>) section:

- {$rss_image_url} displays the content of the <url> tag
- {$rss_image_title} displays the content of the <title> tag
- {$rss_image_link} displays the content of the <link> tag

Variables that go in the {rss_items} section:

- {$rss_item_title} displays the content of the <title> tag
- {$rss_item_link} displays the content of the <link> tag
- {$rss_item_description} displays the content of the <description> tag

Variables that go outside of these sections (the headers of the RSS feed) :

- {$rss_title} displays the content of the <title> tag
- {$rss_link} displays the content of the <link> tag
- {$rss_description} displays the content of the <description> tag
- {$rss_lastBuildDate} displays the content of the <lastBuildDate> tag
- {$rss_docs} displays the content of the <docs> tag
- {$rss_managingEditor} displays the content of the <managingEditor> tag
- {$rss_webMaster} displays the content of the <webMaster> tag
- {$rss_language} displays the content of the <language> tag

You can check the default template file cafeRSS_template.txt for a simple example of a template.

## Notes

If you don't use the use_cache option, don't complain the script takes long to fetch the files :P
One good thing to optimise the time it takes, is to set a cronjob to fetch the RSS feed and then use the script to render the local copy of it, in which case you needn't use caching.
You can also use this class several times in the same script and/or change its options around, for different feeds' URLs and templates.
If you have any comment or suggestion, or want to tell me you got CaféRSS up on your website, email me: m at tidakada.com

CaféRSS is ©2002 Michel Valdrighi - m at tidakada.com - http://tidakada.com
CaféRSS is released under the GPL (see license.txt)
You can download a new version on http://tidakada.com/cafeRSS/

Have fun !