MDL-49036 webservices: New ws gradereport_user_get_grades_table
[moodle.git] / 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/>.
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  */
25 defined('MOODLE_INTERNAL') || die;
27 require_once("$CFG->libdir/externallib.php");
29 class gradereport_user_external extends external_api {
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     }
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;
58         $warnings = array();
60         // Validate the parameter.
61         $params = self::validate_parameters(self::get_grades_table_parameters(),
62             array(
63                 'courseid' => $courseid,
64                 'userid' => $userid)
65             );
67         // Compact/extract functions are not recommended.
68         $courseid = $params['courseid'];
69         $userid   = $params['userid'];
71         // Function get_course internally throws an exception if the course doesn't exist.
72         $course = get_course($courseid);
74         $context = context_course::instance($courseid);
75         self::validate_context($context);
77         // Specific capabilities.
78         require_capability('gradereport/user:view', $context);
80         $user = null;
82         if (empty($userid)) {
83             require_capability('moodle/grade:viewall', $context);
84         } else {
85             $user = core_user::get_user($userid, '*', MUST_EXIST);
86         }
88         $access = false;
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         }
98         if (!$access) {
99             throw new moodle_exception('nopermissiontoviewgrades', 'error');
100         }
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');
108         $gpr = new grade_plugin_return(
109             array(
110                 'type' => 'report',
111                 'plugin' => 'user',
112                 'courseid' => $courseid,
113                 'userid' => $userid)
114             );
116         $tables = array();
118         // Just one user.
119         if ($user) {
120             $report = new grade_report_user($courseid, $gpr, $context, $userid);
121             $report->fill_table();
123             $tables[] = array(
124                 'courseid'      => $courseid,
125                 'userid'        => $user->id,
126                 'userfullname'  => fullname($user),
127                 'maxdepth'      => $report->maxdepth,
128                 'tabledata'     => $report->tabledata
129             );
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);
136             $gui = new graded_users_iterator($course);
137             $gui->require_active_enrolment($showonlyactiveenrol);
138             $gui->init();
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();
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         }
156         $result = array();
157         $result['tables'] = $tables;
158         $result['warnings'] = $warnings;
159         return $result;
160     }
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     }
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     }