A User Guide to the Ratings Tool

This product provides for ratings of cmf content, with centralized access through a ratings tool, and also allows retrieval of the highest rated content.

it is not integrated with any skins, so actually setting it up requires writing a bit of a ui work

Installation

add external method to your CMF folder:

        name: install_ratings
        package: Ratings/Install
        method: install

after adding it, go to the zmi for the external method and test it. this installs the ratings tool.

go back to the zmi contents for the your CMF folder, you should now see a ratings_tool there.

Ok so now what...

Usage

Displaying Content Ratings

When displaying a piece of content for which you want to display ratings, get a reference to the ratings tool, and call ratings_tool.getRatingsFor(content) where content is the current object. this works in a manner very similiar to how comments are retrieved.

once you have a ratings object, you need to render it, by default there is a dtml method associated with the ratings object call method. so the dtml equivalaent of will render it.

recapping in pseudo code

getTool(ratings_tool).getRatingsFor(this())(None, context)

the other option is to manually render it, see below.

Displaying the top Rated Objects

the tool exposes a method for getting a list of the highest rated objects. get a reference to the tool and call rating_tool.getHighestRatedObjects() which will return a list of objects who have the highest ratings.

so a ui layer would call this method, and iterate over the resultant objects.

Displaying Rating Info Directly

once you have a reference to a rating object you can manually query it for the objects rating via the following methods:

                getAverage() - returns the average rating
                getNumberVotes() - returns the number of rating votes
                getContentPath() -  returns the path to this rating's content
                getVoteUrl - returns the url to send a user to vote

and display this info in the presentation of your choosing.

Voting on a Content Item

Votes are assigned to a piece of content by visiting a url.

given a content url you can assume that the rating url is content_url/rating/addRating

you need to make sure that the content has a rating object associated with it by asking the tool for it via rating_tool.getRatingsFor(content)

if you have a rating object you can get the url to vote on its content by calling rating.getVoteUrl()

this url/method takes one query variable named value which should be an integer.

Anonymous Voting

This Rating Tool does not support anonymous voting, and never will.

Advanced Usage

Customizing the Highest Rated Objects (ranking)

the list of the highest rated objects is checked on every rating of an object to see if the new rating (and its associated content) warrant a place on the list. this decision making is isolated in a single python function, by changing this rating ranking algorithm you can customize how objects which objects are considered the highest rated.

currently the ranking algorithm is fairly stupid, and just returns the sum of rating votes for a particular content item.

Customizing the Highest Rated Objects (how many)

the default list size for the highest rated objects is set to an upper bound of 10. to change this at the moment currently requires altering the class definition of the RatingTool before instantiation (and changing _default_set_length) OR an external method that sets this attribute on the rating tool, and then calls

rating_tool.store.setBound(self._default_set_length)

in a future release i'll make this configurable from the zmi.

Customizing the Rating Scale

requires altering the class definition of the Rating object and altering the class attribute _scale there.

More Info

please contact the author, kapil thangavelu at [email protected]