Red Queen Review Engine User Manual PULLING DATA WITH SSI

Adjust Text:  a a a a

« Table of Contents   |   Obtain Red Queen »

• PULLING DATA WITH SSI
• Grabbing Latest Reviews
• Grabbing Latest Items, Members, Suppliers
• Grabbing Average Ratings
• Tiling Options
• Suppressing HTML Tags

PULLING DATA WITH SSI

Although Red Queen 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 Red Queen pages. Instead, you might want the user to navigate the pages of an existing catalog on your site, but you'd like to pull into those pages some of the information captured in the Red Queen 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 Red Queen 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). Red Queen can accommodate you in situations like this.

Depending on your system, an SSI call in general will look something like the following:

<!--#include virtual="/cgi-bin/path/to/some_script.cgi"-->

This code is inserted into your .shtml page 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).

If you are interested in pulling the same data dynamically from a script instead of using an SSI call (to redqueen.cgi) from a "static" page, take a look at this script for clues (it uses the perl module LWP::Simple to perform a network request to redqueen.cgi):

/do/get_recent.cgi

For all URLs displayed on this page which contain redqueen.cgi, replacement with get_recent.cgi will in fact result in the same output (though a direct call to redqueen.cgi is more efficient).

Grabbing Latest Reviews

There 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:

• Latest Reviews For A Container Type

  An SSI call for latest reviews requires 2 mandatory parameters: the module parameter, which specifies the container type involved, and the do parameter which is set to 'latest_reviews'. Here are example calls with the maximum number of returned reviews set to 3 (see discussion of the size parameter below):

  redqueen.cgi?module=ssi_item&do=latest_reviews&size=3      (3 latest Item reviews)
  redqueen.cgi?module=ssi_member&do=latest_reviews&size=3	   (3 latest Member reviews)
  redqueen.cgi?module=ssi_supplier&do=latest_reviews&size=3  (3 latest Supplier reviews)
  

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.

• Latest Reviews For A Container

  To restrict the latest reviews to a given Container, or any Subcontainer of it, add one of the following parameters to the appropriate query string shown above (where the example container_id is taken to be 7 here):

  &category_id=7
  &team_id=7
  &yellowpage_id=7
  

  Thus, if we want to grab the 3 latest Supplier reviews for the Yellow Page with id=7, use this URL:

  redqueen.cgi?module=ssi_supplier&do=latest_reviews&yellowpage_id=7&size=3

For each review presented, if a thumbnail image exists for the corresponding Thing the thumbnail will appear with a summary of the review..

• Latest Reviews For A Thing

  To restrict the latest reviews to a given Container AND a given Thing, add one of the following parameters sets to the appropriate query string shown above (where the example thing_id is taken to be 5 here):

  &item_id=5&category_id=7
  &member_id=5&team_id=7
  &supplier_id=5&yellowpage_id=7
  

  Note that you MUST supply a Container ID here, not just the Thing ID. If you don't, you'll just get an error message returned. Thus, if we want to grab the 3 latest reviews for the Member with id=10, from the Team with id=27 (or any Subteam of that Team) use this URL:

  redqueen.cgi?module=ssi_member&do=latest_reviews&member_id=10&team_id=27&size=3

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.

• Display Size (optional)

  By default, the number of latest reviews presented is derived from the latest review list size parameter set in your configuration file. To override this value, add a size parameter to your query string. For example, to have a maximum of 3 latest reviews returned:

  &size=3

• Display Width (optional)

  By default, latest review information is placed into a table which uses a width attribute of 100%. You can change this by adding a width to the query string. Either a pixel width, or a percentage width is acceptable:

  &width=200
  &width=50%
  

• Display Format (optional)

  By default, latest review information is presented in a "detailed format" suitable for insertion into your page if space is not of a premium. If instead you wish to put this information into a vertical side panel (as, for example, is done in Red Queen when latest reviews are presented on the topmost page of a Container branch) an extra format parameter is provided for this purpose. Add this to your SSI URL to effect the compact format:

  &format=compact

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.

• Review Text Truncation (optional)

  By default, the text for each latest review appears only when the chosen display format is NOT the compact format. When this is the case, you can elect to truncate the amount of review text displayed on the page by adding a trunc parameter to the query string. This parameter specifies the number of characters that will be displayed before an ellipsis is tacked on to represent the rest of the review. A link to the full review is also added. Truncation length is not exact--but will be approximately the length specified, and the ellipsis will appear at the end of the first word which appears AFTER the truncation length is reached. As an example, add this to the query string to truncate the review length to slightly more than 100 characters:

  &trunc=100
  

