[Summary view] [Print] [Text view]

   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   * External grade report user API
  19   *
  20   * @package    gradereport_user
  21   * @copyright  2015 Juan Leyva <juan@moodle.com>
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  defined('MOODLE_INTERNAL') || die;
  26  
  27  require_once("$CFG->libdir/externallib.php");
  28  
  29  
  30  /**
  31   * External grade report API implementation
  32   *
  33   * @package    gradereport_user
  34   * @copyright  2015 Juan Leyva <juan@moodle.com>
  35   * @category   external
  36   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  37   */
  38  class gradereport_user_external extends external_api {
  39  
  40      /**
  41       * Describes the parameters for get_grades_table.
  42       *
  43       * @return external_external_function_parameters
  44       * @since Moodle 2.9
  45       */
  46      public static function get_grades_table_parameters() {
  47          return new external_function_parameters (
  48              array(
  49                  'courseid' => new external_value(PARAM_INT, 'Course Id', VALUE_REQUIRED),
  50                  'userid'   => new external_value(PARAM_INT, 'Return grades only for this user (optional)', VALUE_DEFAULT, 0)
  51              )
  52          );
  53      }
  54  
  55      /**
  56       * Returns a list of grades tables for users in a course.
  57       *
  58       * @param int $courseid Course Id
  59       * @param int $userid   Only this user (optional)
  60       *
  61       * @return array the grades tables
  62       * @since Moodle 2.9
  63       */
  64      public static function get_grades_table($courseid, $userid = 0) {
  65          global $CFG, $USER;
  66  
  67          $warnings = array();
  68  
  69          // Validate the parameter.
  70          $params = self::validate_parameters(self::get_grades_table_parameters(),
  71              array(
  72                  'courseid' => $courseid,
  73                  'userid' => $userid)
  74              );
  75  
  76          // Compact/extract functions are not recommended.
  77          $courseid = $params['courseid'];
  78          $userid   = $params['userid'];
  79  
  80          // Function get_course internally throws an exception if the course doesn't exist.
  81          $course = get_course($courseid);
  82  
  83          $context = context_course::instance($courseid);
  84          self::validate_context($context);
  85  
  86          // Specific capabilities.
  87          require_capability('gradereport/user:view', $context);
  88  
  89          $user = null;
  90  
  91          if (empty($userid)) {
  92              require_capability('moodle/grade:viewall', $context);
  93          } else {
  94              $user = core_user::get_user($userid, '*', MUST_EXIST);
  95              core_user::require_active_user($user);
  96          }
  97  
  98          $access = false;
  99  
 100          if (has_capability('moodle/grade:viewall', $context)) {
 101              // Can view all course grades.
 102              $access = true;
 103          } else if ($userid == $USER->id and has_capability('moodle/grade:view', $context) and $course->showgrades) {
 104              // View own grades.
 105              $access = true;
 106          }
 107  
 108          if (!$access) {
 109              throw new moodle_exception('nopermissiontoviewgrades', 'error');
 110          }
 111  
 112          // Require files here to save some memory in case validation fails.
 113          require_once($CFG->dirroot . '/group/lib.php');
 114          require_once($CFG->libdir  . '/gradelib.php');
 115          require_once($CFG->dirroot . '/grade/lib.php');
 116          require_once($CFG->dirroot . '/grade/report/user/lib.php');
 117  
 118          // Force regrade to update items marked as 'needupdate'.
 119          grade_regrade_final_grades($course->id);
 120  
 121          $gpr = new grade_plugin_return(
 122              array(
 123                  'type' => 'report',
 124                  'plugin' => 'user',
 125                  'courseid' => $courseid,
 126                  'userid' => $userid)
 127              );
 128  
 129          $tables = array();
 130  
 131          // Just one user.
 132          if ($user) {
 133              $report = new grade_report_user($courseid, $gpr, $context, $userid);
 134              $report->fill_table();
 135  
 136              $tables[] = array(
 137                  'courseid'      => $courseid,
 138                  'userid'        => $user->id,
 139                  'userfullname'  => fullname($user),
 140                  'maxdepth'      => $report->maxdepth,
 141                  'tabledata'     => $report->tabledata
 142              );
 143  
 144          } else {
 145              $defaultgradeshowactiveenrol = !empty($CFG->grade_report_showonlyactiveenrol);
 146              $showonlyactiveenrol = get_user_preferences('grade_report_showonlyactiveenrol', $defaultgradeshowactiveenrol);
 147              $showonlyactiveenrol = $showonlyactiveenrol || !has_capability('moodle/course:viewsuspendedusers', $context);
 148  
 149              $gui = new graded_users_iterator($course);
 150              $gui->require_active_enrolment($showonlyactiveenrol);
 151              $gui->init();
 152  
 153              while ($userdata = $gui->next_user()) {
 154                  $currentuser = $userdata->user;
 155                  $report = new grade_report_user($courseid, $gpr, $context, $currentuser->id);
 156                  $report->fill_table();
 157  
 158                  $tables[] = array(
 159                      'courseid'      => $courseid,
 160                      'userid'        => $currentuser->id,
 161                      'userfullname'  => fullname($currentuser),
 162                      'maxdepth'      => $report->maxdepth,
 163                      'tabledata'     => $report->tabledata
 164                  );
 165              }
 166              $gui->close();
 167          }
 168  
 169          $result = array();
 170          $result['tables'] = $tables;
 171          $result['warnings'] = $warnings;
 172          return $result;
 173      }
 174  
 175      /**
 176       * Creates a table column structure
 177       *
 178       * @return array
 179       * @since  Moodle 2.9
 180       */
 181      private static function grades_table_column() {
 182          return array (
 183              'class'   => new external_value(PARAM_RAW, 'class'),
 184              'content' => new external_value(PARAM_RAW, 'cell content'),
 185              'headers' => new external_value(PARAM_RAW, 'headers')
 186          );
 187      }
 188  
 189      /**
 190       * Describes tget_grades_table return value.
 191       *
 192       * @return external_single_structure
 193       * @since Moodle 2.9
 194       */
 195      public static function get_grades_table_returns() {
 196          return new external_single_structure(
 197              array(
 198                  'tables' => new external_multiple_structure(
 199                      new external_single_structure(
 200                          array(
 201                              'courseid' => new external_value(PARAM_INT, 'course id'),
 202                              'userid'   => new external_value(PARAM_INT, 'user id'),
 203                              'userfullname' => new external_value(PARAM_TEXT, 'user fullname'),
 204                              'maxdepth'   => new external_value(PARAM_INT, 'table max depth (needed for printing it)'),
 205                              'tabledata' => new external_multiple_structure(
 206                                  new external_single_structure(
 207                                      array(
 208                                          'itemname' => new external_single_structure(
 209                                              array (
 210                                                  'class' => new external_value(PARAM_RAW, 'class'),
 211                                                  'colspan' => new external_value(PARAM_INT, 'col span'),
 212                                                  'content'  => new external_value(PARAM_RAW, 'cell content'),
 213                                                  'celltype'  => new external_value(PARAM_RAW, 'cell type'),
 214                                                  'id'  => new external_value(PARAM_ALPHANUMEXT, 'id')
 215                                              ), 'The item returned data', VALUE_OPTIONAL
 216                                          ),
 217                                          'leader' => new external_single_structure(
 218                                              array (
 219                                                  'class' => new external_value(PARAM_RAW, 'class'),
 220                                                  'rowspan' => new external_value(PARAM_INT, 'row span')
 221                                              ), 'The item returned data', VALUE_OPTIONAL
 222                                          ),
 223                                          'weight' => new external_single_structure(
 224                                              self::grades_table_column(), 'weight column', VALUE_OPTIONAL
 225                                          ),
 226                                          'grade' => new external_single_structure(
 227                                              self::grades_table_column(), 'grade column', VALUE_OPTIONAL
 228                                          ),
 229                                          'range' => new external_single_structure(
 230                                              self::grades_table_column(), 'range column', VALUE_OPTIONAL
 231                                          ),
 232                                          'percentage' => new external_single_structure(
 233                                              self::grades_table_column(), 'percentage column', VALUE_OPTIONAL
 234                                          ),
 235                                          'lettergrade' => new external_single_structure(
 236                                              self::grades_table_column(), 'lettergrade column', VALUE_OPTIONAL
 237                                          ),
 238                                          'rank' => new external_single_structure(
 239                                              self::grades_table_column(), 'rank column', VALUE_OPTIONAL
 240                                          ),
 241                                          'average' => new external_single_structure(
 242                                              self::grades_table_column(), 'average column', VALUE_OPTIONAL
 243                                          ),
 244                                          'feedback' => new external_single_structure(
 245                                              self::grades_table_column(), 'feedback column', VALUE_OPTIONAL
 246                                          ),
 247                                          'contributiontocoursetotal' => new external_single_structure(
 248                                              self::grades_table_column(), 'contributiontocoursetotal column', VALUE_OPTIONAL
 249                                          ),
 250                                      ), 'table'
 251                                  )
 252                              )
 253                          )
 254                      )
 255                  ),
 256                  'warnings' => new external_warnings()
 257              )
 258          );
 259      }
 260  
 261      /**
 262       * Returns description of method parameters
 263       *
 264       * @return external_function_parameters
 265       * @since Moodle 2.9
 266       */
 267      public static function view_grade_report_parameters() {
 268          return new external_function_parameters(
 269              array(
 270                  'courseid' => new external_value(PARAM_INT, 'id of the course'),
 271                  'userid' => new external_value(PARAM_INT, 'id of the user, 0 means current user', VALUE_DEFAULT, 0)
 272              )
 273          );
 274      }
 275  
 276      /**
 277       * Trigger the user report events, do the same that the web interface view of the report
 278       *
 279       * @param int $courseid id of course
 280       * @param int $userid id of the user the report belongs to
 281       * @return array of warnings and status result
 282       * @since Moodle 2.9
 283       * @throws moodle_exception
 284       */
 285      public static function view_grade_report($courseid, $userid = 0) {
 286          global $CFG, $USER;
 287          require_once($CFG->dirroot . "/grade/lib.php");
 288          require_once($CFG->dirroot . "/grade/report/user/lib.php");
 289  
 290          $params = self::validate_parameters(self::view_grade_report_parameters(),
 291                                              array(
 292                                                  'courseid' => $courseid,
 293                                                  'userid' => $userid
 294                                              ));
 295  
 296          $warnings = array();
 297  
 298          $course = get_course($params['courseid']);
 299  
 300          $context = context_course::instance($course->id);
 301          self::validate_context($context);
 302  
 303          $userid = $params['userid'];
 304          if (empty($userid)) {
 305              $userid = $USER->id;
 306          } else {
 307              $user = core_user::get_user($userid, '*', MUST_EXIST);
 308              core_user::require_active_user($user);
 309          }
 310  
 311          $access = false;
 312  
 313          if (has_capability('moodle/grade:viewall', $context)) {
 314              // Can view all course grades (any user).
 315              $access = true;
 316          } else if ($userid == $USER->id and has_capability('moodle/grade:view', $context) and $course->showgrades) {
 317              // View own grades.
 318              $access = true;
 319          }
 320  
 321          if (!$access) {
 322              throw new moodle_exception('nopermissiontoviewgrades', 'error');
 323          }
 324  
 325          // Create a report instance. We don't need the gpr second parameter.
 326          $report = new grade_report_user($course->id, null, $context, $userid);
 327          $report->viewed();
 328  
 329          $result = array();
 330          $result['status'] = true;
 331          $result['warnings'] = $warnings;
 332          return $result;
 333      }
 334  
 335      /**
 336       * Returns description of method result value
 337       *
 338       * @return external_description
 339       * @since Moodle 2.9
 340       */
 341      public static function view_grade_report_returns() {
 342          return new external_single_structure(
 343              array(
 344                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 345                  'warnings' => new external_warnings()
 346              )
 347          );
 348      }
 349  }