MDL-49347 rating: New external function core_rating_get_item_ratings
[moodle.git] / rating / classes / external.php
CommitLineData
db5b6971
CC
1<?php
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16
17/**
18 * Completion external API
19 *
20 * @package core_rating
21 * @category external
22 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 * @since Moodle 2.9
25 */
26
27require_once("$CFG->libdir/externallib.php");
28require_once("$CFG->dirroot/rating/lib.php");
29
30/**
31 * Completion external functions
32 *
33 * @package core_rating
34 * @category external
35 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com>
36 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37 * @since Moodle 2.9
38 */
39class core_rating_external extends external_api {
40
41 /**
42 * Returns description of get_item_ratings parameters.
43 *
44 * @return external_function_parameters
45 * @since Moodle 2.9
46 */
47 public static function get_item_ratings_parameters() {
48 return new external_function_parameters (
49 array(
50 'contextlevel' => new external_value(PARAM_ALPHA, 'contextlevel'),
51 'instanceid' => new external_value(PARAM_INT, 'The Instance id of item associated with the context level'),
52 'component' => new external_value(PARAM_COMPONENT, 'component'),
53 'ratingarea' => new external_value(PARAM_AREA, 'Rating area', VALUE_DEFAULT, ''),
54 'itemid' => new external_value(PARAM_INT, 'Associated id'),
55 'scaleid' => new external_value(PARAM_INT, 'Scale id'),
56 'sort' => new external_value(PARAM_TEXT, 'Sort order', VALUE_DEFAULT, ''),
57 )
58 );
59 }
60
61 /**
62 * Getting list of ratings for a given item (forum post etc)
63 * @param string $contextlevel ('context_course', etc..)
64 * @param int $instanceid (eg. the 'id' in the 'book' table)
65 * @param string $component the name of the component
66 * @param string|null $ratingarea
67 * @param int $itemid the item id
68 * @param int $scaleid the scale id
69 * @param string $sort sql order
70 * @return array Result and possible warnings
71 * @throws moodle_exception
72 * @since Moodle 2.9
73 */
74 public static function get_item_ratings($contextlevel, $instanceid, $component, $ratingarea, $itemid, $scaleid, $sort) {
75 global $USER;
76
77 $arrayparams = array(
78 'contextlevel' => $contextlevel,
79 'instanceid' => $instanceid,
80 'component' => $component,
81 'ratingarea' => $ratingarea,
82 'itemid' => $itemid,
83 'scaleid' => $scaleid,
84 'sort' => $sort);
85
86 // Validate and normalize parameters.
87 $params = self::validate_parameters(self::get_item_ratings_parameters(), $arrayparams);
88
89 $context = self::get_context_from_params($params);
90 self::validate_context($context);
91 list($context, $course, $cm) = get_context_info_array($context->id);
92
93 // Minimal capability required.
94 if (!has_capability('moodle/rating:view', $context)) {
95 throw new moodle_exception('noviewrate', 'rating');
96 }
97
98 // Can we see all ratings?
99 $canviewallratings = has_capability('moodle/rating:viewall', $context);
100
101 // Create the Sql sort order string.
102 switch ($params['sort']) {
103 case 'firstname':
104 $sqlsort = "u.firstname ASC";
105 break;
106 case 'rating':
107 $sqlsort = "r.rating ASC";
108 break;
109 default:
110 $sqlsort = "r.timemodified ASC";
111 }
112
113 $ratingoptions = new stdClass;
114 $ratingoptions->context = $context;
115 $ratingoptions->component = $params['component'];
116 $ratingoptions->ratingarea = $params['ratingarea'];
117 $ratingoptions->itemid = $params['itemid'];
118 $ratingoptions->sort = $sqlsort;
119
120 $rm = new rating_manager();
121 $ratings = $rm->get_all_ratings_for_item($ratingoptions);
122 $scalemenu = make_grades_menu($params['scaleid']);
123
124 // If the scale was changed after ratings were submitted some ratings may have a value above the current maximum.
125 // We can't just do count($scalemenu) - 1 as custom scales start at index 1, not 0.
126 $maxrating = max(array_keys($scalemenu));
127
128 $results = array();
129
130 foreach ($ratings as $rating) {
131 if ($canviewallratings || $USER->id == $rating->userid) {
132 $result = array();
133 $usercontext = context_user::instance($rating->userid);
134 $profileimageurl = moodle_url::make_pluginfile_url($usercontext->id, 'user', 'icon', null, '/', 'f1');
135 $result['userid'] = $rating->userid;
136 $result['userpictureurl'] = $profileimageurl->out(false);
137 $result['fullname'] = fullname($rating);
138 $result['rating'] = $scalemenu[$rating->rating];
139 $result['timemodified'] = $rating->timemodified;
140 $results[] = $result;
141 }
142 }
143
144 $warnings = array();
145 return array('ratings' => $results, 'warning' => $warnings);
146 }
147
148 /**
149 * Returns description of get_item_ratings result values.
150 *
151 * @return external_single_structure
152 * @since Moodle 2.9
153 */
154 public static function get_item_ratings_returns() {
155
156 return new external_single_structure(
157 array(
158 'ratings' => new external_multiple_structure(
159 new external_single_structure(
160 array(
161 'userid' => new external_value(PARAM_INT, 'User id'),
162 'userpictureurl' => new external_value(PARAM_URL, 'URL user picture'),
163 'fullname' => new external_value(PARAM_TEXT, 'fullname'),
164 'rating' => new external_value(PARAM_TEXT, 'Rating on scale'),
165 'timemodified' => new external_value(PARAM_INT, 'Time modified (timestamp)')
166 ), 'Ratings'
167 ), 'List of ratings'
168 ),
169 'warnings' => new external_warnings(),
170 )
171 );
172 }
173
174}