[Summary view]

Differences Between: [Versions 310 and 401] [Versions 39 and 401] [Versions 401 and 402] [Versions 401 and 403]

   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   * Rating 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  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  require_once("$CFG->libdir/externallib.php");
  30  require_once("$CFG->dirroot/rating/lib.php");
  31  
  32  /**
  33   * Rating external functions
  34   *
  35   * @package    core_rating
  36   * @category   external
  37   * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
  38   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39   * @since      Moodle 2.9
  40   */
  41  class core_rating_external extends external_api {
  42  
  43      /**
  44       * Returns description of get_item_ratings parameters.
  45       *
  46       * @return external_function_parameters
  47       * @since Moodle 2.9
  48       */
  49      public static function get_item_ratings_parameters() {
  50          return new external_function_parameters (
  51              array(
  52                  'contextlevel'  => new external_value(PARAM_ALPHA, 'context level: course, module, user, etc...'),
  53                  'instanceid'    => new external_value(PARAM_INT, 'the instance id of item associated with the context level'),
  54                  'component'     => new external_value(PARAM_COMPONENT, 'component'),
  55                  'ratingarea'    => new external_value(PARAM_AREA, 'rating area'),
  56                  'itemid'        => new external_value(PARAM_INT, 'associated id'),
  57                  'scaleid'       => new external_value(PARAM_INT, 'scale id'),
  58                  'sort'          => new external_value(PARAM_ALPHA, 'sort order (firstname, rating or timemodified)')
  59              )
  60          );
  61      }
  62  
  63      /**
  64       * Retrieve a list of ratings for a given item (forum post etc)
  65       *
  66       * @param string $contextlevel course, module, user...
  67       * @param int $instanceid the instance if for the context element
  68       * @param string $component the name of the component
  69       * @param string $ratingarea rating area
  70       * @param int $itemid the item id
  71       * @param int $scaleid the scale id
  72       * @param string $sort sql order (firstname, rating or timemodified)
  73       * @return array Result and possible warnings
  74       * @throws moodle_exception
  75       * @since Moodle 2.9
  76       */
  77      public static function get_item_ratings($contextlevel, $instanceid, $component, $ratingarea, $itemid, $scaleid, $sort) {
  78          global $USER, $PAGE;
  79  
  80          $warnings = array();
  81  
  82          $arrayparams = array(
  83              'contextlevel' => $contextlevel,
  84              'instanceid'   => $instanceid,
  85              'component'    => $component,
  86              'ratingarea'   => $ratingarea,
  87              'itemid'       => $itemid,
  88              'scaleid'      => $scaleid,
  89              'sort'         => $sort
  90          );
  91  
  92          // Validate and normalize parameters.
  93          $params = self::validate_parameters(self::get_item_ratings_parameters(), $arrayparams);
  94  
  95          $context = self::get_context_from_params($params);
  96          self::validate_context($context);
  97  
  98          // Minimal capability required.
  99          $callbackparams = array('contextid' => $context->id,
 100                          'component' => $component,
 101                          'ratingarea' => $ratingarea,
 102                          'itemid' => $itemid,
 103                          'scaleid' => $scaleid);
 104          if (!has_capability('moodle/rating:view', $context) ||
 105                  !component_callback($component, 'rating_can_see_item_ratings', array($callbackparams), true)) {
 106              throw new moodle_exception('noviewrate', 'rating');
 107          }
 108  
 109          list($context, $course, $cm) = get_context_info_array($context->id);
 110  
 111          // Can we see all ratings?
 112          $canviewallratings = has_capability('moodle/rating:viewall', $context);
 113  
 114          // Create the Sql sort order string.
 115          switch ($params['sort']) {
 116              case 'firstname':
 117                  $sqlsort = "u.firstname ASC";
 118                  break;
 119              case 'rating':
 120                  $sqlsort = "r.rating ASC";
 121                  break;
 122              default:
 123                  $sqlsort = "r.timemodified ASC";
 124          }
 125  
 126          $ratingoptions = new stdClass;
 127          $ratingoptions->context = $context;
 128          $ratingoptions->component = $params['component'];
 129          $ratingoptions->ratingarea = $params['ratingarea'];
 130          $ratingoptions->itemid = $params['itemid'];
 131          $ratingoptions->sort = $sqlsort;
 132  
 133          $rm = new rating_manager();
 134          $ratings = $rm->get_all_ratings_for_item($ratingoptions);
 135          $scalemenu = make_grades_menu($params['scaleid']);
 136  
 137          // If the scale was changed after ratings were submitted some ratings may have a value above the current maximum.
 138          // We can't just do count($scalemenu) - 1 as custom scales start at index 1, not 0.
 139          $maxrating = max(array_keys($scalemenu));
 140  
 141          $results = array();
 142  
 143          foreach ($ratings as $rating) {
 144              if ($canviewallratings || $USER->id == $rating->userid) {
 145                  if ($rating->rating > $maxrating) {
 146                      $rating->rating = $maxrating;
 147                  }
 148  
 149                  $result = array();
 150                  $result['id'] = $rating->id;
 151                  $result['userid'] = $rating->userid;
 152                  $result['userfullname'] = fullname($rating);
 153                  $result['rating'] = $scalemenu[$rating->rating];
 154                  $result['timemodified'] = $rating->timemodified;
 155  
 156                  // The rating object has all the required fields for generating the picture url.
 157                  // Undo the aliasing of the user id column from fields::get_sql.
 158                  $rating->id = $rating->userid;
 159                  $userpicture = new user_picture($rating);
 160                  $userpicture->size = 1; // Size f1.
 161                  $result['userpictureurl'] = $userpicture->get_url($PAGE)->out(false);
 162  
 163                  $results[] = $result;
 164              }
 165          }
 166  
 167          return array(
 168              'ratings' => $results,
 169              'warnings' => $warnings
 170          );
 171      }
 172  
 173      /**
 174       * Returns description of get_item_ratings result values.
 175       *
 176       * @return external_single_structure
 177       * @since Moodle 2.9
 178       */
 179      public static function get_item_ratings_returns() {
 180  
 181          return new external_single_structure(
 182              array(
 183                  'ratings'    => new external_multiple_structure(
 184                      new external_single_structure(
 185                          array(
 186                              'id'              => new external_value(PARAM_INT,  'rating id'),
 187                              'userid'          => new external_value(PARAM_INT,  'user id'),
 188                              'userpictureurl'  => new external_value(PARAM_URL,  'URL user picture'),
 189                              'userfullname'    => new external_value(PARAM_NOTAGS, 'user fullname'),
 190                              'rating'          => new external_value(PARAM_NOTAGS, 'rating on scale'),
 191                              'timemodified'    => new external_value(PARAM_INT,  'time modified (timestamp)')
 192                          ), 'Rating'
 193                      ), 'list of ratings'
 194                  ),
 195                  'warnings'  => new external_warnings(),
 196              )
 197          );
 198      }
 199  
 200      /**
 201       * Returns description of add_rating parameters.
 202       *
 203       * @return external_function_parameters
 204       * @since Moodle 3.2
 205       */
 206      public static function add_rating_parameters() {
 207          return new external_function_parameters (
 208              array(
 209                  'contextlevel'  => new external_value(PARAM_ALPHA, 'context level: course, module, user, etc...'),
 210                  'instanceid'    => new external_value(PARAM_INT, 'the instance id of item associated with the context level'),
 211                  'component'     => new external_value(PARAM_COMPONENT, 'component'),
 212                  'ratingarea'    => new external_value(PARAM_AREA, 'rating area'),
 213                  'itemid'        => new external_value(PARAM_INT, 'associated id'),
 214                  'scaleid'       => new external_value(PARAM_INT, 'scale id'),
 215                  'rating'        => new external_value(PARAM_INT, 'user rating'),
 216                  'rateduserid'   => new external_value(PARAM_INT, 'rated user id'),
 217                  'aggregation'   => new external_value(PARAM_INT, 'agreggation method', VALUE_DEFAULT, RATING_AGGREGATE_NONE)
 218              )
 219          );
 220      }
 221  
 222      /**
 223       * Adds a rating to an item
 224       *
 225       * @param string $contextlevel course, module, user...
 226       * @param int $instanceid the instance if for the context element
 227       * @param string $component the name of the component
 228       * @param string $ratingarea rating area
 229       * @param int $itemid the item id
 230       * @param int $scaleid the scale id
 231       * @param int $rating the user rating
 232       * @param int $rateduserid the rated user id
 233       * @param int $aggregation the aggregation method
 234       * @return array result and possible warnings
 235       * @throws moodle_exception
 236       * @since Moodle 3.2
 237       */
 238      public static function add_rating($contextlevel, $instanceid, $component, $ratingarea, $itemid, $scaleid, $rating, $rateduserid,
 239                                          $aggregation = RATING_AGGREGATE_NONE) {
 240          $warnings = array();
 241  
 242          $params = array(
 243              'contextlevel' => $contextlevel,
 244              'instanceid'   => $instanceid,
 245              'component'    => $component,
 246              'ratingarea'   => $ratingarea,
 247              'itemid'       => $itemid,
 248              'scaleid'      => $scaleid,
 249              'rating'       => $rating,
 250              'rateduserid'  => $rateduserid,
 251              'aggregation'  => $aggregation,
 252          );
 253  
 254          // Validate and normalize parameters.
 255          $params = self::validate_parameters(self::add_rating_parameters(), $params);
 256  
 257          $context = self::get_context_from_params($params);
 258          self::validate_context($context);
 259          $cm = get_coursemodule_from_id(false, $context->instanceid, 0, false, MUST_EXIST);
 260  
 261          require_capability('moodle/rating:rate', $context);
 262  
 263          $rm = new rating_manager();
 264          $result = $rm->add_rating($cm, $context, $params['component'], $params['ratingarea'], $params['itemid'], $params['scaleid'],
 265                                      $params['rating'], $params['rateduserid'], $params['aggregation']);
 266  
 267          if (!empty($result->error)) {
 268              throw new moodle_exception($result->error, 'rating');
 269          }
 270  
 271          $returndata = array(
 272              'success' => $result->success,
 273              'warnings' => $warnings
 274          );
 275  
 276          if (isset($result->aggregate)) {
 277              $returndata['aggregate'] = $result->aggregate;
 278              $returndata['count'] = $result->count;
 279              $returndata['itemid'] = $result->itemid;
 280          }
 281  
 282          return $returndata;
 283      }
 284  
 285      /**
 286       * Returns description of add_rating result values.
 287       *
 288       * @return external_single_structure
 289       * @since Moodle 3.2
 290       */
 291      public static function add_rating_returns() {
 292  
 293          return new external_single_structure(
 294              array(
 295                  'success' => new external_value(PARAM_BOOL, 'Whether the rate was successfully created'),
 296                  'aggregate' => new external_value(PARAM_TEXT, 'New aggregate', VALUE_OPTIONAL),
 297                  'count' => new external_value(PARAM_INT, 'Ratings count', VALUE_OPTIONAL),
 298                  'itemid' => new external_value(PARAM_INT, 'Rating item id', VALUE_OPTIONAL),
 299                  'warnings'  => new external_warnings(),
 300              )
 301          );
 302      }
 303  }