Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
rating_manager Class Reference

The rating_manager class provides the ability to retrieve sets of ratings from the database. More...

Public Member Functions

 add_rating ($cm, $context, $component, $ratingarea, $itemid, $scaleid, $userrating, $rateduserid, $aggregationmethod)
 Adds a new rating.
 
 check_rating_is_valid ($params)
 Validates a submitted rating.
 
moodle_database delete_ratings ($options)
 Delete one or more ratings.
 
 get_aggregate_label ($aggregationmethod)
 Returns a string that describes the aggregation method that was provided.
 
 get_aggregate_types ()
 Returns array of aggregate types.
 
 get_aggregation_method ($aggregate)
 Converts an aggregation method constant into something that can be included in SQL.
 
 get_all_ratings_for_item ($options)
 Returns an array of ratings for a given item (forum post, glossary entry etc).
 
 get_component_ratings_since ($context, $component, $since)
 Get ratings created since a given time.
 
 get_plugin_permissions_array ($contextid, $component, $ratingarea)
 Looks for a callback like forum_rating_permissions() to retrieve permissions from the plugin whose items are being rated.
 
 get_ratings ($options)
 Adds rating objects to an array of items (forum posts, glossary entries etc).
 
 get_user_grades ($options)
 Returns an array of grades calculated by aggregating item ratings.
 
 initialise_rating_javascript (moodle_page $page)
 Initialises JavaScript to enable AJAX ratings on the provided page.
 

Protected Member Functions

moodle_database generate_rating_scale_object ($scaleid)
 Generates a scale object that can be returned.
 
 generate_rating_settings_object ($options)
 Generates a rating settings object based upon the options it is provided.
 
 get_item_time_created ($item)
 Gets the time the given item was created.
 

Protected Attributes

array $scales = array()
 An array of calculated scale options to save us generating them for each request.
 

Detailed Description

The rating_manager class provides the ability to retrieve sets of ratings from the database.

License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
Since
Moodle 2.0

Member Function Documentation

◆ add_rating()

rating_manager::add_rating ( $cm,
$context,
$component,
$ratingarea,
$itemid,
$scaleid,
$userrating,
$rateduserid,
$aggregationmethod )

Adds a new rating.

Parameters
stdClass$cmcourse module object
stdClass$contextcontext object
string$componentcomponent name
string$ratingarearating area
int$itemidthe item id
int$scaleidthe scale id
int$userratingthe user rating
int$rateduseridthe rated user id
int$aggregationmethodthe aggregation method
Since
Moodle 3.2

◆ check_rating_is_valid()

rating_manager::check_rating_is_valid ( $params)

Validates a submitted rating.

Parameters
array$paramssubmitted data context => object the context in which the rated items exists [required] component => The component the rating belongs to [required] ratingarea => The ratingarea the rating is associated with [required] itemid => int the ID of the object being rated [required] 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. 0 to update all. [required] aggregation => int the aggregation method to apply when calculating grades ie RATING_AGGREGATE_AVERAGE [optional]
Return values
booleantrue if the rating is valid, false if callback not found, throws rating_exception if rating is invalid

◆ delete_ratings()

moodle_database rating_manager::delete_ratings ( $options)

Delete one or more ratings.

Specify either a rating id, an item id or just the context id.

$DB

Parameters
stdClass$options{ contextid => int the context in which the ratings exist [required] ratingid => int the id of an individual rating to delete [optional] userid => int delete the ratings submitted by this user. May be used in conjuction with itemid [optional] itemid => int delete all ratings attached to this item [optional] component => string The component to delete ratings from [optional] ratingarea => string The ratingarea to delete ratings from [optional] }

◆ generate_rating_scale_object()

moodle_database rating_manager::generate_rating_scale_object ( $scaleid)
protected

Generates a scale object that can be returned.

$DB moodle database object

Parameters
int$scaleidscale-type identifier
Return values
stdClassscale for ratings

◆ generate_rating_settings_object()

rating_manager::generate_rating_settings_object ( $options)
protected

Generates a rating settings object based upon the options it is provided.

Parameters
stdClass$options{ context => context the context in which the ratings exists [required] component => string The component the items belong to [required] ratingarea => string The ratingarea the items belong to [required] aggregate => int Aggregation method to apply. RATING_AGGREGATE_AVERAGE, RATING_AGGREGATE_MAXIMUM etc [required] scaleid => int the scale from which the user can select a rating [required] returnurl => string the url to return the user to after submitting a rating. Null for ajax requests [optional] assesstimestart => int only allow rating of items created after this timestamp [optional] assesstimefinish => int only allow rating of items created before this timestamp [optional] plugintype => string plugin type ie 'mod' Used to find the permissions callback [optional] pluginname => string plugin name ie 'forum' Used to find the permissions callback [optional] }
Return values
stdClassrating settings object

