Rating API

Moodle 2.3

Overview

The ratings APIs provides classes and functions to add, update, and delete ratings and access collected ratings for grade calculation purposes.

If you are looking for implementation details of the rating system's internal structure go to Ratings 2.0

File Locations

rating/lib.php contains the definition of the rating_manager class. rating_manager is the primary point of contact for the rating API.

Module callbacks

These callbacks will be used by the rating_manager. They should be defined within your module's lib.php.

modname_rating_permissions

Modules must implement a function named modname_rating_permissions to tell the ratings system what the user is able to do. This callback allows modules to use settings, capability checks and any other logic required to determine the current user's ability to view and submit ratings. It is called prior to rendering rating user interface components and when ratings are submitted.

This function receives $contextid, $component and $ratingarea as parameters. It should return an array: array('view'=>true, 'viewany'=>true, 'viewall'=>true, 'rate'=>true)

Example

This example is a simplified version of the forum module's implementation. function forum_rating_permissions($context) {

   return array('view'=>has_capability('mod/forum:viewrating',$context), 
                'viewany'=>has_capability('mod/forum:viewanyrating',$context), 
                'viewall'=>has_capability('mod/forum:viewallratings',$context), 
                'rate'=>has_capability('mod/forum:rate',$context));

}

modname_rating_validate

Modules using ratings should implement modname_rating_validate to verify the validity of submitted ratings.

This function should return true if the rating is valid or throw an instance of rating_exception if the rating is invalid. Note: false is used to indicate that the module hasn't implemented this callback.

Example

This example is a simplified version of the forum module's implementation. function forum_rating_validate($params) {

   if (!array_key_exists('itemid', $params) || !array_key_exists('context', $params) || !array_key_exists('rateduserid', $params)) {
       throw new rating_exception('missingparameter');
   }
   return true;

} The rating_exception argument is the name of a string in the error language file.

The $params argument contains:

• context - object the context in which the rated items exists [required]
• itemid - int the ID of the object being rated
• scaleid - int the scale from which the user can select a rating. Used for bounds checking. [required]
• rating - int the submitted rating
• rateduserid - int the id of the user whose items have been rated. NOT the user who submitted the ratings. 0 to update all. [required]
• aggregation - int the aggregation method to apply when calculating grades ie RATING_AGGREGATE_AVERAGE [required]

See also

• Core APIs
• Ratings 2.0