Rating Engine

Content rating using different user driven and automatic methods. The former project name is ATRatings.

Current release

No stable release available yet.

If you are interested in getting the source code of this project, you can get it from the code repository.

Project Description

Copyright

Voting support, clean-up and maintenance by Mikko Ohtamaa, Red Innovation, 2006

Originally created by Geoff Davis (geoff at geoffdavis.net)

Enhancements by panjunyong (panjy at zopechina.com)

Instructions by Vasily Savin (chabrik at yahoo.com), 2006

Purpose

Rating engine is Plone item rating system.

It supports three different rating methods

  • Hit counting. Hit rate (hits/time unit) can be calculated. 
  • Rate by user. Users chooses 1-5 stars he/she thinks an item is worth of. Various numbers can be calculated by rating statistics. User can change his rating later.
  • Vote by users. A user has a fixed amount of 5 votes he/she can place on items he/she thinks to deserve votes.

Top charts can be made from rated items.

Requirements

  • Plone 2.0.5 or higher

References

RatingEngine is in live usage in www.opensourceusability.com. See this example.

License

GPL

Quality assurance

Tested with:

  • Plone 2.1.1
  • Windows XP
  • Ubuntu 5.10 Breezy
  • Opera 8.5
  • Firefox 1.5
  • Internet Explorer 6.0

Unit tests coverage

  • See tests folder for more details

Instructions

Installing product in Zope.

In order to install product you need to unpack RatingEngine files and put them there: {path/to/zope/instance}/Products/RatingEngine.

Secondly you have to restart Zope, if it was running before. Be aware that Zope looks for new products only on startup.

Ok, once Zope is running again, let's check if we got product installed correctly. Hop into ZMI -> Control Panel -> Product Management

Now run through the list and find RatingEngine. If everything is ok it will say RatingEngine (Installed product RatingEngine (0.3 [Or some othher version]))

If something went wrong at installation, it will say "Broken Product". There can be numerous reasons for going wrong, but troubleshooting is out of scope of this document.

So we assume everything went well and we can proceed to Step 2

Installing product in Plone

For now, everything is still relatively easy.

Go to {your_portal_url}/plone_control_panel

Follow "Add new products" link.

You should go through the list of ready-to-install products and select...... well, doh, select RatingEngine and install it. :)

Check if it installed without error and proceed to Step 3

Starting to use

First, you should know that RatingEngine work only with AT content types, so you choose what you want to rate accordingly.

So, once you made up your mind, create the object you desire to rate. Since ratings are disabled by default, you have to put them on manually.

This is the place black magic happens. :)

Go to ZMI, find the object or its parent object that you want to rate.

 Select this object and go to Properties.

Add 3 boolean properties:

  •  enableRatings : enable ratings for contents in the folder
  •  enableCountings : enable click countings for content in the folder
  •  enableVotings : enable votings for content in the folder

Note that these properties are accessed through acquistiosion. This means that children inherit their parent properties. One can enable rating side wide by putting these properties to portal root properties and then control rateable types in portal_rating tool.

Also, you need explictly specify which types are rateable. This can be done in portal_ratings tool. By default, only "Document", i.e. normal page, is rateable.

Now after, you added these properties, scripts will start counting hits, but to be able to see the results and rate content, you should put something up for user.

So, add following macro 'here/rating_macros/macros/portlet' to your template.

One of the simpler ways to do it:add yet another property "left_slots" or "right_slots" with type = "lines" and value "here/rating_macros/macros/portlet"

It is by no means the only way to do it, but a mere demonstration that it works and how it looks like.

Top chart pages

  • You can create pages for top charts
  • Choose add new item -> Top chart
  • In view mode, a top chart is displayed with item names, item vote counts and links to the items
  • In edit mode, you can tune top chart settings
  • Currently top chart pages are available for voted items only

Permissions

You can control who can vote by permission: "RatingEngine: Add rating". By default, all registered users can use rating.

Simple rating statistics

  • Add 3 portlets in your left_slots or right_slots
  • portal/path/to/your/folder/portlet_top_ratings
  • portal/path/to/your/folder/portlet_top_countings
  • portal/path/to/your/folder/portlet_top_voted

Available votes

  • By default, every registered user has 5 votes available
  • You can edit different vote amounts in Zope Management Interface. Go to ZMI, at_ratings, select "Votes" tab.

Enabling rating for certain item types

  • You can control what can be rate / hit count by portal_ratings properties:
    • allowed_rating_types
    • allowed_couting_types
    • allowed_voting_types

Enabling portlets

  • Put macro 'here/rating_macros/macros/portlet' to portlet slots. For example, you can add it to document_byline.pt or the left_slots propertis in Zope Management Interface at the properties of the root folder of your site.
  • For voting, use macro 'here/voting_macros/macros/vote_portlet'

Voting portlet help link

  • Voting portlet has a help link you can set yourself. This can be done in portal_ratings properties.

Todo

  • Moving votes from one item to another
  • Getting top charts pages for rated and hit counted items. Top chart supports only voted items. 
  • Getting top charts for item subsets based on item parent folder and item type
  • Making the backend management of RatingEngine easier
  • Split RatingTool to several classes
  • Internationalization
    • The orignal RatingEngine 0.2 had internationalization support
    • Version 0.3, specially voting part, don't have internationalization support

Internals

RatingEngine uses a pluggable storage mechanism for rating data. So far I have written a ZODB-based storage that strives to be reasonably efficient with memory.

RatingEngine makes use of references and hence can be used only on Archetypes items. All content is Archetypes base since Plone 2.1.

For the API methods, see API.txt and read method comments.

Diving into the Code

It is possible to make objects ratable on creation. I'm not sure this is the best way it can be done, but the following worked for me reasonably well:

obj.manage_addProperty(id='enableRatings', type='boolean', value=True)
obj.manage_addProperty(id='enableVotings', type='boolean', value=True)
obj.manage_addProperty(id='enableCountings', type='boolean', value=True)
obj.manage_addProperty(id='right_slots', type='lines', value='here/rating_macros/macros/portlet')

obj - AT object that you want to rate.

If you want to switch ratings on/off, you should implement method, that will change the value of the properties above.