◆ get_aggregate_label()

rating_manager::get_aggregate_label ( $aggregationmethod)

Returns a string that describes the aggregation method that was provided.

Parameters
string$aggregationmethod
Return values
stringdescribes the aggregation method that was provided

◆ get_aggregate_types()

rating_manager::get_aggregate_types ( )

Returns array of aggregate types.

Used by ratings.

Return values
arrayaggregate types

◆ get_aggregation_method()

rating_manager::get_aggregation_method ( $aggregate)

Converts an aggregation method constant into something that can be included in SQL.

Parameters
int$aggregateAn aggregation constant. For example, RATING_AGGREGATE_AVERAGE.
Return values
stringan SQL aggregation method

◆ get_all_ratings_for_item()

rating_manager::get_all_ratings_for_item ( $options)

Returns an array of ratings for a given item (forum post, glossary entry etc).

This returns all users ratings for a single item

Parameters
stdClass$options{ context => context the context in which the ratings exists [required] component => component using ratings ie mod_forum [required] ratingarea => ratingarea to associate this rating with [required] itemid => int the id of the associated item (forum post, glossary item etc) [required] sort => string SQL sort by clause [optional] }
Return values
arrayan array of ratings

◆ get_component_ratings_since()

rating_manager::get_component_ratings_since ( $context,
$component,
$since )

Get ratings created since a given time.

Parameters
stdClass$contextcontext object
string$componentcomponent name
int$sincethe time to check
Return values
arraylist of ratings db records since the given timelimit
Since
Moodle 3.2

◆ get_item_time_created()

rating_manager::get_item_time_created ( $item)
protected

Gets the time the given item was created.

TODO: MDL-31511 - Find a better solution for this, its not ideal to test for fields really we should be asking the component the item belongs to what field to look for or even the value we are looking for.

Parameters
stdClass$item
Return values
int|nullreturn null if the created time is unavailable, otherwise return a timestamp

◆ get_plugin_permissions_array()

rating_manager::get_plugin_permissions_array ( $contextid,
$component,
$ratingarea )

Looks for a callback like forum_rating_permissions() to retrieve permissions from the plugin whose items are being rated.

Parameters
int$contextidThe current context id
string$componentthe name of the component that is using ratings ie 'mod_forum'
string$ratingareaThe area the rating is associated with
Return values
arrayrating related permissions

◆ get_ratings()

rating_manager::get_ratings ( $options)

Adds rating objects to an array of items (forum posts, glossary entries etc).

Rating objects are available at $item->rating

Parameters
stdClass$options{ context => context the context in which the ratings exists [required] component => the component name ie mod_forum [required] ratingarea => the ratingarea we are interested in [required] items => array items like forum posts or glossary items. Each item needs an 'id' ie $items[0]->id [required] aggregate => int aggregation method to apply. RATING_AGGREGATE_AVERAGE, RATING_AGGREGATE_MAXIMUM etc [required] scaleid => int the scale from which the user can select a rating [required] userid => int the id of the current user [optional] returnurl => string the url to return the user to after submitting a rating. Null for ajax requests [optional] assesstimestart => int only allow rating of items created after this timestamp [optional] assesstimefinish => int only allow rating of items created before this timestamp [optional]
Return values
arraythe array of items with their ratings attached at $items[0]->rating

◆ get_user_grades()

rating_manager::get_user_grades ( $options)

Returns an array of grades calculated by aggregating item ratings.

Parameters
stdClass$options{ userid => int the id of the user whose items were rated, NOT the user who submitted ratings. 0 to update all. [required] aggregationmethod => int the aggregation method to apply when calculating grades ie RATING_AGGREGATE_AVERAGE [required] scaleid => int the scale from which the user can select a rating. Used for bounds checking. [required] itemtable => int the table containing the items [required] itemtableusercolum => int the column of the user table containing the item owner's user id [required] component => The component for the ratings [required] ratingarea => The ratingarea for the ratings [required] contextid => int the context in which the rated items exist [optional] modulename => string the name of the module [optional] moduleid => int the id of the module instance [optional] }
Return values
arraythe array of the user's grades

◆ initialise_rating_javascript()

rating_manager::initialise_rating_javascript ( moodle_page $page)

Initialises JavaScript to enable AJAX ratings on the provided page.

Parameters
moodle_page$page
Return values
truealways returns true

The documentation for this class was generated from the following file: