[Summary view]

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

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