diff --git a/lib/db/services.php b/lib/db/services.php index ba733bc80df..abbb1b7ab3a 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -1046,6 +1046,15 @@ $functions = array( 'type' => 'read', 'capabilities' => 'report/completion:view', ), + + // Rating functions. + 'core_rating_get_item_ratings' => array( + 'classname' => 'core_rating_external', + 'methodname' => 'get_item_ratings', + 'description' => 'Retrieve all the ratings for an item.', + 'type' => 'read', + 'capabilities' => 'moodle/rating:view' + ), ); $services = array( @@ -1117,6 +1126,7 @@ $services = array( 'mod_forum_view_forum_discussion', 'core_user_view_user_profile', 'gradereport_user_view_grade_report', + 'core_rating_get_item_ratings', ), 'enabled' => 0, 'restrictedusers' => 0, diff --git a/rating/classes/external.php b/rating/classes/external.php new file mode 100644 index 00000000000..691ca3277e0 --- /dev/null +++ b/rating/classes/external.php @@ -0,0 +1,189 @@ +. + +/** + * Rating external API + * + * @package core_rating + * @category external + * @copyright 2015 Costantino Cito + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.9 + */ + +defined('MOODLE_INTERNAL') || die; + +require_once("$CFG->libdir/externallib.php"); +require_once("$CFG->dirroot/rating/lib.php"); + +/** + * Rating external functions + * + * @package core_rating + * @category external + * @copyright 2015 Costantino Cito + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.9 + */ +class core_rating_external extends external_api { + + /** + * Returns description of get_item_ratings parameters. + * + * @return external_function_parameters + * @since Moodle 2.9 + */ + public static function get_item_ratings_parameters() { + return new external_function_parameters ( + array( + 'contextlevel' => new external_value(PARAM_ALPHA, 'context level: course, module, user, etc...'), + 'instanceid' => new external_value(PARAM_INT, 'the instance id of item associated with the context level'), + 'component' => new external_value(PARAM_COMPONENT, 'component'), + 'ratingarea' => new external_value(PARAM_AREA, 'rating area'), + 'itemid' => new external_value(PARAM_INT, 'associated id'), + 'scaleid' => new external_value(PARAM_INT, 'scale id'), + 'sort' => new external_value(PARAM_ALPHA, 'sort order (firstname, rating or timemodified)') + ) + ); + } + + /** + * Retrieve a list of ratings for a given item (forum post etc) + * + * @param string $contextlevel course, module, user... + * @param int $instanceid the instance if for the context element + * @param string $component the name of the component + * @param string $ratingarea rating area + * @param int $itemid the item id + * @param int $scaleid the scale id + * @param string $sort sql order (firstname, rating or timemodified) + * @return array Result and possible warnings + * @throws moodle_exception + * @since Moodle 2.9 + */ + public static function get_item_ratings($contextlevel, $instanceid, $component, $ratingarea, $itemid, $scaleid, $sort) { + global $USER; + + $warnings = array(); + + $arrayparams = array( + 'contextlevel' => $contextlevel, + 'instanceid' => $instanceid, + 'component' => $component, + 'ratingarea' => $ratingarea, + 'itemid' => $itemid, + 'scaleid' => $scaleid, + 'sort' => $sort + ); + + // Validate and normalize parameters. + $params = self::validate_parameters(self::get_item_ratings_parameters(), $arrayparams); + + $context = self::get_context_from_params($params); + self::validate_context($context); + + // Minimal capability required. + if (!has_capability('moodle/rating:view', $context)) { + throw new moodle_exception('noviewrate', 'rating'); + } + + list($context, $course, $cm) = get_context_info_array($context->id); + + // Can we see all ratings? + $canviewallratings = has_capability('moodle/rating:viewall', $context); + + // Create the Sql sort order string. + switch ($params['sort']) { + case 'firstname': + $sqlsort = "u.firstname ASC"; + break; + case 'rating': + $sqlsort = "r.rating ASC"; + break; + default: + $sqlsort = "r.timemodified ASC"; + } + + $ratingoptions = new stdClass; + $ratingoptions->context = $context; + $ratingoptions->component = $params['component']; + $ratingoptions->ratingarea = $params['ratingarea']; + $ratingoptions->itemid = $params['itemid']; + $ratingoptions->sort = $sqlsort; + + $rm = new rating_manager(); + $ratings = $rm->get_all_ratings_for_item($ratingoptions); + $scalemenu = make_grades_menu($params['scaleid']); + + // If the scale was changed after ratings were submitted some ratings may have a value above the current maximum. + // We can't just do count($scalemenu) - 1 as custom scales start at index 1, not 0. + $maxrating = max(array_keys($scalemenu)); + + $results = array(); + + foreach ($ratings as $rating) { + if ($canviewallratings || $USER->id == $rating->userid) { + if ($rating->rating > $maxrating) { + $rating->rating = $maxrating; + } + $usercontext = context_user::instance($rating->userid); + $profileimageurl = moodle_url::make_webservice_pluginfile_url($usercontext->id, 'user', 'icon', null, '/', 'f1'); + + $result = array(); + $result['id'] = $rating->id; + $result['userid'] = $rating->userid; + $result['userpictureurl'] = $profileimageurl->out(false); + $result['userfullname'] = fullname($rating); + $result['rating'] = $scalemenu[$rating->rating]; + $result['timemodified'] = $rating->timemodified; + $results[] = $result; + } + } + + return array( + 'ratings' => $results, + 'warnings' => $warnings + ); + } + + /** + * Returns description of get_item_ratings result values. + * + * @return external_single_structure + * @since Moodle 2.9 + */ + public static function get_item_ratings_returns() { + + return new external_single_structure( + array( + 'ratings' => new external_multiple_structure( + new external_single_structure( + array( + 'id' => new external_value(PARAM_INT, 'rating id'), + 'userid' => new external_value(PARAM_INT, 'user id'), + 'userpictureurl' => new external_value(PARAM_URL, 'URL user picture'), + 'userfullname' => new external_value(PARAM_NOTAGS, 'user fullname'), + 'rating' => new external_value(PARAM_NOTAGS, 'rating on scale'), + 'timemodified' => new external_value(PARAM_INT, 'time modified (timestamp)') + ), 'Rating' + ), 'list of ratings' + ), + 'warnings' => new external_warnings(), + ) + ); + } + +} diff --git a/rating/tests/externallib_test.php b/rating/tests/externallib_test.php new file mode 100644 index 00000000000..fc42a59daae --- /dev/null +++ b/rating/tests/externallib_test.php @@ -0,0 +1,152 @@ +. + +/** + * External rating functions unit tests + * + * @package core_rating + * @category external + * @copyright 2015 Costantino Cito + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + +global $CFG; + +require_once($CFG->dirroot . '/webservice/tests/helpers.php'); +require_once($CFG->dirroot . '/rating/lib.php'); + +/** + * External rating functions unit tests + * + * @package core_rating + * @category external + * @copyright 2015 Costantino Cito + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +class core_rating_externallib_testcase extends externallib_advanced_testcase { + + /** + * Test get_item_ratings + */ + public function test_get_item_ratings() { + + global $DB, $USER; + + $this->resetAfterTest(true); + + $course = self::getDataGenerator()->create_course(); + $student = $this->getDataGenerator()->create_user(); + $teacher1 = $this->getDataGenerator()->create_user(); + $teacher2 = $this->getDataGenerator()->create_user(); + $studentrole = $DB->get_record('role', array('shortname' => 'student')); + $teacherrole = $DB->get_record('role', array('shortname' => 'teacher')); + + $this->getDataGenerator()->enrol_user($student->id, $course->id, $studentrole->id); + $this->getDataGenerator()->enrol_user($teacher1->id, $course->id, $teacherrole->id); + $this->getDataGenerator()->enrol_user($teacher2->id, $course->id, $teacherrole->id); + + // Create the forum. + $record = new stdClass(); + $record->introformat = FORMAT_HTML; + $record->course = $course->id; + // Set Aggregate type = Average of ratings. + $record->assessed = RATING_AGGREGATE_AVERAGE; + $forum = self::getDataGenerator()->create_module('forum', $record); + + $contextid = context_module::instance($forum->cmid)->id; + + // Add discussion to the forums. + $record = new stdClass(); + $record->course = $course->id; + $record->userid = $student->id; + $record->forum = $forum->id; + $discussion = self::getDataGenerator()->get_plugin_generator('mod_forum')->create_discussion($record); + + // Rete the discussion as teacher1. + $rating1 = new stdClass(); + $rating1->contextid = $contextid; + $rating1->component = 'mod_forum'; + $rating1->ratingarea = 'post'; + $rating1->itemid = $discussion->id; + $rating1->rating = 90; + $rating1->scaleid = 100; + $rating1->userid = $teacher1->id; + $rating1->timecreated = time(); + $rating1->timemodified = time(); + $rating1->id = $DB->insert_record('rating', $rating1); + + // Rete the discussion as teacher2. + $rating2 = new stdClass(); + $rating2->contextid = $contextid; + $rating2->component = 'mod_forum'; + $rating2->ratingarea = 'post'; + $rating2->itemid = $discussion->id; + $rating2->rating = 95; + $rating2->scaleid = 100; + $rating2->userid = $teacher2->id; + $rating2->timecreated = time() + 1; + $rating2->timemodified = time() + 1; + $rating2->id = $DB->insert_record('rating', $rating2); + + // Teachers can see all the ratings. + $this->setUser($teacher1); + + $ratings = core_rating_external::get_item_ratings('module', $forum->cmid, 'mod_forum', 'post', $discussion->id, 100, ''); + // We need to execute the return values cleaning process to simulate the web service server. + $ratings = external_api::clean_returnvalue(core_rating_external::get_item_ratings_returns(), $ratings); + $this->assertCount(2, $ratings['ratings']); + + $indexedratings = array(); + foreach ($ratings['ratings'] as $rating) { + $indexedratings[$rating['id']] = $rating; + } + $this->assertEquals($rating1->rating.' / '.$rating1->scaleid, $indexedratings[$rating1->id]['rating']); + $this->assertEquals($rating2->rating.' / '.$rating2->scaleid, $indexedratings[$rating2->id]['rating']); + + $this->assertEquals($rating1->userid, $indexedratings[$rating1->id]['userid']); + $this->assertEquals($rating2->userid, $indexedratings[$rating2->id]['userid']); + + // Student can see ratings. + $this->setUser($student); + + $ratings = core_rating_external::get_item_ratings('module', $forum->cmid, 'mod_forum', 'post', $discussion->id, 100, ''); + // We need to execute the return values cleaning process to simulate the web service server. + $ratings = external_api::clean_returnvalue(core_rating_external::get_item_ratings_returns(), $ratings); + $this->assertCount(2, $ratings['ratings']); + + // Invalid item. + $ratings = core_rating_external::get_item_ratings('module', $forum->cmid, 'mod_forum', 'post', 0, 100, ''); + // We need to execute the return values cleaning process to simulate the web service server. + $ratings = external_api::clean_returnvalue(core_rating_external::get_item_ratings_returns(), $ratings); + $this->assertCount(0, $ratings['ratings']); + + // Invalid area. + $ratings = core_rating_external::get_item_ratings('module', $forum->cmid, 'mod_forum', 'xyz', $discussion->id, 100, ''); + // We need to execute the return values cleaning process to simulate the web service server. + $ratings = external_api::clean_returnvalue(core_rating_external::get_item_ratings_returns(), $ratings); + $this->assertCount(0, $ratings['ratings']); + + // Invalid context. invalid_parameter_exception. + try { + $ratings = core_rating_external::get_item_ratings('module', 0, 'mod_forum', 'post', $discussion->id, 100, ''); + $this->fail('Exception expected due invalid context.'); + } catch (invalid_parameter_exception $e) { + $this->assertEquals('invalidparameter', $e->errorcode); + } + } +} diff --git a/version.php b/version.php index 9f17d6ef6d1..82abb6986d7 100644 --- a/version.php +++ b/version.php @@ -29,7 +29,7 @@ defined('MOODLE_INTERNAL') || die(); -$version = 2015040200.05; // YYYYMMDD = weekly release date of this DEV branch. +$version = 2015040200.06; // YYYYMMDD = weekly release date of this DEV branch. // RR = release increments - 00 in DEV branches. // .XX = incremental changes.