Dynamically embedding ratings with RSS

General Information

MacUpdate utilizes RSS to make it easy for developers to keep track of the ratings for the products they have registered. This provides rating information in a generic way, allowing individual developers great flexibility and independence from any particular solution after dealing with the initial XML contents (which is itself well-defined because of the RSS standard's insistence that files be well-formed and valid).¹ XML parsing is supported by several languages and programming paradigms, letting the developer choose the manner and environment in which to proceed; this also means that RSS information can easily be included in almost any dynamically generated website within the paradigm and practices of the existing site (i.e., without requiring incorporation of a separate, additional language or module).

There are many ways the rating information for a particular product (or products) can be incorporated into an existing site. The recommendations and examples that follow are suggestions, minimal solutions, and cover a handful of common cases. They are by no means comprehensive with respect to the possibilities for handling RSS information, even within the context of the languages they represent.

Following the RSS 2.0 specification, information for each product is contained within an item element. For our purposes, the children of each such item are given as

The basic practice, then, is in most cases to parse the RSS file into some representative structure (an object, a hashtable, etc.), determine what the desired presentation is (i.e., what HTML you want to generate to present the results), write a corresponding function, method, subroutine, etc. to produce that HTML when provided an element of the representative structure, and then place the generative call (and necessary supporting code) in the site pages where output is desired. Below are explanations and examples utilizing PHP and Perl

Caching

In most cases, it is probably desirous to cache your ratings RSS file and periodically update it to include new rating information. Consider: using your RSS link to obtain the file at each and every processing point means retrieving the file remotely each and every time any page needs to parse it; if you include ratings embeddings on multiple pages, the server needs to obtain copies of the RSS file for every view of every page—this could potentially be a lot of redundancy (for your servers and for ours!). Most likely your needs can be served perfectly well by periodically (say, every few hours) obtaining a new, updated copy of your RSS file, storing it locally, and using the local version within your processing.

The above listings show two ways of performing such caching. Both are callable, e.g., from cron (for more information, see the manpage for crontab on Unix systems). The first example uses cURL to retrieve the contents; you should change the first filepath (/path/to/store/rss/) to match the location at which you want to cache the file, and name the file accordingly (yourRSS.xml is just our suggestion). The URI that follows should be the URI at the top of this file, which includes your ID key necessary to generate the proper file (NB: if no such URI appears at the top of this file, or if the page says it cannot be generated, check to make sure that you're logged in appropriately; this link is only available to registered, logged-in developers). The second listing is a brief Perl script which obtains the RSS file and writes it out to another file; you should modify the script to reflect the destination location, filename, and RSS URI accordingly. If the desired behavior is just to obtain a copy of the RSS file, cURL probably provides the simpler solution; however, the Perl solution allows for any additional processing or ancillary behavior that might be necessary (for example, if you already use RSS in other areas of your site but use a different specification—say, from the RDF family—the XML::RSS module provides for converting between specifications). Caveat emptor.

Legal Disclaimer

Source may be freely copied (links to complete files are included below) and modified for the purposes of embedding this information into an external website; files may not be redistributed or utilized in other ways without prior and express written permission of MacUpdate.

PHP

Probably the simplest way of incorporating RSS-based ratings into a site is by using PHP. As a developer, you will find a link to your RSS file above; in order to retrieve the contents, you can take advantage of the built-in PHP XML processing (based on Clark's expat processor).²

First, you may want to download a copy of the MURatingsParser class (we assume for the purpose of this example that you'll download this into the same directory that the PHP page in which you plan to include the rating information is located). Then, in the page you've written, the following code can be used to manipulate the contents of the RSS file into a PHP object.³

You should also define a function which is responsible for the way you want the results to appear on the page. The listing below contains an example of such a function (you are free to use this function—you'll find it in the download section below—or to modify it as necessary to suit your purposes). As defined in this listing, the function is intended to be called with its argument as a single item from the parser object defined above.⁴

With this function definition, we can look at a handful of ways to use a MURatingsParser object that has been initialized and contains the contents of a given RSS file. For the purposes of the following examples, assume that we've instantiated and initialized the contents of an MURatingsParser as above, and so we have a non-trivial object called $theParser. Because our definition of write_item() returns a string instead of writing it out (e.g., with echo), we must write out the return value ourselves if we want to display the results where we make the function call.⁵

In the first example, we retrieve an item from our MURatingsParser object via the method ratingForTitle(), which expects a string that is the name of a product for which there is rating information in the RSS file.⁶ The item matching that title is returned from the object, and given to write_item(), which produces a string of HTML (according to the definition of the function), which is then written into the page (via echo) at that spot (to delay output of the HTML produced by the function, e.g. to place it somewhere else, viz. note 5). The output from this simple implementation looks like this (note, this only writes the rating value as a number and as a star sequence, and a link to the MacUpdate info page for the item):

(4.6)

MacUpdate

The next example uses the method ratingsList() to retrive a list of all the items in the object. The optional argument (which defaults to true) forces the returned array to use the titles of the items for the indices of the array, instead of generating numerical indices; this allows us to access individual elements of the returned list by title string instead of by position in the array. This example, then, produces exactly the same output as the first example, although it also assigns to a script variable the entire list of items; this may be useful if we wanted to call write_item() on more than one item.

If we wanted to display information for every item (e.g., the results of write_item()), the following two examples show the canonical way. In particular, because ratingsList() always returns a list of elements (even if there is only a single item), it is a suitable array value for foreach, which provides a straightforward way to do something to each element in the returned array. Because we have explicitly specified that we want the array to be indexed by title (by passing true to ratingsList()), we can iterate over the keys and values of the array (to make it more convenient to access the title of each element).⁷ In the first of these examples, we simply iterate through the entire array, writing a DIV with each item name (between the H4 tags) and the result of calling write_item() on that item (as above). For the second iteration example, we check the rating value to make sure it's greater than 3, and only output the results of write_item() when this is the case. Of course, it is possible to perform arbitrarily complicated processing on items, either to determine whether they should be displayed or not, or to transform results in any way desired.

These are only a few of the ways to work with the contents of your RSS file in PHP. As mentioned above, hopefully these examples are helpful, but they are not normative. Ideally, the structure of MURatingsParser is flexible enough that it lends itself to whatever your particular programming style or site design guidelines are. Feel free to customize its behavior, as well as to define write_item() (or whatever display mechanism is most appropriate for you) however it best meets your design goals.

Files

If you intend to use MURatingsParser to handle the processing of your RSS file, you should download a copy of that file and include it in each page that you want to use an instantiation in (via require_once or include_once statements). If there are multiple pages within which you would like to display the results of a write_item() call, you might wish to define the function in an external file and include it in each page as appropriate. Toward that end, we offer a PHP file containing just the example definition as given above (which you're free to modify); you can download this file and include it on each page (this will save you from needing to define the function again on every page in which you'd like to use it).

Remember, we offer MURatingsParser as a convenience. There are many ways to handle XML in PHP, and some might be more appropriate for your particular needs. As always, if our parser object does not seem to support your needs, you are encouraged to consult the PHP XML documentation.

Perl

In order to simplify handling of RSS in Perl (and so as not to reinvent perfectly good wheels), we suggest (and the following examples assume) utilizing several commonly-available modules.⁸ In particular, we utilize LWP::Simple for retrieval of the RSS file (this module contains all the behavior necessary for fetching the contents of the file—if you require more robust functionality, we encourage you to consider the full LWP module); actual parsing is handled by the XML::RSS module, which is capable of reading and producing RSS files—this makes it especially well-suited for periodically caching your dynamically-generated RSS file (see above). For the purposes of our example implementation of write_item, we also take advantage of Math::Round, although such functionality is not necessary and may just as easily be accounted for in other ways that depend only on the Perl core.

In addition to use-ing each of the modules mentioned above, for the purposes of the examples that follow, we assume use strict. You may, or may not, use such a directive at your discretion, but the following examples are all valid within the strict parsing rules so as to ensure the widest range of compatability.

The first step to incorporating the ratings results into a Perl-generated page is to create a new parser, get the contents of your dynamically-generated RSS file, and parse the RSS file. The following listing shows the Perl for performing that sequence of actions.

Once you've parsed the contents of the RSS file, we recommend handling output in a way similar to the PHP examples above. In particular, we suggest defining a subroutine (say) write_item, responsible for displaying the contents of a particuar item as determined by the parser object. The XML::RSS object stores items as a hash whose keys are the names of the constitutive elements (see the table above), so a display subroutine should probably expect to recieve a reference to a hash, from which it can access the particular items we wish to display. In the example that follows, note the use of Math::Round for part of the calculations.

It is worth noting that this example returns a string result, suitable for writing as a fragment into an HTML page. It does not write the results into the page itself; you must print the results of this call yourself to include them in the page contents (see note 5 for more, mutatis mutandis).

In order to facilitate getting the information for a particular item, we include in the next listing another subroutine, itemForTitle, which returns the element of the items hash from the parser object for which the RSS title element matches the argument. This behaves in a way analogous to the method ratingForTitle() on the PHP class MURatingsParser above. Along with this utility definition, we provide a couple of examples utilizing write_item as defined above.

The manner in which you utilize the examples above will depend in a large way on how you use Perl to generate content. The most straightforward way (and the way that we follow in our example below) is to include everything in the listings above in the Perl script where you would like to generate the result text. If you plan to include results from the RSS file in multiple pages, you may wish instead to include the definitions of the subroutines in a separate file that can be included on the pages for which you want to generate output, separately from the Perl that actually gets the contents of the RSS file and parses the RSS into a workable representation.

You might also wish to consider the section on general implementation details, above. Particularly if you plan to include calculated statistics on multiple pages, you should look at the section on caching and periodically updating the RSS file, so that you don't have to generate and parse the information every time you need it (i.e., on every page load).

Downloads