[Summary view]

Differences Between: [Versions 311 and 402] [Versions 311 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 functions utility class.
  19   *
  20   * @package    core_rating
  21   * @copyright  2017 Juan Leyva
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  namespace core_rating\external;
  26  
  27  defined('MOODLE_INTERNAL') || die();
  28  
  29  require_once($CFG->dirroot . '/rating/lib.php');
  30  require_once($CFG->libdir . '/externallib.php');
  31  
  32  use external_multiple_structure;
  33  use external_single_structure;
  34  use external_value;
  35  use rating_manager;
  36  use stdClass;
  37  
  38  /**
  39   * Rating external functions utility class.
  40   *
  41   * @package   core_rating
  42   * @copyright 2017 Juan Leyva
  43   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  44   * @since     Moodle 3.4
  45   */
  46  class util {
  47  
  48      /**
  49       * Returns the ratings definition for external functions.
  50       */
  51      public static function external_ratings_structure() {
  52  
  53          return new external_single_structure (
  54              [
  55                  'contextid' => new external_value(PARAM_INT, 'Context id.'),
  56                  'component' => new external_value(PARAM_COMPONENT, 'Context name.'),
  57                  'ratingarea' => new external_value(PARAM_AREA, 'Rating area name.'),
  58                  'canviewall' => new external_value(PARAM_BOOL, 'Whether the user can view all the individual ratings.',
  59                      VALUE_OPTIONAL),
  60                  'canviewany' => new external_value(PARAM_BOOL, 'Whether the user can view aggregate of ratings of others.',
  61                      VALUE_OPTIONAL),
  62                  'scales' => new external_multiple_structure(
  63                      new external_single_structure (
  64                          [
  65                              'id' => new external_value(PARAM_INT, 'Scale id.'),
  66                              'courseid' => new external_value(PARAM_INT, 'Course id.', VALUE_OPTIONAL),
  67                              'name' => new external_value(PARAM_TEXT, 'Scale name (when a real scale is used).', VALUE_OPTIONAL),
  68                              'max' => new external_value(PARAM_INT, 'Max value for the scale.'),
  69                              'isnumeric' => new external_value(PARAM_BOOL, 'Whether is a numeric scale.'),
  70                              'items' => new external_multiple_structure(
  71                                  new external_single_structure (
  72                                      [
  73                                          'value' => new external_value(PARAM_INT, 'Scale value/option id.'),
  74                                          'name' => new external_value(PARAM_NOTAGS, 'Scale name.'),
  75                                      ]
  76                                  ), 'Scale items. Only returned for not numerical scales.', VALUE_OPTIONAL
  77                              )
  78                          ], 'Scale information'
  79                      ), 'Different scales used information', VALUE_OPTIONAL
  80                  ),
  81                  'ratings' => new external_multiple_structure(
  82                      new external_single_structure (
  83                          [
  84                              'itemid' => new external_value(PARAM_INT, 'Item id.'),
  85                              'scaleid' => new external_value(PARAM_INT, 'Scale id.', VALUE_OPTIONAL),
  86                              'userid' => new external_value(PARAM_INT, 'User who rated id.', VALUE_OPTIONAL),
  87                              'aggregate' => new external_value(PARAM_FLOAT, 'Aggregated ratings grade.', VALUE_OPTIONAL),
  88                              'aggregatestr' => new external_value(PARAM_NOTAGS, 'Aggregated ratings as string.', VALUE_OPTIONAL),
  89                              'aggregatelabel' => new external_value(PARAM_NOTAGS, 'The aggregation label.', VALUE_OPTIONAL),
  90                              'count' => new external_value(PARAM_INT, 'Ratings count (used when aggregating).', VALUE_OPTIONAL),
  91                              'rating' => new external_value(PARAM_INT, 'The rating the user gave.', VALUE_OPTIONAL),
  92                              'canrate' => new external_value(PARAM_BOOL, 'Whether the user can rate the item.', VALUE_OPTIONAL),
  93                              'canviewaggregate' => new external_value(PARAM_BOOL, 'Whether the user can view the aggregated grade.',
  94                                  VALUE_OPTIONAL),
  95                          ]
  96                      ), 'The ratings', VALUE_OPTIONAL
  97                  ),
  98              ], 'Rating information', VALUE_OPTIONAL
  99          );
 100      }
 101  
 102      /**
 103       * Returns rating information inside a data structure like the one defined by external_ratings_structure.
 104       *
 105       * @param  stdClass $mod        course module object
 106       * @param  stdClass $context    context object
 107       * @param  str $component       component name
 108       * @param  str $ratingarea      rating area
 109       * @param  array $items         items to add ratings
 110       * @return array ratings ready to be returned by external functions.
 111       */
 112      public static function get_rating_info($mod, $context, $component, $ratingarea, $items) {
 113          global $USER;
 114  
 115          $ratinginfo = [
 116              'contextid' => $context->id,
 117              'component' => $component,
 118              'ratingarea' => $ratingarea,
 119              'canviewall' => null,
 120              'canviewany' => null,
 121              'scales' => [],
 122              'ratings' => [],
 123          ];
 124          if ($mod->assessed != RATING_AGGREGATE_NONE) {
 125              $ratingoptions = new stdClass;
 126              $ratingoptions->context = $context;
 127              $ratingoptions->component = $component;
 128              $ratingoptions->ratingarea = $ratingarea;
 129              $ratingoptions->items = $items;
 130              $ratingoptions->aggregate = $mod->assessed;
 131              $ratingoptions->scaleid = $mod->scale;
 132              $ratingoptions->userid = $USER->id;
 133              $ratingoptions->assesstimestart = $mod->assesstimestart;
 134              $ratingoptions->assesstimefinish = $mod->assesstimefinish;
 135  
 136              $rm = new rating_manager();
 137              $allitems = $rm->get_ratings($ratingoptions);
 138  
 139              foreach ($allitems as $item) {
 140                  if (empty($item->rating)) {
 141                      continue;
 142                  }
 143                  $rating = [
 144                      'itemid' => $item->rating->itemid,
 145                      'scaleid' => $item->rating->scaleid,
 146                      'userid' => $item->rating->userid,
 147                      'rating' => $item->rating->rating,
 148                      'canrate' => $item->rating->user_can_rate(),
 149                      'canviewaggregate' => $item->rating->user_can_view_aggregate(),
 150                  ];
 151                  // Fill the capabilities fields the first time (the rest are the same values because they are not item dependent).
 152                  if ($ratinginfo['canviewall'] === null) {
 153                      $ratinginfo['canviewall'] = $item->rating->settings->permissions->viewall &&
 154                                                      $item->rating->settings->pluginpermissions->viewall;
 155                      $ratinginfo['canviewany'] = $item->rating->settings->permissions->viewany &&
 156                                                      $item->rating->settings->pluginpermissions->viewany;
 157                  }
 158  
 159                  // Return only the information the user can see.
 160                  if ($rating['canviewaggregate']) {
 161                      $rating['aggregate'] = $item->rating->aggregate;
 162                      $rating['aggregatestr'] = $item->rating->get_aggregate_string();
 163                      $rating['aggregatelabel'] = $rm->get_aggregate_label($item->rating->settings->aggregationmethod);
 164                      $rating['count'] = $item->rating->count;
 165                  }
 166                  // If the user can rate, return the scale information only one time.
 167                  if ($rating['canrate'] &&
 168                          !empty($item->rating->settings->scale->id) &&
 169                          !isset($ratinginfo['scales'][$item->rating->settings->scale->id])) {
 170                      $scale = $item->rating->settings->scale;
 171                      // Return only non numeric scales (to avoid return lots of data just including items from 0 to $scale->max).
 172                      if (!$scale->isnumeric) {
 173                          $scaleitems = [];
 174                          foreach ($scale->scaleitems as $value => $name) {
 175                              $scaleitems[] = [
 176                                  'name' => $name,
 177                                  'value' => $value,
 178                              ];
 179                          }
 180                          $scale->items = $scaleitems;
 181                      }
 182                      $ratinginfo['scales'][$item->rating->settings->scale->id] = (array) $scale;
 183                  }
 184                  $ratinginfo['ratings'][] = $rating;
 185              }
 186          }
 187          return $ratinginfo;
 188      }
 189  }