MDL-66809 core_grades: Implement scale-based marking
[moodle.git] / grade / classes / component_gradeitem.php
CommitLineData
f8da1b93
AN
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 * Compontent definition of a gradeitem.
19 *
20 * @package core_grades
21 * @copyright Andrew Nicols <andrew@nicols.co.uk>
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
25declare(strict_types = 1);
26
27namespace core_grades;
28
29use context;
30use gradingform_controller;
31use gradingform_instance;
32use moodle_exception;
33use stdClass;
34use grade_item as core_gradeitem;
35use grading_manager;
36
37/**
38 * Compontent definition of a gradeitem.
39 *
40 * @package core_grades
41 * @copyright Andrew Nicols <andrew@nicols.co.uk>
42 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
43 */
44abstract class component_gradeitem {
45
46 /** @var array The scale data for the current grade item */
47 protected $scale;
48
49 /** @var string The component */
50 protected $component;
51
52 /** @var context The context for this activity */
53 protected $context;
54
55 /** @var string The item name */
56 protected $itemname;
57
58 /** @var int The grade itemnumber */
59 protected $itemnumber;
60
61 final protected function __construct(string $component, context $context, string $itemname) {
62 $this->component = $component;
63 $this->context = $context;
64 $this->itemname = $itemname;
65 $this->itemnumber = component_gradeitems::get_itemnumber_from_itemname($component, $itemname);
66 }
67
68 /**
69 * Fetch an instance of a specific component_gradeitem.
70 *
71 * @param string $component
72 * @param context $context
73 * @param string $itemname
74 * @return self
75 */
76 public static function instance(string $component, context $context, string $itemname): self {
77 $itemnumber = component_gradeitems::get_itemnumber_from_itemname($component, $itemname);
78
79 $classname = "{$component}\\grades\\{$itemname}_gradeitem";
80 if (!class_exists($classname)) {
81 throw new coding_exception("Unknown gradeitem {$itemname} for component {$classname}");
82 }
83
84 return $classname::load_from_context($context);
85 }
86
87 /**
88 * Load an instance of the current component_gradeitem based on context.
89 *
90 * @param context $context
91 * @return self
92 */
93 abstract public static function load_from_context(context $context): self;
94
95 /**
96 * The table name used for grading.
97 *
98 * @return string
99 */
100 abstract protected function get_table_name(): string;
101
b253a4f2
AN
102 /**
103 * Get the itemid for the current gradeitem.
104 *
105 * @return int
106 */
107 public function get_grade_itemid(): int {
108 return component_gradeitems::get_itemnumber_from_itemname($this->component, $this->itemname);
109 }
110
f8da1b93
AN
111 /**
112 * Whether grading is enabled for this item.
113 *
114 * @return bool
115 */
116 abstract public function is_grading_enabled(): bool;
117
118 /**
119 * Get the grade value for this instance.
120 * The itemname is translated to the relevant grade field for the activity.
121 *
122 * @return int
123 */
124 abstract protected function get_gradeitem_value(): ?int;
125
126 /**
127 * Whether the grader can grade the gradee.
128 *
129 * @param stdClass $gradeduser The user being graded
130 * @param stdClass $grader The user who is grading
131 * @return bool
132 */
133 abstract public function user_can_grade(stdClass $gradeduser, stdClass $grader): bool;
134
135 /**
136 * Require that the user can grade, throwing an exception if not.
137 *
138 * @param stdClass $gradeduser The user being graded
139 * @param stdClass $grader The user who is grading
140 * @throws required_capability_exception
141 */
142 abstract public function require_user_can_grade(stdClass $gradeduser, stdClass $grader): void;
143
144 /**
145 * Get the scale if a scale is being used.
146 *
147 * @return stdClass
148 */
149 protected function get_scale(): ?stdClass {
b253a4f2
AN
150 global $DB;
151
f8da1b93
AN
152 $gradetype = $this->get_gradeitem_value();
153 if ($gradetype > 0) {
154 return null;
155 }
156
157 // This is a scale.
158 if (null === $this->scale) {
159 $this->scale = $DB->get_record('scale', ['id' => -1 * $gradetype]);
160 }
161
162 return $this->scale;
163 }
164
165 /**
166 * Check whether a scale is being used for this grade item.
167 *
168 * @return bool
169 */
b253a4f2 170 public function is_using_scale(): bool {
f8da1b93
AN
171 $gradetype = $this->get_gradeitem_value();
172
173 return $gradetype < 0;
174 }
175
176 /**
177 * Whether this grade item is configured to use direct grading.
178 *
179 * @return bool
180 */
181 public function is_using_direct_grading(): bool {
182 if ($this->is_using_scale()) {
183 return false;
184 }
185
186 if ($this->get_advanced_grading_controller()) {
187 return false;
188 }
189
190 return true;
191 }
192
193 /**
194 * Whether this grade item is configured to use advanced grading.
195 *
196 * @return bool
197 */
198 public function is_using_advanced_grading(): bool {
199 if ($this->is_using_scale()) {
200 return false;
201 }
202
203 if ($this->get_advanced_grading_controller()) {
204 return true;
205 }
206
207 return false;
208 }
209
210 /**
211 * Get the name of the advanced grading method.
212 *
213 * @return string
214 */
215 public function get_advanced_grading_method(): ?string {
216 $gradingmanager = $this->get_grading_manager();
217
218 if (empty($gradingmanager)) {
219 return null;
220 }
221
222 return $gradingmanager->get_active_method();
223 }
224
225 /**
226 * Get the name of the component responsible for grading this gradeitem.
227 *
228 * @return string
229 */
230 public function get_grading_component_name(): ?string {
231 if (!$this->is_grading_enabled()) {
232 return null;
233 }
234
235 if ($method = $this->get_advanced_grading_method()) {
236 return "gradingform_{$method}";
237 }
238
239 return 'core_grades';
240 }
241
242 /**
243 * Get the name of the component subtype responsible for grading this gradeitem.
244 *
245 * @return string
246 */
247 public function get_grading_component_subtype(): ?string {
248 if (!$this->is_grading_enabled()) {
249 return null;
250 }
251
252 if ($method = $this->get_advanced_grading_method()) {
253 return null;
254 }
255
256 if ($this->is_using_scale()) {
257 return 'scale';
258 }
259
260 return 'point';
261 }
262
263 /**
264 * Whether decimals are allowed.
265 *
266 * @return bool
267 */
268 protected function allow_decimals(): bool {
269 return $this->get_gradeitem_value() > 0;
270 }
271
272 /**
273 * Get the grading manager for this advanced grading definition.
274 *
275 * @return grading_manager
276 */
277 protected function get_grading_manager(): ?grading_manager {
278 require_once(__DIR__ . '/../grading/lib.php');
279 return get_grading_manager($this->context, $this->component, $this->itemname);
280
281 }
282
283 /**
284 * Get the advanced grading controller if advanced grading is enabled.
285 *
286 * @return gradingform_controller
287 */
288 protected function get_advanced_grading_controller(): ?gradingform_controller {
289 $gradingmanager = $this->get_grading_manager();
290
291 if (empty($gradingmanager)) {
292 return null;
293 }
294
295 if ($gradingmethod = $gradingmanager->get_active_method()) {
296 return $gradingmanager->get_controller($gradingmethod);
297 }
298
299 return null;
300 }
301
302 /**
b253a4f2 303 * Get the list of available grade items.
f8da1b93
AN
304 *
305 * @return array
306 */
b253a4f2 307 public function get_grade_menu(): array {
f8da1b93
AN
308 return make_grades_menu($this->get_gradeitem_value());
309 }
310
311 /**
312 * Check whether the supplied grade is valid and throw an exception if not.
313 *
314 * @param float $grade The value being checked
315 * @throws moodle_exception
f8da1b93
AN
316 * @return bool
317 */
318 public function check_grade_validity(?float $grade): bool {
b253a4f2
AN
319 $grade = grade_floatval(unformat_float($grade));
320 if ($grade) {
321 if ($this->is_using_scale()) {
322 // Fetch all options for this scale.
323 $scaleoptions = make_menu_from_list($this->get_scale()->scale);
324
325 if ($grade != -1 && !array_key_exists((int) $grade, $scaleoptions)) {
326 // The selected option did not exist.
327 throw new moodle_exception('error:notinrange', 'core_grading', '', (object) [
328 'maxgrade' => count($scaleoptions),
329 'grade' => $grade,
330 ]);
331 }
332 } else if ($grade) {
333 $maxgrade = $this->get_gradeitem_value();
334 if ($grade > $maxgrade) {
335 // The grade is greater than the maximum possible value.
336 throw new moodle_exception('error:notinrange', 'core_grading', '', (object) [
337 'maxgrade' => $maxgrade,
338 'grade' => $grade,
339 ]);
340 } else if ($grade < 0) {
341 // Negative grades are not supported.
342 throw new moodle_exception('error:notinrange', 'core_grading', '', (object) [
343 'maxgrade' => $maxgrade,
344 'grade' => $grade,
345 ]);
346 }
f8da1b93
AN
347 }
348 }
349
350 return true;
351 }
352
353 /**
354 * Create an empty row in the grade for the specified user and grader.
355 *
356 * @param stdClass $gradeduser The user being graded
357 * @param stdClass $grader The user who is grading
358 * @return stdClass The newly created grade record
359 */
360 abstract public function create_empty_grade(stdClass $gradeduser, stdClass $grader): stdClass;
361
362 /**
363 * Get the grade record for the specified grade id.
364 *
365 * @param int $gradeid
366 * @return stdClass
367 */
368 public function get_grade(int $gradeid): stdClass {
369 global $DB;
370
371 $grade = $DB->get_record($this->get_table_name(), ['id' => $gradeid]);
372
373 return $grade ?: null;
374 }
375
376 /**
377 * Get the grade for the specified user.
378 *
379 * @param stdClass $gradeduser The user being graded
380 * @param stdClass $grader The user who is grading
381 * @return stdClass The grade value
382 */
383 abstract public function get_grade_for_user(stdClass $gradeduser, stdClass $grader): ?stdClass;
384
385 /**
386 * Get grades for all users for the specified gradeitem.
387 *
388 * @param int $itemnumber The specific grade item to fetch for the user
389 * @return stdClass[] The grades
390 */
391 abstract public function get_all_grades(): array;
392
393 /**
394 * Create or update the grade.
395 *
396 * @param stdClass $grade
397 * @return bool Success
398 */
399 abstract protected function store_grade(stdClass $grade): bool;
400
401 /**
402 * Create or update the grade.
403 *
404 * @param stdClass $gradeduser The user being graded
405 * @param stdClass $grader The user who is grading
406 * @param stdClass $formdata The data submitted
407 * @return bool Success
408 */
409 public function store_grade_from_formdata(stdClass $gradeduser, stdClass $grader, stdClass $formdata): bool {
410 // Require gradelib for grade_floatval.
411 require_once(__DIR__ . '/../../lib/gradelib.php');
412 $grade = $this->get_grade_for_user($gradeduser, $grader);
413
414 if ($this->is_using_advanced_grading()) {
415 $instanceid = $formdata->instanceid;
416 $gradinginstance = $this->get_advanced_grading_instance($grader, $grade, (int) $instanceid);
417 $grade->grade = $gradinginstance->submit_and_get_grade($formdata->advancedgrading, $grade->id);
418 } else {
419 // Handle the case when grade is set to No Grade.
420 if (isset($formdata->grade)) {
421 $grade->grade = grade_floatval(unformat_float($formdata->grade));
422 }
423 }
424
425 return $this->store_grade($grade);
426 }
427
428 /**
429 * Get the advanced grading instance for the specified grade entry.
430 *
431 * @param stdClass $grader The user who is grading
432 * @param stdClass $grade The row from the grade table.
433 * @param int $instanceid The instanceid of the advanced grading form
434 * @return gradingform_instance
435 */
436 public function get_advanced_grading_instance(stdClass $grader, stdClass $grade, int $instanceid = null): ?gradingform_instance {
437 $controller = $this->get_advanced_grading_controller($this->itemname);
438
439 if (empty($controller)) {
440 // Advanced grading not enabeld for this item.
441 return null;
442 }
443
444 if (!$controller->is_form_available()) {
445 // The form is not available for this item.
446 return null;
447 }
448
449 // Fetch the instance for the specified graderid/itemid.
450 $gradinginstance = $controller->fetch_instance(
451 (int) $grader->id,
452 (int) $grade->id,
453 $instanceid
454 );
455
456 // Set the allowed grade range.
457 $gradinginstance->get_controller()->set_grade_range(
b253a4f2 458 $this->get_grade_menu(),
f8da1b93
AN
459 $this->allow_decimals()
460 );
461
462 return $gradinginstance;
463 }
464}