 |
||
PUBLISHING RSS FEEDS
Activating A Custom RSS Feed
Now that you have created an RSS feed you need to publish it so that the world can gain access to it. Click on the Activate Feeds link in the navigation bar of the same page from which you have been working. This brings up a list of RSS feeds. Feeds that have been activated are represented as links that lead to the page displaying the published feed. For those not yet activated there is a checkbox to the right of each feed. Select the feed for activation, and click on Activate Selected Feeds at the bottom of the page. Follow the new link to the published feed to see what your visitors will be presented with. Of course, if your RSS feed is empty (because no reviews match the criteria used to select items for the feed) your visitors are going to feel cheated, so be sure to create feeds that have at least a few items in them.
Each time a feed is activated (or deactivated) the RSS Syndication page is rewritten. This is a static page on your site that lists every activated custom RSS feed (those you can generate from the Configure > RSS Management page), and this is the page to which visitors should be redirected in general when they are seeking information about RSS feeds on your site (or at least the RSS feeds generated by Review Foundry). Every activated feed has its own XSL stylesheet page, and links to the Syndication page. You can find the RSS feeds in the section of your document root that contains Review Foundry documentation and images. In particular, look for the /rss subdirectory of your /foundry directory.
If you should need to remove a custom RSS feed from publication, simply deactivate it. You can then reactivate it at a later stage if needed. To destroy the RSS feed record itself, see the Remove Feed link in the navigation bar. Removing an RSS feed causes the feed information to be deleted from the RSS table.
Once a feed is activated it can be regularly updated by using the rss_reviews.pl script found in the /admin directory:
perl reviews_rss.pl
This will update ALL activated custom RSS feeds on your site and rebuild the Syndication page. You might also want to set this script to run as a weekly cron job.
Viewing A Custom RSS Feed
Once you have created a custom RSS feed and published it (i.e. activated it), the feed can be reached from the Syndication page on your site. Of course, plain RSS markup is not particulary human-friendly. If you send a reader to an RSS page and they aren't familiar with RSS markup they will likely think they are looking at a non-functional page on your site. It will seem like garbage to them. Instead, what you really want to do is present the information in an easy-to-digest format.
There are several ways of going about the problem, but they all boil down to 2 steps. First you need to apply a parser to the RSS feed to extract the information it contains. Next you need to use a formatter to render that information in a manner that is easy to comprehend. Only two specific ways of going about this are discussed here, but they are the most commonly used methods of dealing with an RSS feed. The first method, outlined below, involves using a PHP script to do the work, and is the method used to format RSS feeds so that somebody can add the content of your feed directly to their site. The second method (which is generally used to display the content of an RSS feed on your own site without generating an alernate HTML-formatted page) harnesses the ability of your browser to handle XSL instructions.
So both methods of viewing the content of an RSS feed are useful. It just depends on the context in which you are viewing the feed as to whether you will be doing it one way or the other. Review Foundry has XSL templates already created for use, and it has PHP scripts available to format feeds so that other people can insert an HTML version of the feed into their own web pages. Those methods are discussed in the following sections.
Adding Your RSS Feeds To Another Person's Webpage
As mentioned above, XSL templates for stylesheets are available for all RSS feeds generated by Review Foundry. That means when you offer an RSS subscription icon on your Review Foundry pages for a user to click on (these icons are automatically added to your pages when a feed is available), the resulting page they see in their browser is a nicely formatted one with all the RSS feed items tidily presented.
This is fine for those who might want to subscribe to the feeds on your site. But what about someone who wants to take a feed from your site and insert it into their own web page? In that case, the XSL stylesheet is of no use to them because browsers will only apply a stylesheet to a pure XML document, not an XML document (like an RSS feed) inserted into a web page. So either they have to format that feed themselves, or you have to provide a means for it to be formatted for them. Of course, that means YOU have to format it for them. After all, it's your feed. Your client isn't going to want to do the work for you.
So what tools are available to help you with this?
There are several scripts that one can get one's hands on for formatting RSS feeds. Some of these are javascript-based, but since search engines won't index any information generated via javascript, we can rule those out as a possible method for adding RSS feeds to your client's web pages. This leaves scripts that retrieve the RSS feed information, format it as HTML, and insert it directly into the client's page. As most web pages these days seem to be PHP based, we'll restrict our discussion in the following sections to PHP methods, though in fact since all the formatting is going to take place on your server the fact that we are discussing PHP is not so important. I'm going to give you PHP solutions, but you could replace these with alternate non-PHP solutions if you have a preference for another language and an understanding of how to parse and format XML feeds in general.
Our goal is to create a script that you can place on your own site (the site that hosts Review Foundry) which will format any RSS feed that that the user has requested from your site. Actually, we'll come up with a few script variants since there are a number of different kinds of RSS feeds that you can generate using Review Foundry.
Generally such scripts are called in the following way:
rss_script.php?url=/some/path/to/rss_feed.xml
In other words, you are hosting the script rss_script.php, the user is requesting the RSS feed located on your site at /some/path/to/rss_feed.xml, and they are expecting to get back a page of nicely formatted information that can just be added directly to their web page without any trouble.
So, jumping ahead for a moment and supposing that the script already exists, here's one way the client might grab the formatted feed from your site and add it to an existing PHP page on their site:
<table width="600" style="border: 1px solid #dddddd; padding: 10px;"><tr><td>
<?php
$rss_feed_url = 'http://yoursite.com/rss_script.php?url=/some/path/to/rss_feed.xml';
display_remote_file($rss_feed_url);
function display_remote_file($file)
{
$path = parse_url($file);
$fs = @fsockopen($path['host'], 80);
if ($fs) {
$header = 'GET ' . $file . ' HTTP/1.0' . "\n";
$header .= 'Host: ' . $path['host'] . "\n\n";
fwrite($fs, $header);
$buffer = '';
while ($tmp = fread($fs, 1024)) { $buffer .= $tmp; }
$matches = split( "\r?\n\r?\n", $buffer, 2);
print $matches[1];
}
return;
}
?>
</td></tr></table>
That's the code you might hand out to clients wanting to access pre-formatted RSS feeds. They might come up with some code of their own, but it will nonetheless do the same job: retrieve the feed from your site, and add the HTML to some cordoned off part of their page (which is a table cell in the above code).
Formatting An RSS Feed With PHP And MagpieRSS
One well-known and handy PHP utility for parsing RSS feeds is known as MagpieRSS.
This RSS manipulation library can be incorporated into a simple PHP script (the rss_script.php script that is referenced above). The script will reads a specified RSS feed and make the information in the feed accessible as a structured PHP array. If you know a little PHP, the rest of the job--converting the PHP array of information into an HTML representation of the data--is fairly easy.
Here are a couple of PHP scripts that, with some minor adjustments, can be used to parse the custom RSS feeds produced by Review Foundry (since those feeds are fairly simple in construction):
- reviews_rss.php -- formats custom rss review feeds
- review_items_rss.php -- formats custom review item feeds
To use either of these scripts, download and install MagpieRSS, then simply call them in your browser address bar and add a query string paramter named url which specifies the path to the relevant custom RSS feed to be parsed. For example
review_items_rss.php?url=/some/path/to/foundry/rss_feed.xml
The main line of code (found near the top of the file) that needs to be changed in each of these files to accommodate your own site is this one, which should specify your own domain:
$rss_domain = 'http://www.mydomain.com';
These PHP scripts are very useful. You can hand out their URLs to anyone who wants to add your feeds to their own website.
Another PHP-based method for parsing and formatting an RSS feed will be discussed in a later section, where the generation of RSS feeds in bulk is discussed.
Formatting An RSS Feed With XSL
Although you probably don't need to give it too much thought (since it works out of the box anyway) the page your visitor sees when they click on an RSS feed link is one that has had an XSL stylesheet applied to it. The use of XSL, which stands for XML Style Language, is a very convenient means for formatting RSS feeds, since it leaves the underlying RSS document untouched. The downside of XSL is that it is a very difficult markup language to learn. But seeing that your RSS pages are formatted with it, it is worth spending a moment to let you know roughly how it works.
In each of the RSS feeds generated by Review Foundry is a line of code that specifies the location of an XSL stylesheet file. When a browser reads the RSS feed, it sees that an XSL stylesheet file is also available and fetches it. It then uses the markup in the XSL file to generate the HTML needed to display the information in the feed in a suitable way. So if you look at the underlying code at the top of any Review Foundry-generated feed you will see a line like this:
<?xml-stylesheet title="XSL_formatting" type="text/xsl" href="/some/path/to/foundry/rss/stylesheets/rss_stylesheet_item_review.xsl" ?>
As already mentioned, XSL is NOT a simple markup language, and it requires some effort to master. The primary advantage to using an XSL stylesheet is that no work need be done on your server to render the feed. It is all done by the visitor's browser. Furthermore, no transformation need be applied directly to the RSS feed in order to display it. The feed itself remains untouched and easily parsable by other RSS client applications, like RSS feed newsreaders.
However, one very serious problem with relying on XSL formatting is that the browser will only take notice of the stylesheet in a very restricted instance. Generally, unless the document is a pure XML document with an attached stylesheet, the browser will ignore the stylesheet. So if you just insert an entire RSS feed with an attached stylesheet into an existing web page, you won't get a nicely formatted feed. Far from it.
The ONLY way I have found so far to pull an RSS feed into an existing web page, in such a way that the XSL formatting IS preserved, is to use an iframe. However, this method requires that you specify both the width and height of the region within which the feed will appear. The end result is that there can be lots of whitespace added to the web page if the maximum number of displayed reviews has not been reached. Here's a example of how you might pull such a feed into an existing webpage:
<div align=center> <iframe style="border: 1px solid #dddddd; padding:20px;" src="http://yourdomain.com/path/to/some/latest_reviews_rss.xml" width="600" height="1000" frameborder="0"></iframe> </div>
This assumes that the RSS feed has an attached XSL stylesheet which is retrieved and used by the browser. It's a simple method, but it suffers from the whitespace problem I mentioned above, since to work well, the formatted feed would have to fit exactly into the 1000px tall iframe that sits on the web page.
Building RSS Feeds In Bulk
When you need to generate an RSS feed of latest reviews for ALL the Items, Members, or Suppliers in your database, the way to do it is to use the general static page building mechanism offered either from the Build control panel, or via the command line. Building is discussed elsewhere in this user manual.
The important thing to realize is that if you are going to build RSS feeds in bulk, you need to announce your intention to the application by enabling the relevant build plan option. This is the plan, as Review Foundry understands it, for the build process overall. It maps out the assumptions that can be made about what should and should not be built. If you want to build RSS feeds for all your Items, but you don't want to build static pages as well, then your build plan should be configured this way:
This configuration allows you to offer only dynamic pages for the Category branch, but nonetheless have static RSS feeds of latest reviews for all Items. The same applies to setting the build plan options for the Team and Yellowpage branches.
If you want to build an RSS feed of latest reviews written by a member, for ALL members in your database, but don't want to build static pages for the profiles themselves, set the following options to affect the way in which a Member Profile build is carried out:
It goes without saying that if you also want the static pages to be built, you simply toggle the first option in both of the configuration setups shown above.
Note that once you start building RSS feeds in bulk you probably want to arrange to perform the builds regularly as a cron job. Doing so is discussed in the BUILDING PAGES section of the manual.
Formatting An RSS Feed With PHP And FoundryRSS
After adding to Review Foundry the code that produces bulk RSS feeds, which are somewhat more complex in construction than the one-off custom feeds, it occurred to me that I could incorporate an XML parser that I had recently completed. I'll refer to this as FoundryRSS, since it's a reasonable alternative to using MagpieRSS.
One of the useful things about FoundryRSS is that it is actually a general XML parser, so we can embellish the format of an RSS feed and still expect to be able to parse it without difficulty.
The XSL stylesheets for the bulk RSS feeds generated by Review Foundry are fairly complex. The reason for this is that the feeds themselves are quite complex. In turn, the reason for the feed complexity is that when these feeds appear on another site, they are likely being used to display reviews of a business or service, and that business or service is going to expect your feeds to be a cut above the rest, otherwise why would they incorporate your feed into their commercial web pages? They might even be paying you money to take those feeds.
So from your perspective there needs to be a way to easily reformat the feeds. It should be easy to add or subtract elements (e.g. include or exclude member avatars in the reviews).
The end user cannot influence which elements appear in the feed when the formatting is done with an XSL stylesheet (because generally they have no control over the stylesheet). But if the feed formatting is done by a script that is invoked by the user, then it is a simple matter to add query string parameters to the script invocation and have those parameters determine what appears in the feed. So that's the outcome we are looking for here.
Here's what an RSS feed formatting script, and its associated Smarty template, might look like using FoundryRSS:
- thing_reviews_rss.php -- script to parse a bulk rss review feed
- rss_reviews_single_thing.tpl -- template to format a bulk rss review feed
As you can see, the script itself is very simple. That's because the all of the formatting logic is contained in the template. On the one hand, templates which are as involved as the one referred to above tend to be somewhat overwhelming when you first see them. On the other hand, they provide you will a lot of power and flexibility. The template above has been formatted so that many different components of the feed can be switched on or off via the query string. Here's a list of all the extra query string parameters that can be supplied (all of which, except the list size parameter, take a value of 0 (zero) or 1 (one) to toggle the feature):
max_items header header_title header_image header_summary header_summary_label header_submit_review report_review reviewer_byline average_rating average_rating_image average_rating_numeric attribute_ratings avatars pros cons review_text read_more image_frames
So, for example, if the user wanted to add the formatted RSS feed to their web page, but did not wish for member avatars, the "cons" component, or the individual ratings breakdown by attribute to appear for each review, they would add the following query string parameters when invoking bulk_reviews_rss.php
avatars=0&cons=0&attribute_ratings=0
The default state for all these features can be configured in the template. You might decide to switch off the attribute_ratings component, so that it is only added when a user specifically requests it, in which case they would add it to their request. If you had also removed the main image shown in the header section, they could switch that on too by specifically requesting it:
header_image=1&attribute_ratings=1
Of course, you will have to make your users aware of what the possibilities are if you wish for them to take control of their formatting needs.
Accommodating Smarty
One thing you will notice when you get around to inspecting the Smarty templates carefully is that XML variables that derive from a namespace such as c: or g:, say, appear in the template with the colon replaced by an underscore. So for example, if <c:hat_size>6B</c:hat_size> appeared in the RSS feed, the corresponding variable in the template would be referred to as c_hat_size. This is simply because Smarty does not accommodate the colon in its variable names. So keep that in mind. Generally, though, this is not a problem, provided you are aware of it when editing the templates.
Another thing you might notice when editing the Smarty templates is the tag delimiters. The default tag delimiters for Smarty are curly braces, so that { hat_size } is the tag used to invoke the value of the variable named hat_size. I prefer the Template Toolkit tag delimiter style of [% hat_size %] when working with templates, so that's what you'll find in Review Foundry Smarty templates. So be aware that while the tag delimiters are the same in these Smarty templates, the templating language is different. In my opinion Smarty is a lot more difficult to use than the Template Toolkit, but it's the best templating system to use if you are dealing with PHP.
FoundryRSS Scripts
Because there are a number of possible RSS feed types possible with Review Foundry it is easy to get confused about what RSS feed parser and template you ought to use for a given job. Here are sample scripts and templates that you can use:
Format a bulk RSS feed of reviews for a SINGLE Item, Member, or Supplier: script: /rs/foundry/skins/default/php/rss/thing_reviews_rss.php Format a custom RSS feed of reviews for MULTIPLE Items, Members, or Suppliers: script: /rs/foundry/skins/default/php/rss/reviews_of_things_rss.php Format a bulk RSS feed of reviews from a SINGLE Member: script: /rs/foundry/skins/default/php/rss/reviews_from_member_rss.php Format a custom RSS feed of MULTIPLE Items, Members, or Suppliers: script: /rs/foundry/skins/default/php/rss/things_feed_rss.php
You can take a copy of any of these scripts and place the script anywhere on your site that is convenient for your site users (the ones who want to incorporate your feeds into their pages). Perhaps you'll want to add the script(s) to your document root so as to make the RSS feed retrieval URL short. You can also rename any of these scripts to anything that is convenient.
Just be sure to edit the lines in the script that specify the paths to your /my directory in your CGI bin area, and the /_lib directory in your document root area (this is the PHP /_lib directory and NOT the /_lib directory in your CGI bin area, which handles the Perl side of the application).
IMPORTANT
Each of these scripts differs only in the Smarty template used to format the RSS feed. The feed itself is specified by the caller (using the url parameter), and is expected to be of the correct type. For example, if you attempted to use the things_feed_rss.php script to format an RSS feed of reviews from a specified member (review author) you would not get the exact result you are hoping for, since the reviews_from_member_rss.php script is specifically tailored to handle that case (and uses the template for formatting reviews from a single member). Therefore, if you get an oddly-formatted result when using any of these scripts, the first thing you should check is whether you are matching the correct script to the RSS feed that you are trying to parse and format.
Next Section: CUSTOMIZING RSS FEEDS
Copyright © 2004 Random Mouse Software. All Rights Reserved.