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

The primary functions for the Rating API is located in rating/lib.php

Additional functions and usage examples can be found in the following files:

• rating/rate.php
• rating/rate_ajax.php

Module callbacks

These allow modules to control how ratings behave.

modname_rating_validate

As of Moodle 2.0.3 modules must implement a function named modname_rating_validate to verify the validity of submitted ratings.

This function must 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.

This example shows how this would work for the forum module 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]

modname_rating_permissions

Modules must implement a function named modname_rating_permissions to control post and view permission. This is called prior to rendering a set of ratings. It is also called by rating/rate.php and rate/rate_ajax.php when they receive rating submissions.

Modules do not need to implement this. It's mostly provided for backward compatibility with modules that had complicated ratings related logic or for modules that use settings other than capabilities to control ratings behavior.

This function will return an array: array('view'=>true, 'viewany'=>true, 'viewall'=>true, 'rate'=>true)

This example shows how this would work for the forum module 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));

}

See also

• Core APIs
• Ratings 2.0