Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Ratings 2.0: Difference between revisions

From MoodleDocs
No edit summary
(45 intermediate revisions by 4 users not shown)
Line 1: Line 1:
==Objectives==
{{obsolete}}
 
[[Rating_API|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.
Ratings are grades entered away from the gradebook. They can be entered by students and teachers and are aggregated into grades.
Line 23: Line 27:
MDL-20514 Allow Aggregate Type in Glossary Activity
MDL-20514 Allow Aggregate Type in Glossary Activity


==New tables==
MDL-21657 Implement Ratings 2.0


===Ratings===
==Interface==
 
[[Image:RatingUI.gif]]
 
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====


{| class="nicetable"
{| class="nicetable"
Line 75: Line 95:
|}
|}


==Altered tables==
===Altered tables===
The forum, glossary and data tables need to be altered to contain the required fields specificed in [https://docs.moodle.org/en/Development:Ratings_2.0#Ratings_Settings]
The forum, glossary and data tables need to be altered to contain the required fields specificed in [https://docs.moodle.org/en/Development:Ratings_2.0#Ratings_Settings]


==Removed database tables==
===Removed database tables===


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


==Scales==
===Scales===


Course modules will continue to store the scale associated with their ratings. For example the glossary table has a scale column.
Course modules will continue to store the scale associated with their ratings. For example the glossary table has a scale column.
Line 94: Line 114:
Scales are going to be refactored as part of a separate issue. See MDL-17258.
Scales are going to be refactored as part of a separate issue. See MDL-17258.


==Ratings API==
==Ratings code changes==


lib/ratinglib.php will contain...
rating/lib.php will contain...


===class rating===
===class rating===


====__construct($contextid, $itemid, $scaleid, $userid)====
====__construct($options)====


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


====update_rating($rating)====
====update_rating($rating)====


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


====get_rating()====
====get_rating()====


get the rating
get the numerical value of the rating


====delete_rating()====
====delete_rating()====


delete the 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.


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


Load the rating renderer and use it to output this rating's UI. See [https://docs.moodle.org/en/Development:Ratings_2.0#Rating_Submission Rating Submission] for required fields.
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.


====static ratings_load_ratings($contextid, $aggregate='AVG', $items, $userid = null)====
Optionally options may include userid, returnurl, assesstimestart and assesstimefinish.
Returns an result set of ratings including aggregated ratings. $items is an array of objects with an id member variable ie $items[0]->id.
 
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.


<code php>
<code php>
function ratings_load_ratings($contextid, $aggregate='AVG', $items, $userid = null) {
function get_ratings($options) {
  global $DB, $USER;
  global $DB, $USER;
   
   
Line 139: Line 170:
             $itemids, SQL_PARAMS_NAMED, 'itemid0000');
             $itemids, SQL_PARAMS_NAMED, 'itemid0000');
   
   
     $sql = <<<ENDSQL
     $sql = "SELECT r.itemid, ur.id, ur.userid, ur.scaleid,
SELECT r.itemid,
     $aggregatestr(r.rating) AS aggrrating,
     $aggregate(r.rating) AS aggrrating,
     COUNT(r.rating) AS numratings,
     COUNT(r.rating) AS numratings,
     ur.rating AS usersrating
     ur.rating AS usersrating
Line 150: Line 180:
WHERE
WHERE
     r.contextid = :contextid AND
     r.contextid = :contextid AND
     r.itemid $itemidtest AND
     r.itemid $itemidtest
GROUP BY r.itemid, ur.rating
GROUP BY r.itemid, ur.rating
ENDSQL;
ORDER BY r.itemid";
   
   
     $params['userid'] = $userid;
     $params['userid'] = $userid;
     $params['contextid'] = $context->id;
     $params['contextid'] = $context->id;
   
   
     return $DB->get_records_sql($sql, $params);
     //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).
}
}
</code>
</code>


====static make_rating_subobjs($posts,$ratings)====
====get_aggregation_method($aggregate)====
Similar to make_context_subobj(). Iterate over forum $posts (forum posts, glossary items etc) and create $post->rating, $post->rating->aggregate and $post->rating->count.
Converts the aggregation method constants to a string that can be included in SQL


==Ratings Renderer==
====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.


Located in mod/ratings/renderer.php the 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.
Requires context, itemid and optionally accepts an SQL order by clause.


===core_rating_renderer methods===
====get_user_grades($options)====
Returns a grade for a user based on other user's rating of their items.


=====render_rating($rating)=====
===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.
returns rating UI html snippet. Used to include ratings in pages.
Line 181: Line 221:
// in mod/forum/discuss.php (for example)
// in mod/forum/discuss.php (for example)
$posts = // Some forum/lib.php function call.
$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
//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
//Also, a user should only see their own ratings
$ratings = Rating->ratings_load_ratings($contextid, $aggregate, $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*/, $userid);
$posts = rating::load_ratings($context,  
//Or, just return all ratings for the given 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*/,  
$ratings = Rating->ratings_load_ratings($contextid, $aggregate);
    $aggregate,
    $scaleid,  
    $userid,  
    $returnurl);


//Iterate over the posts and converts the result set into objects
//ratings are now attached to the post objects. $posts[0]->rating
//$post->rating, $post->rating->aggregate and $post->rating->count
//Similar to make_context_subobj().
$posts = Rating->make_rating_subobjs($posts,$ratings);


foreach ($posts as $postid => $post) {
foreach ($posts as $postid => $post) {
Line 197: Line 243:
}
}


$permissions = forum_rating_permission();//implemented by the module. returns array('view'=>true/false,'post'=>true/false)
// in mod/forum/renderer.php, in the post($post) method:
$scaleid = //load scale id from forum or glossary
 
// in mod/forum/renderer.php, in the post(post, $rating) method:


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




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


public function Rating::render_rating($page = null, $permissions=null,$scaleid) {
public function core_renderer::render_rating(rating $rating) {
     if (is_null($page) {
     //return html representation of the rating
        global $PAGE;
        $page = $PAGE;
    }
    $ratingoutput = $page->get_renderer('core', 'rating');
    return $ratingoutput->render_rating($this,$permissions,$scaleid);
}
}
</code>
</code>


==Ratings Aggregation==
===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.
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 ratings_load_ratings()
They are calculated within rating::ratings_load_ratings()


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


Line 234: Line 272:
! Info
! Info
|-
|-
| aggregation
| assessed
| int(10)
| int(10)
|  
|  
| The aggregation method to apply. Currently this is stored in the assessed column in the table "forum".
| 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.
|-
|-
| allcanrate
| int(10)
|
| Allow anyone to rate items. Currently this is stored in the assessed column in the table "glossary".
|-
|-
| assesstimestart
| assesstimestart
Line 261: Line 293:
|}
|}


Where is the "Restrict ratings to posts with dates in this range:" flag stored?
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...
<code php>
if (plugin_supports('mod', $this->_modname, FEATURE_RATINGS, false)) {
    //include ratings elements
}
</code>


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


==Rating Submission==
FEATURE_MOD_RATINGS will have to be added to lib/moodlelib.php


lib/rating.php will be the target for posted ratings. Currently each module implements their own ratings submission. For example mod/glossary/rate.php within the glossary module.
===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
The supplied fields should consist of
Line 296: Line 341:
|
|
| 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
| 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
|-
| userid
| PARAM_INT
|
| who wrote this comment
|-
|-
| returnurl
| returnurl
Line 314: Line 354:
if($permissions['post']) {
if($permissions['post']) {
$rating = N; //the actual rating from the user
$rating = N; //the actual rating from the user
$ratingObj = new Rating($contextid, $scaleid, $userid, array($itemid));
$ratingObj = new rating($contextid, $scaleid, $userid, array($itemid));
$ratingObj->set_rating($rating);
$ratingObj->set_rating($rating);
//redirect to return url if supplied
//redirect to return url if supplied
}
}


//within the class Rating
//within the class rating
function Rating::set_rating($rating) {
function Rating::update_rating($rating) {
$ratings = rating_system::load_ratings($scaleid, $userid, $contextid, array($itemid));
$ratings = rating_system::load_ratings($scaleid, $userid, $contextid, array($itemid));
if( !$ratings || sizeof($ratings)==0) {
if( !$ratings || sizeof($ratings)==0) {
Line 338: Line 378:
</code>
</code>


===Ajax submission===
====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.
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.


Line 351: Line 391:
</code>
</code>


== Permissions ==
=== Permissions changes ===


Permission could be handled in one of two ways.
Ratings is dependent on two things: core capabilities and the result of a module callback (which may itself use module capabilities).


===Module callback===
====New ratings permissions====
This allows modules to individually control ratings so, for example, the user may be able to rate forum posts but not glossary items.
====modname_rating_permissions()====
Modules can 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 lib/rating.php when it receives and ajax rating submission.


This function will return an array: array('view'=>true, 'viewall'=>true, post'=>true)
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
This example shows how this would work for the forum module
<code php>
<code php>
function forum_rating_permissions() {
function forum_rating_validate($params) {
$context = get_context_instance(CONTEXT_MODULE, $this->cm->id);
    if (!array_key_exists('itemid', $params) || !array_key_exists('context', $params) || !array_key_exists('rateduserid', $params)) {
return array('view'=>has_capability('mod/forum:viewrating',$context), 'viewall'=>has_capability('mod/forum:viewanyrating',$context), 'post'=>has_capability('mod/forum:rate',$context));
        throw new rating_exception('missingparameter');
    }
    return true;
}
}
</code>
</code>
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.


===Centralized ratings permissions===
This function will return an array: array('view'=>true, 'viewany'=>true, 'viewall'=>true, 'rate'=>true)
Control the ratings related permissions within the ratings module itself. This would allow less fine grained control but makes adding ratings to new areas of Moodle much less invasive.


As each module currently has its own ratings permissions migrating to single set of rating permissions could be tricky. What should happen if a user has viewall permissions in the forums but not in the glossary for example.
This example shows how this would work for the forum module
====Rating::get_ratings_permissions()====
<code php>
<code php>
static function get_rating_permissions() {
function forum_rating_permissions($context) {
$context = get_context_instance(CONTEXT_MODULE, $this->cm->id);
    return array('view'=>has_capability('mod/forum:viewrating',$context),
return array('view'=>has_capability('moodle/site:ratingview',$context), 'viewall'=>has_capability('moodle/site:ratingviewall',$context), 'post'=>has_capability('moodle/site:ratingrate',$context));
                'viewany'=>has_capability('mod/forum:viewanyrating',$context),  
                'viewall'=>has_capability('mod/forum:viewallratings',$context),  
                'rate'=>has_capability('mod/forum:rate',$context));
}
}
</code>
</code>


==Interface==
==See also==
 
[[Image:RatingUI.gif]]
 
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.
* MDL-21657 Implement Ratings 2.0


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.
[[Category:Grades]]

Revision as of 08:13, 27 January 2012

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

RatingUI.gif

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