The Ratings API |
Refer to the Support section of the Cogix web site to download a set of files that can be imported into your ViewsFlash installation to deploy an actual working example, in a place named "ratings" and a questionnaire named "ratelive".
The Ratings API allows constructing ratings systems for content such as articles, videos, photos, and products. For each set of items to be rated, create a different ratings questionnaire. Ratings questionnaires are ViewsFlash questionnaires created using the Standard and Response styles or styles derived from it.
Each item to be rated includes a copy of the ratings questionnaire form, customized so that the item's identification code is inserted into a hidden field named item_id inside the form. This is usually done by a content management system. The form includes javascript that modifies the form's behavior so that instead of submitting the form, the content of the form is sent to ViewsFlash as an HTTP query using AJAX, and the response is used to replace the ratings form. The ratelive questionnaire includes all the correct settings and can be copied to any place of your choosing and can be further modified to improve look and feel and behavior as needed.
A Web Services API is also provided to retrieve an item's rating at any time. This API can be used by CMS systems to publish rankings either live or at certain intervals and can be cached. The API is one http query to ViewsFlash/servllet/viewsflash, with the following query string parameters:
&cmd=fetchrating
&pollid=SSSS!PPPP
&itemid=TTTTT
&count=1
&average=1
&decimals=N
&nodata=msg
Parameters fetchrating, pollid and itemid are required. Either count=1 or average=1, or both, are required. "decimals" defaults to none. "nodata" is what to return if there are no items to rate yet. SSSS!PPPP is the name of the Place and the Questionnaire of the ratings questionnaire. TTTTT is the id of the item; item id's must be unique within a ratings questionnaire, but can be duplicated across different rating questionnaies.
The query returns the following content:
COUNT space
AVERAGE space
where COUNT is a number of the people who have rated the item,
"space" means a delimiting space, and AVERAGE is the average rating for the item, formatted to the indicated number of decimal places. If something goes wrong during the query, a string is returned in the following format:
<viewsflash [/NG] - message>
where "message" indicates what went wrong.
The Ratings API uses a database table, VWFRATINGS, to store for each item:
- ITEMID - the pollid concatenated to the item id, must be unique
- SCORESUM and SCORECOUNT - the sum and count of the ratings; average is calculated from the two
- POLLID - the pollid
- DATEUPDATED - when the record was created or modified
Records are added to the VWFRATINGS table dynamically as needed; there is no need to create records in advance. Entries are removed automatically when the ratings questionnaire is deleted. The table is created automatically by ViewsFlash on startup provided the application has the appropriate database rights. The table can be accessed directly by other applications.