Rating API - Revision history

Mudrd8mz: Text replacement - "" to ""

2021-07-14T20:22:21Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 20:22, 14 July 2021
Line 80:		Line 80:
	$rm = new rating_manager();		$rm = new rating_manager();
	$rm->delete_ratings($delopt);		$rm->delete_ratings($delopt);
	</~~code~~>		</syntaxhighlight>

	==Module callbacks==		==Module callbacks==
Line 100:		Line 100:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	===modname_rating_permissions===		===modname_rating_permissions===
Line 124:		Line 124:
	'rate'=>has_capability('mod/forum:rate',$context));		'rate'=>has_capability('mod/forum:rate',$context));
	}		}
	</~~code~~>		</syntaxhighlight>

	===modname_rating_validate===		===modname_rating_validate===
Line 141:		Line 141:
	return true;		return true;
	}		}
	</~~code~~>		</syntaxhighlight>
	The rating_exception argument is the name of a string in the error language file.		The rating_exception argument is the name of a string in the error language file.

Line 161:		Line 161:
	$output .= $OUTPUT->render($post->rating);		$output .= $OUTPUT->render($post->rating);
	}		}
	</~~code~~>		</syntaxhighlight>

	==See also==		==See also==

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:31:05Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:31, 14 July 2021
				
Line 26:
Line 26:
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). 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).



