See Release Notes
Long Term Support Release
Differences Between: [Versions 39 and 401] [Versions 401 and 402] [Versions 401 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 * Web service functions relating to scale grades and grading. 19 * 20 * @package core_grades 21 * @copyright 2019 Andrew Nicols <andrew@nicols.co.uk> 22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 23 */ 24 25 declare(strict_types = 1); 26 27 namespace core_grades\grades\grader\gradingpanel\scale\external; 28 29 use coding_exception; 30 use context; 31 use core_grades\component_gradeitem as gradeitem; 32 use core_grades\component_gradeitems; 33 use core_user; 34 use external_api; 35 use external_function_parameters; 36 use external_multiple_structure; 37 use external_single_structure; 38 use external_value; 39 use external_warnings; 40 use moodle_exception; 41 use required_capability_exception; 42 use stdClass; 43 44 /** 45 * External grading panel scale API 46 * 47 * @package core_grades 48 * @copyright 2019 Andrew Nicols <andrew@nicols.co.uk> 49 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 50 */ 51 class fetch extends external_api { 52 53 /** 54 * Describes the parameters for fetching the grading panel for a simple grade. 55 * 56 * @return external_function_parameters 57 * @since Moodle 3.8 58 */ 59 public static function execute_parameters(): external_function_parameters { 60 return new external_function_parameters ([ 61 'component' => new external_value( 62 PARAM_ALPHANUMEXT, 63 'The name of the component', 64 VALUE_REQUIRED 65 ), 66 'contextid' => new external_value( 67 PARAM_INT, 68 'The ID of the context being graded', 69 VALUE_REQUIRED 70 ), 71 'itemname' => new external_value( 72 PARAM_ALPHANUM, 73 'The grade item itemname being graded', 74 VALUE_REQUIRED 75 ), 76 'gradeduserid' => new external_value( 77 PARAM_INT, 78 'The ID of the user show', 79 VALUE_REQUIRED 80 ), 81 ]); 82 } 83 84 /** 85 * Fetch the data required to build a grading panel for a simple grade. 86 * 87 * @param string $component 88 * @param int $contextid 89 * @param string $itemname 90 * @param int $gradeduserid 91 * @return array 92 * @throws \dml_exception 93 * @throws \invalid_parameter_exception 94 * @throws \restricted_context_exception 95 * @throws coding_exception 96 * @throws moodle_exception 97 * @since Moodle 3.8 98 */ 99 public static function execute(string $component, int $contextid, string $itemname, int $gradeduserid): array { 100 global $USER, $CFG; 101 require_once("{$CFG->libdir}/gradelib.php"); 102 [ 103 'component' => $component, 104 'contextid' => $contextid, 105 'itemname' => $itemname, 106 'gradeduserid' => $gradeduserid, 107 ] = self::validate_parameters(self::execute_parameters(), [ 108 'component' => $component, 109 'contextid' => $contextid, 110 'itemname' => $itemname, 111 'gradeduserid' => $gradeduserid, 112 ]); 113 114 // Validate the context. 115 $context = context::instance_by_id($contextid); 116 self::validate_context($context); 117 118 // Validate that the supplied itemname is a gradable item. 119 if (!component_gradeitems::is_valid_itemname($component, $itemname)) { 120 throw new coding_exception("The '{$itemname}' item is not valid for the '{$component}' component"); 121 } 122 123 // Fetch the gradeitem instance. 124 $gradeitem = gradeitem::instance($component, $context, $itemname); 125 126 if (!$gradeitem->is_using_scale()) { 127 throw new moodle_exception("The {$itemname} item in {$component}/{$contextid} is not configured for grading with scales"); 128 } 129 130 $gradeduser = \core_user::get_user($gradeduserid, '*', MUST_EXIST); 131 132 // One can access its own grades. Others just if they're graders. 133 if ($gradeduserid != $USER->id) { 134 $gradeitem->require_user_can_grade($gradeduser, $USER); 135 } 136 137 // Set up some items we need to return on other interfaces. 138 $gradegrade = \grade_grade::fetch(['itemid' => $gradeitem->get_grade_item()->id, 'userid' => $gradeduser->id]); 139 $gradername = $gradegrade ? fullname(\core_user::get_user($gradegrade->usermodified)) : null; 140 $maxgrade = (int) $gradeitem->get_grade_item()->grademax; 141 142 return self::get_fetch_data($gradeitem, $gradeduser, $maxgrade, $gradername); 143 } 144 145 /** 146 * Get the data to be fetched. 147 * 148 * @param gradeitem $gradeitem 149 * @param stdClass $gradeduser 150 * @param int $maxgrade 151 * @param string|null $gradername 152 * @return array 153 */ 154 public static function get_fetch_data(gradeitem $gradeitem, stdClass $gradeduser, int $maxgrade, ?string $gradername): array { 155 global $USER; 156 157 $hasgrade = $gradeitem->user_has_grade($gradeduser); 158 $grade = $gradeitem->get_formatted_grade_for_user($gradeduser, $USER); 159 $currentgrade = (int) unformat_float($grade->grade); 160 161 $menu = $gradeitem->get_grade_menu(); 162 $values = array_map(function($description, $value) use ($currentgrade) { 163 return [ 164 'value' => $value, 165 'title' => $description, 166 'selected' => ($value == $currentgrade), 167 ]; 168 }, $menu, array_keys($menu)); 169 170 return [ 171 'templatename' => 'core_grades/grades/grader/gradingpanel/scale', 172 'hasgrade' => $hasgrade, 173 'grade' => [ 174 'options' => $values, 175 'usergrade' => $grade->usergrade, 176 'maxgrade' => $maxgrade, 177 'gradedby' => $gradername, 178 'timecreated' => $grade->timecreated, 179 'timemodified' => $grade->timemodified, 180 ], 181 'warnings' => [], 182 ]; 183 } 184 185 /** 186 * Describes the data returned from the external function. 187 * 188 * @return external_single_structure 189 * @since Moodle 3.8 190 */ 191 public static function execute_returns(): external_single_structure { 192 return new external_single_structure([ 193 'templatename' => new external_value(PARAM_SAFEPATH, 'The template to use when rendering this data'), 194 'hasgrade' => new external_value(PARAM_BOOL, 'Does the user have a grade?'), 195 'grade' => new external_single_structure([ 196 'options' => new external_multiple_structure( 197 new external_single_structure([ 198 'value' => new external_value(PARAM_FLOAT, 'The grade value'), 199 'title' => new external_value(PARAM_RAW, 'The description fo the option'), 200 'selected' => new external_value(PARAM_BOOL, 'Whether this item is currently selected'), 201 ]), 202 'The description of the grade option' 203 ), 204 'usergrade' => new external_value(PARAM_RAW, 'Current user grade'), 205 'maxgrade' => new external_value(PARAM_RAW, 'Max possible grade'), 206 'gradedby' => new external_value(PARAM_RAW, 'The assumed grader of this grading instance'), 207 'timecreated' => new external_value(PARAM_INT, 'The time that the grade was created'), 208 'timemodified' => new external_value(PARAM_INT, 'The time that the grade was last updated'), 209 ]), 210 'warnings' => new external_warnings(), 211 ]); 212 } 213 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body