Ratings 2.0

Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

Up-to-date info can be found in the Rating API doc

Moodle 2.0

Objectives

Ratings are grades entered away from the gradebook. They can be entered by students and teachers and are aggregated into grades.

The goals of ratings 2.0:

• Manage ratings centrally
• Use a consistent approach for all ratings throughout Moodle
• Easily integrate ratings 2.0 with existing modules
• Remove duplicate implementations of ratings functionality

Overview

The ratings 2.0 provides APIs to:

1. Add ratings
2. Update ratings
3. Access collected ratings for grade calculation purposes
4. Delete ratings

Current tracker issues

MDL-21389 Write spec for separate Ratings 2.0

MDL-20514 Allow Aggregate Type in Glossary Activity

MDL-21657 Implement Ratings 2.0

Interface

When Javascript is enabled ajax submission means the button can be removed. In the future it would be possible to automatically interpret a 1 to 5 rating as a star rating style UI element.

If the user has 'post' permission as returned by modname_rating_permissions() the dropdown box and submission button will be displayed.

If the user has 'view' permissions the text to the left of the dropdown box will be displayed. The displayed text consists of the aggregate of the ratings, 4 out of 5 in the example. The number in brackets is the number of ratings that have been submitted. There have been two ratings submitted in the example.

If the user has 'viewall' permissions they can click on the aggregate summary to view a list of all of the ratings that have been submitted. This is a listing of each user's profile pic, their name and the rating they submitted.

Database changes

New tables

Ratings

Field	Type	Default	Info
id	int(10)	auto-incrementing	The unique ID for this comment.
contextid	int(10)		The context id defined in context table - identifies the instance of plugin owning the comment.
itemid	int(10)		Some plugin specific item id (eg. forum post blog entry)
scaleid	int(10)		ID of the scale (1-5, 0-100, custom) from which the user selected their rating. Including this allows smarter handling of previously entered ratings should the scales be changed.
rating	int(10)		The user's rating
userid	int(10)		The user who submitted the rating
timecreated	int(10)
timemodified	int(10)

Altered tables

The forum, glossary and data tables need to be altered to contain the required fields specificed in [1]

Removed database tables

The following tables will have their data migrated to the above ratings table and then be removed:

data_ratings

forum_ratings

glossary_ratings

Scales

Course modules will continue to store the scale associated with their ratings. For example the glossary table has a scale column.

Scales are going to be refactored as part of a separate issue. See MDL-17258.

Ratings code changes

rating/lib.php will contain...

class rating

__construct($options)

Initialize a class instance. Requires context, itemid, scaleid and userid.

update_rating($rating)

Add or update the numerical value of the rating in the database

get_rating()

get the numerical value of the rating

delete_rating()

delete the rating. Not implemented yet as it hasn't been required.

class rating_manager

public get_ratings($options)

Returns the supplied set of items with a rating instance attached to each item.

$items is an array of objects with an id member variable ie $items[0]->id. $options requires context, items, aggregate and scaleid.

items is an array of items such as forum posts or glossary items. They must have an 'id' member ie $items[0]->id. aggregate is the the aggregation method to apply. RATING_AGGREGATE_AVERAGE etc.

Optionally options may include userid, returnurl, assesstimestart and assesstimefinish.

If userid is omitted the current user's id will be used. returnurl is the url to return the user to after submitting a rating. Can be left null for ajax requests. assesstimestart. Only allow rating of items created after this timestamp. assesstimefinish. Only allow rating of items created before this timestamp.

