|
PULLING DATA WITH SSIAlthough Review Foundry is designed to be self contained--in the sense that you point users to a top page and subsequent pages are produced in response the user's clicks--there may be times when you don't want to send your site visitors directly to the Review Foundry pages. Instead, you might want the user to navigate the pages of an existing catalog on your site (or a remote site), but you'd like to pull into those pages some of the information captured in the Review Foundry database. A good example of this is the idea of Latest Reviews. You have a product page in your catalog and you send users to the Review Foundry review submission page whenever a user wants to submit a new review. Once those reviews are in the database you want to incorporate them back into your product page (possibly even a plain .shtml page which can be updated with information on the fly by issuing a server side include, or SSI, call). Review Foundry can accommodate you in situations like this. Before proceeding to tell you how to pull data using the SSI formalism of Review Foundry, a distinction needs to be made between the current method and the method of PULLING DATA WITH JSON. The current SSI method is suitable for relatively complex data structures that we want to insert into an existing page AND be indexable by the search engines. If you put HTML directly onto an existing page then it can be seen by the search engines. So reviews are a good example of that. We want them to be indexed. On the other hand, if we use javascript to do any of our data fetching, then the data is going to be invisible to the search engines, since search engines mostly ignore javascript. But using javascript can be more than useful. For example, on a category page we might have 20 items for which we need to retrieve average rating values. We need to make ONE CALL to retrieve the data, then spread it around our category page. We can do this fairly easily with javascript. Using literal SSI calls would require 20 separate calls and our page would take forever to load. So be sure to check out the section on PULLING DATA WITH JSON when it comes to adding information to existing category pages with MULTIPLE items on them. The current section is devoted to retrieve information about just ONE item. Depending on your system, an SSI call in general will look something like the following: <!--#include virtual="/cgi-bin/path/to/some_script.cgi"--> Note that the URL in the SSI call is relative to your document root, so you cannot fetch a page from another server. That's the normal state of affairs, anyway, your own particular server might allow fetching from remote servers, but probably not. Keep that in mind. This SSI call is inserted into your .shtml page (or any page that your web server will parse for SSI content) and is interpreted by the web server, when the page is requested, as a sub request to retrieve and insert into the page, the content of the script referenced in the SSI call--here, the script named some_script.cgi, which can be found at the location specified by the relative server URL shown in the call. Depending on your setup, it is posible that this call may require some alteration to have it execute properly (ask your web hosting company if you have problems with the SSI formalism). Fetching From A Remote SiteIf for some reason you cannot use an SSI call to grab data directly from the Foundry application there are alternatives. Let's say you want to pull Foundry content onto the pages on a remote server, and the SSI calls there only allow local pages to be pulled. In that case you can use an intermediate LOCAL script to do the page fetching for you. Your SSI call is to the local script, not directly to the Foundry script on the remote server. You will find 2 versions of a script to do this remote page fetching in the Foundry distribution. One is Perl based and uses the Perl LWP::Simple class to perform a network request. The other script is PHP based and uses either Curl or FSockOpen to do the fetching. You can find these in the following locations:
/cgi-bin/rs/foundry/do/get_page.cgi /rs/foundry/skins/default/php/get_page.php The PHP script might be the more efficient of the two. Use either one for your purposes if you need to. If you use either of these scripts, you'll supply them with exactly the same query string that you'd have used if you were calling the Foundry script reviews.cgi itself. For example: get_page.php?module=ssi_item&do=latest_items&size=3 The various query string invocations are discussed in the sections that follow. For all URLs discussed which contain the Foundry application reviews.cgi, replacement with get_page.cgi (or get_page.php) will in fact result in the same output (though a direct call to reviews.cgi is always more efficient). Again, if your SSI call originates on the same server (domain) that hosts the Foundry application, you don't need to use these intermediate scripts. You simply make direct SSI calls to the Foundry application itself (i.e. the reviews.cgi script). Another possibility may be that you cannot use SSI calls, but you can fetch remote web pages using some other formalism. For example, if your pages are generated via PHP you might be able to retrieve a Review Foundry page by making a call with the file_get_contents() method, or you might make use of the curl() library. Either way, you are simply requesting a page from Review Foundry that you are going to insert into your existing page. Specifying Records By ID or SKUIn the sections to follow you will see that record specification is done in terms of the value of the ID column in the Thing (i.e. Item, Member, or Supplier) and Container (Category, Team, or Yellow Page) tables. So if we where retrieving the supplier with record id Supplier.id = 333 from the yellowpage with Yellowpage.id = 35 then we would have the following string in our request: &supplier_id=333&yellowpage_id=35 This tells Review Foundry which record to retrieve, and which set of ratings to pull from (since rating attributes are container dependent). It may however be convenient to not have to specify the identity of the supplier in the Supplier table, and possibly the yellowpage identity in the Yellowpage table, but to provide identifiers that relate to a third party database (in other words, your own local databse). So you might be running software that pulls from tables named Product and Category. They might have ID fields of their own: Product.id and Category.id, but to distinguish them from Review Foundry field, we call them SKU values (for Store Keeping Unit). If you want to reference these SKU values instead, you can add an 'sku' column to the relevant Review Foundry table, and populate it with the corresponding value from your local table. So you might add a Supplier.sku column. You might also add a Yellowpage.sku column. This way you can, if you prefer, specify the supplier and yellowpage, like so: &supplier_sku=chair123&yellowpage_sku=kitchenstuff You can do this for one or both of the Review Foundry tables in question. If you do, be sure to add the 'sku' column as a VARCHAR column of some suitable length (say 32 characters). Again, using SKU values is not mandatory, and if you do use them you have to populate the relevant Review Foundry table with all the sku values that you might possibly use during a lookup. SKU values are always converted into Review Foundry thing IDs or container IDs before the required data (latest reviews, or what not) is retrieved, formatted, and returned to you. Note that IDs in Review Foundry are always integers. But given that it cannot be assumed of other applications that SKUs will likewise be integers, the sku columns you add to Review Foundry tables must be VARCHAR columns, so that any alphanumeric sku will be acceptable. If you use a column type of anything other than VARCHAR or CHAR to characterize skus in Review Foundry you may get unexpected (erroneous) results. Grabbing Latest ReviewsThere are 3 main types of latest reviews. Reviews can either be associated with a given Thing (i.e. Item, Member, or Supplier), or they can be associated with a given Container (Category, Team, or Yellow Page), or they are associated with NO particular Thing or Container, but they ARE associated with a particular Container Type--that is, you can ask for, say, the 4 latest Member reviews, the 3 latest Item reviews, or the 5 latest Supplier reviews. Here is how you do it:
For each review presented, if a thumbnail image exists for the corresponding Thing the thumbnail will appear with a summary of the review. This behavior changes when reviews are restricted to a given Thing.
For each review presented, if a thumbnail image exists for the corresponding Thing the thumbnail will appear with a summary of the review..
For each review presented, if a member avatar exists for the corresponding reviewer, the avatar will appear with a summary of the review. This is similar the manner in which reviews are presented on a Thing detail page.
For the compact format, the detailed breakdown of rating values associated with the review are dispensed with and an average rating is reported instead. This can significantly save on space, and is in line with the idea of presenting a "summary" of the latest reviews.
Grabbing Latest Items, Members, SuppliersIn addition to being able to grab the latest reviews, you can also grab the latest Item, Member, and Suppliers submissions. The calling protocol is virtually identical to the one used for latest reviews. The main difference is that the do parameter should be given one of the values latest_items, latest_members, or latest_reviews. The differences are spelled out below.
Grabbing Average RatingsIf all you want to do is add a graphical display of the average ratings for a thing (Item/Member/Supplier) to an existing page on your site, you can do so with one of the following SSI URLs: reviews.cgi?module=ssi_item&do=average_ratings&item_id=7&category_id=3 reviews.cgi?module=ssi_member&do=average_ratings&member_id=7&team_id=3 reviews.cgi?module=ssi_supplier&do=average_ratings&supplier_id=7&yellowpage_id=3 This will retrieve only the averages of all the things rating attributes for the container in question. This is useful if you want to connect your existing pages to your Review Foundry pages, and you do not want to display reviews on your existing pages for one reason or another. If you wish to also add, for comparison, the same quantities, but averaged over all things in the same container, add the following modifier: &compare=1 The SSI templates for pulling in these average ratings are the following: ssi_average_rating_item.ttml, ssi_average_rating_member.ttml, and ssi_average_rating_supplier.ttml Tiling OptionsTiling is covered in some detail in the tutorial How To Tile Review Records, but the options for altering the appearance of the tiled records are covered here. The main pair of query string variables that affect whether or not SSI data will appear in list or tiled format (that is, records are formatted across and down the page as tiles) are the format and tiled parameters: &format=compact &tiled=1 (or &tiled=0 to switch off any default tiling) In other words, you cannot activate tiling unless you are displaying the compact format for records. The next 2 parameters, which should be given as INTEGERS, control the number of tiles that appear in each row, and how many rows of records to format: &tiles_per_row=3 &num_tiled_rows=2 In the asbsence of query string parameters that specify otherwise, the width of an individual tile, and the spacing between tiles, are determined by the configuration values specified on the Configure > Build / Browse control panel. To override the defaults, you specify these directly: &width=200 &spacing=10 Note that to remove spacing entirely, so that the tiles are jammed together, you must explicitly set &spacing=0. Suppressing HTML TagsWhen content is served up by Review Foundry using the special SSI URLs outlined above, the generated HTML is self-contained. That is to say, it contains <HTML> and </HTML> tags, and so on. Generally this does not cause a problem when the content is inserted into existing pages. Usually modern browsers are smart enough to ignore the extra tags. But if you wish to suppress these tags, which is probably a good idea, add the following to your SSI call query string: &nowrap=1 That will ensure the served content is restricted to safe elements like <DIV> or <TABLE> containers, plus a CSS reference to ensure CSS continuity. If more control is required, edit the empty_navigation.ttml template which is used when the nowrap variable is activated. « Table of Contents | Obtain Review Foundry » Copyright © 2004 Random Mouse Software. All Rights Reserved. |