grade/report/user/externallib.php

   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 class gradereport_user_external extends external_api {
  30
  31     /**
  32      * Describes the parameters for get_grades_table.
  33      *
  34      * @return external_external_function_parameters
  35      * @since Moodle 2.9
  36      */
  37     public static function get_grades_table_parameters() {
  38         return new external_function_parameters (
  39             array(
  40                 'courseid' => new external_value(PARAM_INT, 'Course Id', VALUE_REQUIRED),
  41                 'userid'   => new external_value(PARAM_INT, 'Return grades only for this user (optional)', VALUE_DEFAULT, 0)
  42             )
  43         );
  44     }
  45
  46     /**
  47      * Returns a list of grades tables for users in a course.
  48      *
  49      * @param int $courseid Course Id
  50      * @param int $userid   Only this user (optional)
  51      *
  52      * @return array the grades tables
  53      * @since Moodle 2.9
  54      */
  55     public static function get_grades_table($courseid, $userid = 0) {
  56         global $CFG, $USER;
  57
  58         $warnings = array();
  59
  60         // Validate the parameter.
  61         $params = self::validate_parameters(self::get_grades_table_parameters(),
  62             array(
  63                 'courseid' => $courseid,
  64                 'userid' => $userid)
  65             );
  66
  67         // Compact/extract functions are not recommended.
  68         $courseid = $params['courseid'];
  69         $userid   = $params['userid'];
  70
  71         // Function get_course internally throws an exception if the course doesn't exist.
  72         $course = get_course($courseid);
  73
  74         $context = context_course::instance($courseid);
  75         self::validate_context($context);
  76
  77         // Specific capabilities.
  78         require_capability('gradereport/user:view', $context);
  79
  80         $user = null;
  81
  82         if (empty($userid)) {
  83             require_capability('moodle/grade:viewall', $context);
  84         } else {
  85             $user = core_user::get_user($userid, '*', MUST_EXIST);
  86         }
  87
  88         $access = false;
  89
  90         if (has_capability('moodle/grade:viewall', $context)) {
  91             // Can view all course grades.
  92             $access = true;
  93         } else if ($userid == $USER->id and has_capability('moodle/grade:view', $context) and $course->showgrades) {
  94             // View own grades.
  95             $access = true;
  96         }
  97
  98         if (!$access) {
  99             throw new moodle_exception('nopermissiontoviewgrades', 'error');
 100         }
 101
 102         // Require files here to save some memory in case validation fails.
 103         require_once($CFG->dirroot . '/group/lib.php');
 104         require_once($CFG->libdir  . '/gradelib.php');
 105         require_once($CFG->dirroot . '/grade/lib.php');
 106         require_once($CFG->dirroot . '/grade/report/user/lib.php');
 107
 108         $gpr = new grade_plugin_return(
 109             array(
 110                 'type' => 'report',
 111                 'plugin' => 'user',
 112                 'courseid' => $courseid,
 113                 'userid' => $userid)
 114             );
 115
 116         $tables = array();
 117
 118         // Just one user.
 119         if ($user) {
 120             $report = new grade_report_user($courseid, $gpr, $context, $userid);
 121             $report->fill_table();
 122
 123             $tables[] = array(
 124                 'courseid'      => $courseid,
 125                 'userid'        => $user->id,
 126                 'userfullname'  => fullname($user),
 127                 'maxdepth'      => $report->maxdepth,
 128                 'tabledata'     => $report->tabledata
 129             );
 130
 131         } else {
 132             $defaultgradeshowactiveenrol = !empty($CFG->grade_report_showonlyactiveenrol);
 133             $showonlyactiveenrol = get_user_preferences('grade_report_showonlyactiveenrol', $defaultgradeshowactiveenrol);
 134             $showonlyactiveenrol = $showonlyactiveenrol || !has_capability('moodle/course:viewsuspendedusers', $context);
 135
 136             $gui = new graded_users_iterator($course);
 137             $gui->require_active_enrolment($showonlyactiveenrol);
 138             $gui->init();
 139
 140             while ($userdata = $gui->next_user()) {
 141                 $currentuser = $userdata->user;
 142                 $report = new grade_report_user($courseid, $gpr, $context, $currentuser->id);
 143                 $report->fill_table();
 144
 145                 $tables[] = array(
 146                     'courseid'      => $courseid,
 147                     'userid'        => $currentuser->id,
 148                     'userfullname'  => fullname($currentuser),
 149                     'maxdepth'      => $report->maxdepth,
 150                     'tabledata'     => $report->tabledata
 151                 );
 152             }
 153             $gui->close();
 154         }
 155
 156         $result = array();
 157         $result['tables'] = $tables;
 158         $result['warnings'] = $warnings;
 159         return $result;
 160     }
 161
 162     /**
 163      * Creates a table column structure
 164      *
 165      * @return array
 166      * @since  Moodle 2.9
 167      */
 168     private static function grades_table_column() {
 169         return array (
 170             'class'   => new external_value(PARAM_RAW, 'class'),
 171             'content' => new external_value(PARAM_RAW, 'cell content'),
 172             'headers' => new external_value(PARAM_RAW, 'headers')
 173         );
 174     }
 175
 176     /**
 177      * Describes tget_grades_table return value.
 178      *
 179      * @return external_single_structure
 180      * @since Moodle 2.9
 181      */
 182     public static function get_grades_table_returns() {
 183         return new external_single_structure(
 184             array(
 185                 'tables' => new external_multiple_structure(
 186                     new external_single_structure(
 187                         array(
 188                             'courseid' => new external_value(PARAM_INT, 'course id'),
 189                             'userid'   => new external_value(PARAM_INT, 'user id'),
 190                             'userfullname' => new external_value(PARAM_TEXT, 'user fullname'),
 191                             'maxdepth'   => new external_value(PARAM_INT, 'table max depth (needed for printing it)'),
 192                             'tabledata' => new external_multiple_structure(
 193                                 new external_single_structure(
 194                                     array(
 195                                         'itemname' => new external_single_structure(
 196                                             array (
 197                                                 'class' => new external_value(PARAM_RAW, 'class'),
 198                                                 'colspan' => new external_value(PARAM_INT, 'col span'),
 199                                                 'content'  => new external_value(PARAM_RAW, 'cell content'),
 200                                                 'celltype'  => new external_value(PARAM_RAW, 'cell type'),
 201                                                 'id'  => new external_value(PARAM_ALPHANUMEXT, 'id')
 202                                             ), 'The item returned data', VALUE_OPTIONAL
 203                                         ),
 204                                         'leader' => new external_single_structure(
 205                                             array (
 206                                                 'class' => new external_value(PARAM_RAW, 'class'),
 207                                                 'rowspan' => new external_value(PARAM_INT, 'row span')
 208                                             ), 'The item returned data', VALUE_OPTIONAL
 209                                         ),
 210                                         'weight' => new external_single_structure(
 211                                             self::grades_table_column(), 'weight column', VALUE_OPTIONAL
 212                                         ),
 213                                         'grade' => new external_single_structure(
 214                                             self::grades_table_column(), 'grade column', VALUE_OPTIONAL
 215                                         ),
 216                                         'range' => new external_single_structure(
 217                                             self::grades_table_column(), 'range column', VALUE_OPTIONAL
 218                                         ),
 219                                         'percentage' => new external_single_structure(
 220                                             self::grades_table_column(), 'percentage column', VALUE_OPTIONAL
 221                                         ),
 222                                         'lettergrade' => new external_single_structure(
 223                                             self::grades_table_column(), 'lettergrade column', VALUE_OPTIONAL
 224                                         ),
 225                                         'rank' => new external_single_structure(
 226                                             self::grades_table_column(), 'rank column', VALUE_OPTIONAL
 227                                         ),
 228                                         'average' => new external_single_structure(
 229                                             self::grades_table_column(), 'average column', VALUE_OPTIONAL
 230                                         ),
 231                                         'feedback' => new external_single_structure(
 232                                             self::grades_table_column(), 'feedback column', VALUE_OPTIONAL
 233                                         ),
 234                                         'contributiontocoursetotal' => new external_single_structure(
 235                                             self::grades_table_column(), 'contributiontocoursetotal column', VALUE_OPTIONAL
 236                                         ),
 237                                     ), 'table'
 238                                 )
 239                             )
 240                         )
 241                     )
 242                 ),
 243                 'warnings' => new external_warnings()
 244             )
 245         );
 246     }
 247 }