Grabbing Latest Items, Members, Suppliers

In 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.

• Latest Submissions For A Container Type

  As with the query string for latest reviews, latest submissions for a given Container Type require that the module and do parameters be appropriately set:

  redqueen.cgi?module=ssi_item&do=latest_items&size=3          (3 latest Item submissions)
  redqueen.cgi?module=ssi_member&do=latest_members&size=3      (3 latest Member enrollments)
  redqueen.cgi?module=ssi_supplier&do=latest_suppliers&size=3  (3 latest Supplier submissions)
  

  For each Thing presented in the list of new submissions, if a thumbnail image exists for the corresponding Thing the thumbnail will appear in addition to a summary of the Thing. In the case of Suppliers, if a logo is available, the logo will be used instead. In the case of Members, if a member thumbnail image is not available, the Member avatar will be used instead.

• Latest Submissions For A Container

  It is also possible to restrict the submissions returned to those associated with a given Container. Thus, as an example, you can ask for the 5 latest enrollments in the Critics/Baseball Team. In contrast to the behavior for latest reviews, when results are restricted to a Container, NO Subcontainers are included in the results. This means that if you restrict the latest enrollments to the Critics/Baseball Team you will not get a result from the Critics/Baseball/East Coast Team turning up. As before, you add one of the following parameters sets to your query:

  &category_id=7
  &team_id=7
  &yellowpage_id=7
  

  To grab the 3 latest Members from the Critics/Baseball Team (with team_id=7), use this URL:

  redqueen.cgi?module=ssi_member&do=latest_members&team_id=7&size=3

• Display Size (optional)

  To control the maximum number of latest Things returned, add a size parameter to the query string. This parameter, and it's behavior, is the same as was discussed for latest reviews.

• Display Width (optional)

  To control the width of the table in which latest submissions are presented, add a width parameter to the query string. This parameter, and it's behavior, is the same as was discussed for latest reviews.

• Display Format (optional)

  By default, latest submissions are output in a "detailed format". To reduce the amount of information presented so that the list may be put into a vertical column (such as a side panel), add a format parameter to the query string and supply the value "compact". This parameter, and it's behavior, is the same as was discussed for latest reviews.

• Field Truncation (optional)

  When the "detailed" format is specified, there are several descriptive (text) fields that may potentially be quite large and you may wish to truncate these. For example, the Item.description field, or the Member.full_bio. To shorten these, add a trunc parameter to the query string, specifying the (approximate) maximum number of characters that can appear before these fields are truncated. This parameter, and it's behavior, is the same as was discussed for latest reviews.

• Descriptive Fields When decriptive fields are displayed for latest submissions, an attempt will be made to place the (most likely) shortest variant of the field. In the case of Items there are no variants--the Item.description field is used. But for Members and Suppliers there are the short and long forms of the descriptive fields to choose from--Member.brief_bio and Member.full_bio for Members, and Supplier.brief_description and Supplier.description for Suppliers. There is also a Container-dependent version of the Member.brief_bio and Supplier.brief_description fields, which, if defined, carry a textual description created specifically for a given Container. Preference is given to this latter field, stored either in the MemberGlimpse or SupplierGlimpse tables (Members can edit the glimpse field by clicking on the "Edit Bio" link seen on public pages). Only if no glimpse field has been defined will the more generic descriptive fields from the Member or Supplier tables be placed on the page. The motivation here, of course, is to use the most accurate, but shortest descriptive field to summarize the Thing appearing in the list of latest submissions.

Grabbing Average Ratings

If 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:

redqueen.cgi?module=ssi_item&do=average_ratings&item_id=7&category_id=3
redqueen.cgi?module=ssi_member&do=average_ratings&member_id=7&team_id=3
redqueen.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 Red Queen 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 Options

Tiling 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 query string variable that affects whether or not SSI data will appear in list or tiled format (that is, records are formatted across and down the page as tiles) is the tiled parameter:

&tiled=1    (or &tiled=0 to switch off any default tiling)

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 Tags

When content is served up by Red Queen 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 Red Queen »