function get_ratings($options) {
 global $DB, $USER;
 
    if (isnull($userid)) {
        $userid = $USER->id;
    }

    $itemids = array();
    foreach($items as $item) {
        $itemids[] = $item->id;
    }
 
    list($itemidtest, $params) = $DB->get_in_or_equal(
            $itemids, SQL_PARAMS_NAMED, 'itemid0000');
 
    $sql = "SELECT r.itemid, ur.id, ur.userid, ur.scaleid,
    $aggregatestr(r.rating) AS aggrrating,
    COUNT(r.rating) AS numratings,
    ur.rating AS usersrating
FROM {ratings} r
LEFT JOIN {ratings} ur ON ur.contextid = r.contextid AND
        ur.itemid = r.itemid AND
        ur.userid = :userid
WHERE
    r.contextid = :contextid AND
    r.itemid $itemidtest
GROUP BY r.itemid, ur.rating
ORDER BY r.itemid";
 
    $params['userid'] = $userid;
    $params['contextid'] = $context->id;
 
    //add ratings to the items at $item->rating. Similar to make_context_subobj().
    //Iterate over forum $items (forum posts, glossary items etc) and create the  $item->rating objects. Properties of the individual ratings, such as $item->rating->aggregate and $item->rating->rating, are stored on the rating object directly.
    //Settings common to the ratings are stored at $item->rating->settings->aggregationmethod (for example).
}

get_aggregation_method($aggregate)

Converts the aggregation method constants to a string that can be included in SQL

get_all_ratings_for_item($options)

Load all ratings for a given item. Used to display a listing of submitted ratings to users with 'viewall' permission.

Requires context, itemid and optionally accepts an SQL order by clause.

get_user_grades($options)

Returns a grade for a user based on other user's rating of their items.

Rendering ratings

As rendering a rating will consist of only a single function call a new method called render_rating() will be added to the core renderer.

If necessary a ratings renderer could be added. Located in mod/ratings/renderer.php this new class core_rating_renderer should extend plugin_renderer_base defined in lib/outputrenderers.php Almost all renderers appear to inherit from plugin_renderer_base rather than core_renderer.

core_renderer::render_rating(rating $rating)

returns rating UI html snippet. Used to include ratings in pages.

Using the rating renderer

The process to render ratings is as follows:

// in mod/forum/discuss.php (for example)
$posts = // Some forum/lib.php function call.

//these are supplied by the calling module (forum etc)
$aggregate = 
$scaleid = 
$userid =
$returnurl = 

//The current scaleid comes from the forum or glossary object and may be changed at any time so supply it each time
//Also, a user should only see their own ratings
$posts = rating::load_ratings($context, 
    $posts/* Optional array of items (forum posts or glossary items) with an 'id' property. If null returns all ratings for the context by the user*/, 
    $aggregate, 
    $scaleid, 
    $userid, 
    $returnurl);

//ratings are now attached to the post objects. $posts[0]->rating

foreach ($posts as $postid => $post) {
    $forumoutput->post($post);//access the rating info at $post->rating, $post->rating->aggregate and $post->rating->count
}

// in mod/forum/renderer.php, in the post($post) method:

// ... output most of the post ... starts around line 5813 of mod/forum/lib.php
echo $OUTPUT->render($item->rating);
// ... output the rest.


// and finally in rating/lib.php in the rating class:

public function core_renderer::render_rating(rating $rating) {
    //return html representation of the rating
}

Ratings Aggregation

Forums currently support multiple forms of rating aggregation such as average, maximum, sum etc. These options should be available everywhere that ratings are available.

They are calculated within rating::ratings_load_ratings()

Ratings Settings

Settings for ratings are stored by the module. Each module table, for example forum, must contain the following columns.

Field	Type	Default	Info
assessed	int(10)		The aggregation method to apply. A value of 0 means ratings should be disabled. Currently the glossary stores an "allcanrate" flag in the assessed column. "allcanrate" will disappear in favour of proper permissions.
assesstimestart	int(10)		From when can users submit ratings
assesstimefinish	int(10)		When must users submit ratings by
scale	int(10)		What scale to use

The "Restrict ratings to posts with dates in this range" flag is calculated in the course/moodleforum_mod.php method moodleform::data_preprocessing() and is not stored in the database.

Settings interface

moodleform_mod::standard_coursemodule_elements()