<code php> <syntaxhighlight lang="php">
//first include the rating library //first include the rating library
require_once($CFG->dirroot.'/rating/lib.php'); require_once($CFG->dirroot.'/rating/lib.php');
Line 91:
Line 91:
====Example==== ====Example====
This example is a simplified version of the forum module's implementation. This example is a simplified version of the forum module's implementation.
<code php> <syntaxhighlight lang="php">
function forum_supports($feature) { function forum_supports($feature) {
     switch($feature) {      switch($feature) {
Line 117:
Line 117:
====Example==== ====Example====
This example is a simplified version of the forum module's implementation. This example is a simplified version of the forum module's implementation.
<code php> <syntaxhighlight lang="php">
function forum_rating_permissions($context) { function forum_rating_permissions($context) {
     return array('view'=>has_capability('mod/forum:viewrating',$context),        return array('view'=>has_capability('mod/forum:viewrating',$context),  
Line 134:
Line 134:
====Example==== ====Example====
This example is a simplified version of the forum module's implementation. This example is a simplified version of the forum module's implementation.
<code php> <syntaxhighlight lang="php">
function forum_rating_validate($params) { function forum_rating_validate($params) {
     if (!array_key_exists('itemid', $params) || !array_key_exists('context', $params) || !array_key_exists('rateduserid', $params)) {      if (!array_key_exists('itemid', $params) || !array_key_exists('context', $params) || !array_key_exists('rateduserid', $params)) {
Line 157:
Line 157:
===Example=== ===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. 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.
<code php> <syntaxhighlight lang="php">
if (!empty($post->rating)) { if (!empty($post->rating)) {
     $output .= $OUTPUT->render($post->rating);      $output .= $OUTPUT->render($post->rating);



Andyjdavis: /* modname_supports */
2012-02-17T12:03:08Z
modname_supports

				
				
				
				
				
				← Older revision
				Revision as of 12:03, 17 February 2012
				
Line 87:
Line 87:



===modname_supports=== ===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 modnam_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==== ====Example====



Andyjdavis: /* Module callbacks */
2012-02-17T12:01:56Z
Module callbacks

				
				
				
				
				
				← Older revision
				Revision as of 12:01, 17 February 2012
				
Line 85:
Line 85:



These callbacks will be used by the rating_manager. They should be defined within your module's lib.php. 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 modnam_supports()

====Example====
This example is a simplified version of the forum module's implementation.
<code php>
function forum_supports($feature) {
    switch($feature) {
        ...
        case FEATURE_RATE:                    return true;
        ...
        default: return null;
    }
}
</code>



===modname_rating_permissions=== ===modname_rating_permissions===



Andyjdavis: /* modname_rating_permissions */
2012-02-17T11:52:09Z
modname_rating_permissions

				
				
				
				
				
				← Older revision
				Revision as of 11:52, 17 February 2012
				
Line 89:
Line 89:
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. 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) 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==== ====Example====



Andyjdavis at 11:44, 17 February 2012
2012-02-17T11:44:22Z


				
				
				
				
				
				← Older revision
				Revision as of 11:44, 17 February 2012
				
Line 127:
Line 127:
* rateduserid - int the id of the user whose items have been rated. NOT the user who submitted the ratings. 0 to update all. [required] * 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] * 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.
<code php>
if (!empty($post->rating)) {
    $output .= $OUTPUT->render($post->rating);
}
</code>



==See also== ==See also==



Andyjdavis: /* Using The Rating's Manager */
2012-02-17T11:38:00Z
Using The Rating's Manager

				
				
				
				
				
				← Older revision
				Revision as of 11:38, 17 February 2012
				
Line 10:
Line 10:
rating/lib.php contains the definition of the rating_manager class. rating_manager is the primary point of contact for the rating API. 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's Manager== ==Using The Rating Manager==



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



Andyjdavis: /* Examples */
2012-02-17T11:34:29Z
Examples

				
				
				
				
				
				← Older revision
				Revision as of 11:34, 17 February 2012
				
Line 24:
Line 24:
===Examples=== ===Examples===



Below are several examples of using the rating_manager class. These are modified versions of how the forum modules utilises rating_manager. 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).



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


//get_ratings() example //get_ratings() example
if ($forum->assessed != RATING_AGGREGATE_NONE) { if ($forum->assessed != RATING_AGGREGATE_NONE) {
Line 49:
Line 53:
     $posts = $rm->get_ratings($ratingoptions);      $posts = $rm->get_ratings($ratingoptions);
} }




//get_user_grades() example //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 //delete_ratings() example



Andyjdavis at 11:01, 17 February 2012
2012-02-17T11:01:25Z


				
				
				
				
				
				← Older revision
				Revision as of 11:01, 17 February 2012
				
Line 9:
Line 9:



rating/lib.php contains the definition of the rating_manager class. rating_manager is the primary point of contact for the rating API. 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's 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 of how the forum modules utilises rating_manager.

<code 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

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



==Module callbacks== ==Module callbacks==



Andyjdavis: /* Overview */
2012-02-17T10:15:06Z
Overview

				
				
				
				
				
				← Older revision
				Revision as of 10:15, 17 February 2012
				
Line 2:
Line 2:



==Overview== ==Overview==
The ratings APIs provides classes and functions to add, update, and delete ratings and access collected ratings for grade calculation purposes. 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]] If you are looking for implementation details of the rating system's internal structure go to [[Ratings 2.0]]

← Older revision		Revision as of 13:31, 14 July 2021
Line 26:		Line 26:
	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).		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).

	<~~code~~ php>		<syntaxhighlight lang="php">
	//first include the rating library		//first include the rating library
	require_once($CFG->dirroot.'/rating/lib.php');		require_once($CFG->dirroot.'/rating/lib.php');
Line 91:		Line 91:
	====Example====		====Example====
	This example is a simplified version of the forum module's implementation.		This example is a simplified version of the forum module's implementation.
	<~~code~~ php>		<syntaxhighlight lang="php">
	function forum_supports($feature) {		function forum_supports($feature) {
	switch($feature) {		switch($feature) {
Line 117:		Line 117:
	====Example====		====Example====
	This example is a simplified version of the forum module's implementation.		This example is a simplified version of the forum module's implementation.
	<~~code~~ php>		<syntaxhighlight lang="php">
	function forum_rating_permissions($context) {		function forum_rating_permissions($context) {
	return array('view'=>has_capability('mod/forum:viewrating',$context),		return array('view'=>has_capability('mod/forum:viewrating',$context),
Line 134:		Line 134:
	====Example====		====Example====
	This example is a simplified version of the forum module's implementation.		This example is a simplified version of the forum module's implementation.
	<~~code~~ php>		<syntaxhighlight lang="php">
	function forum_rating_validate($params) {		function forum_rating_validate($params) {
	if (!array_key_exists('itemid', $params) \|\| !array_key_exists('context', $params) \|\| !array_key_exists('rateduserid', $params)) {		if (!array_key_exists('itemid', $params) \|\| !array_key_exists('context', $params) \|\| !array_key_exists('rateduserid', $params)) {
Line 157:		Line 157:
	===Example===		===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.		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.
	<~~code~~ php>		<syntaxhighlight lang="php">
	if (!empty($post->rating)) {		if (!empty($post->rating)) {
	$output .= $OUTPUT->render($post->rating);		$output .= $OUTPUT->render($post->rating);

← Older revision		Revision as of 12:03, 17 February 2012
Line 87:		Line 87:

	===modname_supports===		===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 ~~modnam_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====		====Example====

← Older revision		Revision as of 12:01, 17 February 2012
Line 85:		Line 85:

	These callbacks will be used by the rating_manager. They should be defined within your module's lib.php.		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 modnam_supports()

			====Example====
			This example is a simplified version of the forum module's implementation.
			<code php>
			function forum_supports($feature) {
			switch($feature) {
			...
			case FEATURE_RATE: return true;
			...
			default: return null;
			}
			}
			</code>

	===modname_rating_permissions===		===modname_rating_permissions===

← Older revision		Revision as of 11:52, 17 February 2012
Line 89:		Line 89:
	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.		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)		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====		====Example====

← Older revision		Revision as of 11:38, 17 February 2012
Line 10:		Line 10:
	rating/lib.php contains the definition of the rating_manager class. rating_manager is the primary point of contact for the rating API.		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's Manager==		==Using The Rating Manager==

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

← Older revision		Revision as of 11:34, 17 February 2012
Line 24:		Line 24:
	===Examples===		===Examples===

	Below are several examples of using the rating_manager class. These are modified versions ~~of how~~ the forum ~~modules utilises rating_manager~~.		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).

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


	//get_ratings() example		//get_ratings() example
	if ($forum->assessed != RATING_AGGREGATE_NONE) {		if ($forum->assessed != RATING_AGGREGATE_NONE) {
Line 49:		Line 53:
	$posts = $rm->get_ratings($ratingoptions);		$posts = $rm->get_ratings($ratingoptions);
	}		}


	//get_user_grades() example		//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		//delete_ratings() example

← Older revision		Revision as of 11:01, 17 February 2012
Line 9:		Line 9:

	rating/lib.php contains the definition of the rating_manager class. rating_manager is the primary point of contact for the rating API.		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's 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 of how the forum modules utilises rating_manager.

			<code 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

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

	==Module callbacks==		==Module callbacks==

← Older revision		Revision as of 10:15, 17 February 2012
Line 2:		Line 2:

	==Overview==		==Overview==
	The ratings ~~APIs~~ provides ~~classes and functions to~~ add, update, and delete ratings ~~and~~ access collected ratings for grade calculation purposes.		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]]		If you are looking for implementation details of the rating system's internal structure go to [[Ratings 2.0]]