Rating API

Moodle 2.3

Overview

The ratings API provides the ability add, update, and delete ratings as well as 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.

Using The Rating Manager

The rating_manager class is defined in rating/lib.php.

Its most important functions are:

get_ratings() Attach ratings to an array of items. Rating objects are available at $item->rating.

get_user_grades() Returns an array of grades calculated by aggregating item ratings.

delete_ratings() Used to delete ratings. For example, when a module instance is deleted you should delete all of its associated ratings.

Examples

Below are several examples of using the rating_manager class. These are modified versions taken from the forum module. For more information look in the forum activity module (/mod/forum/lib.php), the glossary activity module (/mod/glossary/lib.php) and the database activity module (/mod/data/lib.php).

//first include the rating library
require_once($CFG->dirroot.'/rating/lib.php');


//get_ratings() example
if ($forum->assessed != RATING_AGGREGATE_NONE) {
    $ratingoptions = new stdClass;
    $ratingoptions->context = $modcontext;
    $ratingoptions->component = 'mod_forum';
    $ratingoptions->ratingarea = 'post';
    $ratingoptions->items = $posts; //the array of items to attach ratings to
    $ratingoptions->aggregate = $forum->assessed;//the aggregation method
    $ratingoptions->scaleid = $forum->scale;
    $ratingoptions->userid = $USER->id;
    //where to send the user after submitting a non-ajax rating
    if ($forum->type == 'single' or !$discussion->id) {
        $ratingoptions->returnurl = "$CFG->wwwroot/mod/forum/view.php?id=$cm->id";
    } else {
        $ratingoptions->returnurl = "$CFG->wwwroot/mod/forum/discuss.php?d=$discussion->id";
    }
    $ratingoptions->assesstimestart = $forum->assesstimestart;
    $ratingoptions->assesstimefinish = $forum->assesstimefinish;

    $rm = new rating_manager();
    $posts = $rm->get_ratings($ratingoptions);
}


//get_user_grades() example
$ratingoptions = new stdClass;
$ratingoptions->component = 'mod_forum';
$ratingoptions->ratingarea = 'post';
$ratingoptions->modulename = 'forum';
$ratingoptions->moduleid   = $forum->id;
$ratingoptions->userid = $userid;
$ratingoptions->aggregationmethod = $forum->assessed;
$ratingoptions->scaleid = $forum->scale;
$ratingoptions->itemtable = 'forum_posts';
$ratingoptions->itemtableusercolumn = 'userid';

$rm = new rating_manager();
return $rm->get_user_grades($ratingoptions);


//delete_ratings() example
require_once($CFG->dirroot.'/rating/lib.php');
$delopt = new stdClass;
$delopt->contextid = $context->id;
$delopt->component = 'mod_forum';
$delopt->ratingarea = 'post';
$delopt->itemid = $post->id;
$rm = new rating_manager();
$rm->delete_ratings($delopt);

Module callbacks

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

modname_supports

As with other optional functionality your activity module must state that it wishes to support ratings. It does that by adding FEATURE_RATE to modname_supports()

Example

This example is a simplified version of the forum module's implementation.

function forum_supports($feature) {
    switch($feature) {
        ...
        case FEATURE_RATE:                    return true;
        ...
        default: return null;
    }
}

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) which do the following.

view - allow the user to view aggregated ratings made on their own items

viewany - allow the user to view aggregated ratings made on other people's items

viewall - allow the user to see individual ratings submitted by other users

rate - allows the user to submit ratings on other people's items

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]

Displaying a Rating UI

To display a rating UI so the user can submit a rating supply a rating object to $OUTPUT->render(). It returns the rating UI html as a string.

Example

This is a modified example taken from the forum activity module. The forum previously uses rating_manager::get_ratings() to attach rating objects to an array of forum posts.

if (!empty($post->rating)) {
    $output .= $OUTPUT->render($post->rating);
}

See also

• Core APIs
• Ratings 2.0