Overview
After working on your Jamroom System for a while, you may decide that you would like to implement an RSS Feed for something that Jamroom does not seem to support "out of the box". Initially, Jamroom comes with RSS support for your Artist and Member Blogs, but following this guide, and a small amount of template work, you can create an RSS Feed for almost any item in your Jamroom.
Step 1 - Decide what you want in an RSS Feed
The first step in the creating your new RSS Feed is to decide what you want to become an RSS Feed. While most of the instructions for creating a new RSS Feed are "generic" (meaning that they work for every type of feed) the "content" of the Feed will likely vary depending on if you are providing an RSS Feed of the latest "gig events," or a feed of the latest "reviews" posted to a profile page. Likely you already have an idea of what you want to implement as an RSS Feed, so the next step is to create a small script for your Jamroom that will provide the proper XML "header" information that is needed by some RSS Readers.
To illustrate how creating the custom RSS Feed works, we'll use an example of creating an RSS Feed of the 10 latest "Events" from all artist profiles.
Step 2 - Create the RSS/XML Wrapper script
The next step in creating your RSS Feed, is to create a small "wrapper" script that will be the actual "file" that the RSS reader calls to get the custom feed. Here's what it would look like based on our example:
rss_event.php:
<?php
//----------------------------------------
// Jamroom RSS Feed Creator Wrapper module
//----------------------------------------
require('include/jamroom-include.inc.php');
// These header calls are required to get the browser to see this as an RSS Feed
header('Expires: '. gmdate('D, d M Y H:i:s', time()) .' GMT');
header('Last-Modified: '. gmdate('D, d M Y H:i:s') .' GMT');
header('Content-Type: application/xml; charset=utf-8');
// The $base_url variable holds the URL to the ranking system
$base_url = $jamroom['jm_htm'] .'/ranking.php?mode=event&order=1&show=10';
// now we define which templates we will use for each part
$head_tpl = 'rss_event_header.tpl';
$row_tpl = 'rss_event_row.tpl';
$foot_tpl = 'rss_common_footer.tpl';
// Now run jrCallUrl to actually run the ranking system call
echo jrCallUrl($base_url .'&header_template='. $head_tpl .'&row_template='. $row_tpl .'&footer_template='. $foot_tpl);
?> |
Save this file as "rss_event.php" and place it in your Jamroom directory. This is the file that you would "advertise" as your RSS Feed, and it must be a PHP file (i.e. have a .php extension) or it will not be executed properly by your web server. Note that the "work" is being done on the last line of the script - the "ranking.php" script is being called to get the data we need to populate the RSS Feed. You would want to substitute the ranking.php script call with the script call you would want to make an RSS Feed from (i.e. search.php, chart.php, playlist.php, etc. - many different Jamroom scripts can be used, as long as they accept a header_template, row_template and footer_template argument).
If you plan on implementing multiple RSS Feeds, you'll want to create an individual wrapper script (modeled on the example above) for each RSS Feed "type" you wish to have.
Step 3 - Create the RSS Feed Templates
The next step is to create the actual header/row/footer templates that will construct the XML that makes up our formatted RSS data. For the most part the "footer" template can a template you re-use for any type of RSS Feed you construct, since it does not (typically) change for the different types of data. However, you will want to customize your header and row templates based on the type of data you are showing. You will want to make sure and name your header and row templates accordingly so you understand their role in your Jamroom. For our example we will name our header template "rss_event_header.tpl" and the row template "rss_event_row.tpl". Our footer template will be named "rss_common_footer.tpl" to show that it is a "common" template and can be re-used by other RSS Feeds we may create. Make sure that if you change the name, you update the proper name in the rss_event.php file.
rss_event_header.tpl:
<?xml version="1.0"?>
<rss version="2.0">
<channel>
<title>{$system_name} - Upcoming Gigs</title>
<description>{$system_name} - a list of the next 10 upcoming Artist Gigs</description>
<language>en-us</language>
<link>{$JAMROOM_URL}</link>
<lastBuildDate>{$smarty.now|jr_date_format:"%a, %d %b %Y %T %Z"}</lastBuildDate>
<generator>Jamroom {$version}</generator> |
rss_event_row.tpl:
<item>
<title>{$BAND_NAME} - {$EVENT_TITLE|jr_strip_html}</title>
<link>{$ARTIST_URL}</link>
<description>{$EVENT_DESCRIPTION|jr_strip_html}</description>
</item> |
rss_common_footer.tpl:
Now that we have created the 3 necessary templates that will be used by the Jamroom Ranking System to create our RSS Feed, we are almost finished, and can now move to how you would "link" to your RSS Feed so that others can view it.
Note: The RSS Feed created by the above templates is a very simple RSS Feed - there are additional parameters that you can add to the XML templates that can convey additional information to your readers - for a more complete overview of what you can (and cannot) add to an RSS Feed, check out the Wikipedia entry on RSS.
Step 4 - Load your new RSS Feed in an RSS Feed Reader
Now that you have completed the steps necessary to deliver the RSS Feed, the last step is to give it a test in your favorite RSS Reader. If you are running the Firefox Web Browser 2.0 or newer, there is already built-in support for RSS Feeds via the "Add Live Bookmark" feature. Simply enter the following location into your "Location" bar in your browser:
http://yoursite.com/rss_event.php
And you will see your RSS Feed loaded up for you.
That's it - using the outline above, you can now create RSS Feeds for anything that Jamroom can "output" using the Jamroom Ranking System, the Jamroom Advanced Charts, the Jamroom Search, and any other Jamroom script that can be manipulated via the use of templates.
Additional Resources
If you have any questions on this guide, or would like to add comments or suggestions, please join us in the Jamroom User Support forums. Thanks!
|
