Олег Давидович: 1 версия импортирована

2024-10-21T08:53:06Z

1 версия импортирована

← Предыдущая версия	Версия от 08:53, 21 октября 2024
(нет различий)

1>Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

2021-07-14T13:24:11Z

Text replacement - "class="nicetable"" to "class="wikitable""

Новая страница

{{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:
# Add ratings
# Update ratings
# Access collected ratings for grade calculation purposes
# 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==

[[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="wikitable"
|-
! 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 [https://docs.moodle.org/en/Development:Ratings_2.0#Ratings_Settings]

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

<code php>
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).
}
</code>

====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:

<code php>
// 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
}
</code>

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

{| class="wikitable"
|-
! 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...
<code php>
if (plugin_supports('mod', $this->_modname, FEATURE_RATINGS, false)) {
//include ratings elements
}
</code>

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
{| class="wikitable"
|-
! 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:

<code php>
$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);
}

}
</code>

====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...
<code php>
if (empty($CFG->enableajax)) {
//no ajax
}
else {
//add ajax stuff
}
</code>

=== 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
<code php>
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;
}
</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.

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
<code php>
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));
}
</code>

==See also==

* MDL-21657 Implement Ratings 2.0

[[Category:Grades]]

Development:Ratings 2.0 - История изменений

Олег Давидович: 1 версия импортирована

1>Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""