[zopeorg-checkins] CVS: Products/Ratings/help - UserGuide.stx:1.1

[Kapil Thangavelu]

Update of /cvs-zopeorg/Products/Ratings/help
In directory cvs.zope.org:/tmp/cvs-serv25602/help

Added Files:
	UserGuide.stx 
Log Message:
adding in ratings


=== Added File Products/Ratings/help/UserGuide.stx ===
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 
       <dtml-var rating> 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 kvthan at wm.edu