Adds elements to an instance of moodle form. The ratings elements should appear in a separate block from Common Module Settings.

It will determine whether to include ratings settings by calling plugin_supports() found in lib/moodlelib.php like this...

if (plugin_supports('mod', $this->_modname, FEATURE_RATINGS, false)) {
    //include ratings elements
}

mod/%modulename%/lib.php defines a function called %modulename%_supports() that lists the elements that the module supports.

FEATURE_MOD_RATINGS will have to be added to lib/moodlelib.php

Rating Submission

rating/rate.php will be the target for posted ratings. Previously each module implemented their own ratings submission. For example mod/glossary/rate.php within the glossary module.

The supplied fields should consist of

Field	Type	Default	Info
contextid	PARAM_INT		The context id defined in context table - identifies the instance of plugin owning the comment.
itemid	PARAM_INT		Some plugin specific item id (eg. forum post blog entry)
scaleid	PARAM_INT		ID of the scale (1-5, 0-100, custom) from which the user selected their rating. Including this allows smarter handling of scales being changed.
rating	PARAM_INT		for example, in user profile, you can comment user's description or interests, but they share the same itemid(==userid), we need comment_area to separate them
returnurl	PARAM_LOCALURL		Null for ajax requests. If not null the url to which the user should be redirected after recording the rating

The process to record a rating is as follows:

$permissions = forum_rating_permission();
if($permissions['post']) {
$rating = N; //the actual rating from the user
$ratingObj = new rating($contextid, $scaleid, $userid, array($itemid));
$ratingObj->set_rating($rating);
//redirect to return url if supplied
}

//within the class rating
function Rating::update_rating($rating) {
$ratings = rating_system::load_ratings($scaleid, $userid, $contextid, array($itemid));
if( !$ratings || sizeof($ratings)==0) {
$data->contextid    = $this->contextid;
$data->scaleid      = $this->scaleid;
$data->userid       = $this->userid;
$data->rating       = $rating;
$DB->insert_record($this->table, $data);
}
else {
$data->id       = $this->id;
$data->rating   = $rating;
$DB->update_record($this->table, $data);
}

}

Ajax submission

Ajax submission of ratings must be possible for sites with ajax enabled. ForumNG (http://moodle.org/mod/data/view.php?d=13&rid=2927) written by Sam Marshall contains an ajax implementation of the rating UI elements that may be useful to reference.

Check if ajax is enabled like this...

if (empty($CFG->enableajax)) {
    //no ajax
}
else {
    //add ajax stuff
}

Permissions changes

Ratings is dependent on two things: core capabilities and the result of a module callback (which may itself use module capabilities).

New ratings permissions

New system-wide ratings permissions will be added. These will be checked IN ADDITION to local permissions in existing modules.

It is anticipated most new modules will just use these.

The new capabilities are:

moodle/rating:view - allows the user to view aggregated ratings made on their own items

moodle/rating:viewany - allows the user to view aggregated ratings made on other people's items

moodle/rating:viewall - allows the user to see individual ratings

moodle/rating:rate - allows the user to make ratings on other people's items

Handling of old permissions

Pre-existing module-specific permissions will be extended to have matching names/behaviour with the new rating permissions.

• mod/data:rate - unchanged
• mod/data:viewrating - unchanged
• mod/data:viewanyrating - cloned from old mod/data:viewrating
• mod/data:viewallratings - cloned from old mod/data:viewrating
• mod/forum:rate - unchanged
• mod/forum:viewrating - unchanged
• mod/forum:viewanyrating - unchanged
• mod/forum:viewallratings - cloned from old mod/forum:viewanyrating
• mod/glossary:rate - unchanged
• mod/glossary:viewrating - unchanged
• mod/glossary:viewanyrating - cloned from old mod/glossary:viewrating
• mod/glossary:viewallratings - cloned from old mod/glossary:viewrating

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

• MDL-21657 Implement Ratings 2.0