Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
- Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
- PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
/mod/workshop/classes/ -> external.php (source)
Differences Between: [Versions 311 and 402] [Versions 311 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 * Workshop external API 19 * 20 * @package mod_workshop 21 * @category external 22 * @copyright 2017 Juan Leyva <juan@moodle.com> 23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 24 * @since Moodle 3.4 25 */ 26 27 defined('MOODLE_INTERNAL') || die; 28 29 require_once("$CFG->libdir/externallib.php"); 30 require_once($CFG->dirroot . '/mod/workshop/locallib.php'); 31 32 use mod_workshop\external\workshop_summary_exporter; 33 use mod_workshop\external\submission_exporter; 34 use mod_workshop\external\assessment_exporter; 35 36 /** 37 * Workshop external functions 38 * 39 * @package mod_workshop 40 * @category external 41 * @copyright 2017 Juan Leyva <juan@moodle.com> 42 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 43 * @since Moodle 3.4 44 */ 45 class mod_workshop_external extends external_api { 46 47 /** 48 * Describes the parameters for get_workshops_by_courses. 49 * 50 * @return external_function_parameters 51 * @since Moodle 3.4 52 */ 53 public static function get_workshops_by_courses_parameters() { 54 return new external_function_parameters ( 55 array( 56 'courseids' => new external_multiple_structure( 57 new external_value(PARAM_INT, 'Course id'), 'Array of course ids', VALUE_DEFAULT, array() 58 ), 59 ) 60 ); 61 } 62 63 /** 64 * Returns a list of workshops in a provided list of courses. 65 * If no list is provided all workshops that the user can view will be returned. 66 * 67 * @param array $courseids course ids 68 * @return array of warnings and workshops 69 * @since Moodle 3.4 70 */ 71 public static function get_workshops_by_courses($courseids = array()) { 72 global $PAGE; 73 74 $warnings = array(); 75 $returnedworkshops = array(); 76 77 $params = array( 78 'courseids' => $courseids, 79 ); 80 $params = self::validate_parameters(self::get_workshops_by_courses_parameters(), $params); 81 82 $mycourses = array(); 83 if (empty($params['courseids'])) { 84 $mycourses = enrol_get_my_courses(); 85 $params['courseids'] = array_keys($mycourses); 86 } 87 88 // Ensure there are courseids to loop through. 89 if (!empty($params['courseids'])) { 90 91 list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses); 92 $output = $PAGE->get_renderer('core'); 93 94 // Get the workshops in this course, this function checks users visibility permissions. 95 // We can avoid then additional validate_context calls. 96 $workshops = get_all_instances_in_courses("workshop", $courses); 97 foreach ($workshops as $workshop) { 98 99 $context = context_module::instance($workshop->coursemodule); 100 // Remove fields that are not from the workshop (added by get_all_instances_in_courses). 101 unset($workshop->coursemodule, $workshop->context, $workshop->visible, $workshop->section, $workshop->groupmode, 102 $workshop->groupingid); 103 104 $exporter = new workshop_summary_exporter($workshop, array('context' => $context)); 105 $returnedworkshops[] = $exporter->export($output); 106 } 107 } 108 109 $result = array( 110 'workshops' => $returnedworkshops, 111 'warnings' => $warnings 112 ); 113 return $result; 114 } 115 116 /** 117 * Describes the get_workshops_by_courses return value. 118 * 119 * @return external_single_structure 120 * @since Moodle 3.4 121 */ 122 public static function get_workshops_by_courses_returns() { 123 return new external_single_structure( 124 array( 125 'workshops' => new external_multiple_structure( 126 workshop_summary_exporter::get_read_structure() 127 ), 128 'warnings' => new external_warnings(), 129 ) 130 ); 131 } 132 133 /** 134 * Utility function for validating a workshop. 135 * 136 * @param int $workshopid workshop instance id 137 * @return array array containing the workshop object, course, context and course module objects 138 * @since Moodle 3.4 139 */ 140 protected static function validate_workshop($workshopid) { 141 global $DB, $USER; 142 143 // Request and permission validation. 144 $workshop = $DB->get_record('workshop', array('id' => $workshopid), '*', MUST_EXIST); 145 list($course, $cm) = get_course_and_cm_from_instance($workshop, 'workshop'); 146 147 $context = context_module::instance($cm->id); 148 self::validate_context($context); 149 150 $workshop = new workshop($workshop, $cm, $course); 151 152 return array($workshop, $course, $cm, $context); 153 } 154 155 156 /** 157 * Describes the parameters for get_workshop_access_information. 158 * 159 * @return external_external_function_parameters 160 * @since Moodle 3.4 161 */ 162 public static function get_workshop_access_information_parameters() { 163 return new external_function_parameters ( 164 array( 165 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id.') 166 ) 167 ); 168 } 169 170 /** 171 * Return access information for a given workshop. 172 * 173 * @param int $workshopid workshop instance id 174 * @return array of warnings and the access information 175 * @since Moodle 3.4 176 * @throws moodle_exception 177 */ 178 public static function get_workshop_access_information($workshopid) { 179 global $USER; 180 181 $params = self::validate_parameters(self::get_workshop_access_information_parameters(), array('workshopid' => $workshopid)); 182 183 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']); 184 185 $result = array(); 186 // Return all the available capabilities. 187 $capabilities = load_capability_def('mod_workshop'); 188 foreach ($capabilities as $capname => $capdata) { 189 // Get fields like cansubmit so it is consistent with the access_information function implemented in other modules. 190 $field = 'can' . str_replace('mod/workshop:', '', $capname); 191 $result[$field] = has_capability($capname, $context); 192 } 193 194 // Now, specific features access information. 195 $result['creatingsubmissionallowed'] = $workshop->creating_submission_allowed($USER->id); 196 $result['modifyingsubmissionallowed'] = $workshop->modifying_submission_allowed($USER->id); 197 $result['assessingallowed'] = $workshop->assessing_allowed($USER->id); 198 $result['assessingexamplesallowed'] = $workshop->assessing_examples_allowed(); 199 if (is_null($result['assessingexamplesallowed'])) { 200 $result['assessingexamplesallowed'] = false; 201 } 202 $result['examplesassessedbeforesubmission'] = $workshop->check_examples_assessed_before_submission($USER->id); 203 list($result['examplesassessedbeforeassessment'], $code) = $workshop->check_examples_assessed_before_assessment($USER->id); 204 205 $result['warnings'] = array(); 206 return $result; 207 } 208 209 /** 210 * Describes the get_workshop_access_information return value. 211 * 212 * @return external_single_structure 213 * @since Moodle 3.4 214 */ 215 public static function get_workshop_access_information_returns() { 216 217 $structure = array( 218 'creatingsubmissionallowed' => new external_value(PARAM_BOOL, 219 'Is the given user allowed to create their submission?'), 220 'modifyingsubmissionallowed' => new external_value(PARAM_BOOL, 221 'Is the user allowed to modify his existing submission?'), 222 'assessingallowed' => new external_value(PARAM_BOOL, 223 'Is the user allowed to create/edit his assessments?'), 224 'assessingexamplesallowed' => new external_value(PARAM_BOOL, 225 'Are reviewers allowed to create/edit their assessments of the example submissions?.'), 226 'examplesassessedbeforesubmission' => new external_value(PARAM_BOOL, 227 'Whether the given user has assessed all his required examples before submission 228 (always true if there are not examples to assess or not configured to check before submission).'), 229 'examplesassessedbeforeassessment' => new external_value(PARAM_BOOL, 230 'Whether the given user has assessed all his required examples before assessment 231 (always true if there are not examples to assessor not configured to check before assessment).'), 232 'warnings' => new external_warnings() 233 ); 234 235 $capabilities = load_capability_def('mod_workshop'); 236 foreach ($capabilities as $capname => $capdata) { 237 // Get fields like cansubmit so it is consistent with the access_information function implemented in other modules. 238 $field = 'can' . str_replace('mod/workshop:', '', $capname); 239 $structure[$field] = new external_value(PARAM_BOOL, 'Whether the user has the capability ' . $capname . ' allowed.'); 240 } 241 242 return new external_single_structure($structure); 243 } 244 245 /** 246 * Describes the parameters for get_user_plan. 247 * 248 * @return external_external_function_parameters 249 * @since Moodle 3.4 250 */ 251 public static function get_user_plan_parameters() { 252 return new external_function_parameters ( 253 array( 254 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id.'), 255 'userid' => new external_value(PARAM_INT, 'User id (empty or 0 for current user).', VALUE_DEFAULT, 0), 256 ) 257 ); 258 } 259 260 /** 261 * Return the planner information for the given user. 262 * 263 * @param int $workshopid workshop instance id 264 * @param int $userid user id 265 * @return array of warnings and the user plan 266 * @since Moodle 3.4 267 * @throws moodle_exception 268 */ 269 public static function get_user_plan($workshopid, $userid = 0) { 270 global $USER; 271 272 $params = array( 273 'workshopid' => $workshopid, 274 'userid' => $userid, 275 ); 276 $params = self::validate_parameters(self::get_user_plan_parameters(), $params); 277 278 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']); 279 280 // Extra checks so only users with permissions can view other users plans. 281 if (empty($params['userid']) || $params['userid'] == $USER->id) { 282 $userid = $USER->id; 283 } else { 284 require_capability('moodle/course:manageactivities', $context); 285 $user = core_user::get_user($params['userid'], '*', MUST_EXIST); 286 core_user::require_active_user($user); 287 if (!$workshop->check_group_membership($user->id)) { 288 throw new moodle_exception('notingroup'); 289 } 290 $userid = $user->id; 291 } 292 293 // Get the user plan information ready for external functions. 294 $userplan = new workshop_user_plan($workshop, $userid); 295 $userplan = array('phases' => $userplan->phases, 'examples' => $userplan->get_examples()); 296 foreach ($userplan['phases'] as $phasecode => $phase) { 297 $phase->code = $phasecode; 298 $userplan['phases'][$phasecode] = (array) $phase; 299 foreach ($userplan['phases'][$phasecode]['tasks'] as $taskcode => $task) { 300 $task->code = $taskcode; 301 if ($task->link instanceof moodle_url) { 302 $task->link = $task->link->out(false); 303 } 304 $userplan['phases'][$phasecode]['tasks'][$taskcode] = (array) $task; 305 } 306 foreach ($userplan['phases'][$phasecode]['actions'] as $actioncode => $action) { 307 if ($action->url instanceof moodle_url) { 308 $action->url = $action->url->out(false); 309 } 310 $userplan['phases'][$phasecode]['actions'][$actioncode] = (array) $action; 311 } 312 } 313 314 $result['userplan'] = $userplan; 315 $result['warnings'] = array(); 316 return $result; 317 } 318 319 /** 320 * Describes the get_user_plan return value. 321 * 322 * @return external_single_structure 323 * @since Moodle 3.4 324 */ 325 public static function get_user_plan_returns() { 326 return new external_single_structure( 327 array( 328 'userplan' => new external_single_structure( 329 array( 330 'phases' => new external_multiple_structure( 331 new external_single_structure( 332 array( 333 'code' => new external_value(PARAM_INT, 'Phase code.'), 334 'title' => new external_value(PARAM_NOTAGS, 'Phase title.'), 335 'active' => new external_value(PARAM_BOOL, 'Whether is the active task.'), 336 'tasks' => new external_multiple_structure( 337 new external_single_structure( 338 array( 339 'code' => new external_value(PARAM_ALPHA, 'Task code.'), 340 'title' => new external_value(PARAM_RAW, 'Task title.'), 341 'link' => new external_value(PARAM_URL, 'Link to task.'), 342 'details' => new external_value(PARAM_RAW, 'Task details.', VALUE_OPTIONAL), 343 'completed' => new external_value(PARAM_NOTAGS, 344 'Completion information (maybe empty, maybe a boolean or generic info.'), 345 ) 346 ) 347 ), 348 'actions' => new external_multiple_structure( 349 new external_single_structure( 350 array( 351 'type' => new external_value(PARAM_ALPHA, 'Action type.', VALUE_OPTIONAL), 352 'label' => new external_value(PARAM_RAW, 'Action label.', VALUE_OPTIONAL), 353 'url' => new external_value(PARAM_URL, 'Link to action.'), 354 'method' => new external_value(PARAM_ALPHA, 'Get or post.', VALUE_OPTIONAL), 355 ) 356 ) 357 ), 358 ) 359 ) 360 ), 361 'examples' => new external_multiple_structure( 362 new external_single_structure( 363 array( 364 'id' => new external_value(PARAM_INT, 'Example submission id.'), 365 'title' => new external_value(PARAM_RAW, 'Example submission title.'), 366 'assessmentid' => new external_value(PARAM_INT, 'Example submission assessment id.'), 367 'grade' => new external_value(PARAM_FLOAT, 'The submission grade.'), 368 'gradinggrade' => new external_value(PARAM_FLOAT, 'The assessment grade.'), 369 ) 370 ) 371 ), 372 ) 373 ), 374 'warnings' => new external_warnings(), 375 ) 376 ); 377 } 378 379 /** 380 * Describes the parameters for view_workshop. 381 * 382 * @return external_function_parameters 383 * @since Moodle 3.4 384 */ 385 public static function view_workshop_parameters() { 386 return new external_function_parameters ( 387 array( 388 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id'), 389 ) 390 ); 391 } 392 393 /** 394 * Trigger the course module viewed event and update the module completion status. 395 * 396 * @param int $workshopid workshop instance id 397 * @return array of warnings and status result 398 * @since Moodle 3.4 399 * @throws moodle_exception 400 */ 401 public static function view_workshop($workshopid) { 402 403 $params = array('workshopid' => $workshopid); 404 $params = self::validate_parameters(self::view_workshop_parameters(), $params); 405 $warnings = array(); 406 407 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']); 408 409 $workshop->set_module_viewed(); 410 411 $result = array( 412 'status' => true, 413 'warnings' => $warnings, 414 ); 415 return $result; 416 } 417 418 /** 419 * Describes the view_workshop return value. 420 * 421 * @return external_single_structure 422 * @since Moodle 3.4 423 */ 424 public static function view_workshop_returns() { 425 return new external_single_structure( 426 array( 427 'status' => new external_value(PARAM_BOOL, 'status: true if success'), 428 'warnings' => new external_warnings(), 429 ) 430 ); 431 } 432 433 /** 434 * Returns the description of the external function parameters. 435 * 436 * @return external_function_parameters 437 * @since Moodle 3.4 438 */ 439 public static function add_submission_parameters() { 440 return new external_function_parameters(array( 441 'workshopid' => new external_value(PARAM_INT, 'Workshop id'), 442 'title' => new external_value(PARAM_TEXT, 'Submission title'), 443 'content' => new external_value(PARAM_RAW, 'Submission text content', VALUE_DEFAULT, ''), 444 'contentformat' => new external_value(PARAM_INT, 'The format used for the content', VALUE_DEFAULT, FORMAT_MOODLE), 445 'inlineattachmentsid' => new external_value(PARAM_INT, 'The draft file area id for inline attachments in the content', 446 VALUE_DEFAULT, 0), 447 'attachmentsid' => new external_value(PARAM_INT, 'The draft file area id for attachments', VALUE_DEFAULT, 0), 448 )); 449 } 450 451 /** 452 * Add a new submission to a given workshop. 453 * 454 * @param int $workshopid the workshop id 455 * @param string $title the submission title 456 * @param string $content the submission text content 457 * @param int $contentformat the format used for the content 458 * @param int $inlineattachmentsid the draft file area id for inline attachments in the content 459 * @param int $attachmentsid the draft file area id for attachments 460 * @return array Containing the new created submission id and warnings. 461 * @since Moodle 3.4 462 * @throws moodle_exception 463 */ 464 public static function add_submission($workshopid, $title, $content = '', $contentformat = FORMAT_MOODLE, 465 $inlineattachmentsid = 0, $attachmentsid = 0) { 466 global $USER; 467 468 $params = self::validate_parameters(self::add_submission_parameters(), array( 469 'workshopid' => $workshopid, 470 'title' => $title, 471 'content' => $content, 472 'contentformat' => $contentformat, 473 'inlineattachmentsid' => $inlineattachmentsid, 474 'attachmentsid' => $attachmentsid, 475 )); 476 $warnings = array(); 477 478 // Get and validate the workshop. 479 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']); 480 require_capability('mod/workshop:submit', $context); 481 482 // Check if we can submit now. 483 $canaddsubmission = $workshop->creating_submission_allowed($USER->id); 484 $canaddsubmission = $canaddsubmission && $workshop->check_examples_assessed_before_submission($USER->id); 485 if (!$canaddsubmission) { 486 throw new moodle_exception('nopermissions', 'error', '', 'add submission'); 487 } 488 489 // Prepare the submission object. 490 $submission = new stdClass; 491 $submission->id = null; 492 $submission->cmid = $cm->id; 493 $submission->example = 0; 494 $submission->title = trim($params['title']); 495 $submission->content_editor = array( 496 'text' => $params['content'], 497 'format' => $params['contentformat'], 498 'itemid' => $params['inlineattachmentsid'], 499 ); 500 $submission->attachment_filemanager = $params['attachmentsid']; 501 502 if (empty($submission->title)) { 503 throw new moodle_exception('errorinvalidparam', 'webservice', '', 'title'); 504 } 505 506 $errors = $workshop->validate_submission_data((array) $submission); 507 // We can get several errors, return them in warnings. 508 if (!empty($errors)) { 509 $submission->id = 0; 510 foreach ($errors as $itemname => $message) { 511 $warnings[] = array( 512 'item' => $itemname, 513 'itemid' => 0, 514 'warningcode' => 'fielderror', 515 'message' => s($message) 516 ); 517 } 518 return array( 519 'status' => false, 520 'warnings' => $warnings 521 ); 522 } else { 523 $submission->id = $workshop->edit_submission($submission); 524 return array( 525 'status' => true, 526 'submissionid' => $submission->id, 527 'warnings' => $warnings 528 ); 529 } 530 } 531 532 /** 533 * Returns the description of the external function return value. 534 * 535 * @return external_description 536 * @since Moodle 3.4 537 */ 538 public static function add_submission_returns() { 539 return new external_single_structure(array( 540 'status' => new external_value(PARAM_BOOL, 'True if the submission was created false otherwise.'), 541 'submissionid' => new external_value(PARAM_INT, 'New workshop submission id.', VALUE_OPTIONAL), 542 'warnings' => new external_warnings() 543 )); 544 } 545 546 /** 547 * Returns the description of the external function parameters. 548 * 549 * @return external_function_parameters 550 * @since Moodle 3.4 551 */ 552 public static function update_submission_parameters() { 553 return new external_function_parameters(array( 554 'submissionid' => new external_value(PARAM_INT, 'Submission id'), 555 'title' => new external_value(PARAM_TEXT, 'Submission title'), 556 'content' => new external_value(PARAM_RAW, 'Submission text content', VALUE_DEFAULT, ''), 557 'contentformat' => new external_value(PARAM_INT, 'The format used for the content', VALUE_DEFAULT, FORMAT_MOODLE), 558 'inlineattachmentsid' => new external_value(PARAM_INT, 'The draft file area id for inline attachments in the content', 559 VALUE_DEFAULT, 0), 560 'attachmentsid' => new external_value(PARAM_INT, 'The draft file area id for attachments', VALUE_DEFAULT, 0), 561 )); 562 } 563 564 565 /** 566 * Updates the given submission. 567 * 568 * @param int $submissionid the submission id 569 * @param string $title the submission title 570 * @param string $content the submission text content 571 * @param int $contentformat the format used for the content 572 * @param int $inlineattachmentsid the draft file area id for inline attachments in the content 573 * @param int $attachmentsid the draft file area id for attachments 574 * @return array whether the submission was updated and warnings. 575 * @since Moodle 3.4 576 * @throws moodle_exception 577 */ 578 public static function update_submission($submissionid, $title, $content = '', $contentformat = FORMAT_MOODLE, 579 $inlineattachmentsid = 0, $attachmentsid = 0) { 580 global $USER, $DB; 581 582 $params = self::validate_parameters(self::update_submission_parameters(), array( 583 'submissionid' => $submissionid, 584 'title' => $title, 585 'content' => $content, 586 'contentformat' => $contentformat, 587 'inlineattachmentsid' => $inlineattachmentsid, 588 'attachmentsid' => $attachmentsid, 589 )); 590 $warnings = array(); 591 592 // Get and validate the submission and workshop. 593 $submission = $DB->get_record('workshop_submissions', array('id' => $params['submissionid']), '*', MUST_EXIST); 594 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 595 require_capability('mod/workshop:submit', $context); 596 597 // Check if we can update the submission. 598 $canupdatesubmission = $submission->authorid == $USER->id; 599 $canupdatesubmission = $canupdatesubmission && $workshop->modifying_submission_allowed($USER->id); 600 $canupdatesubmission = $canupdatesubmission && $workshop->check_examples_assessed_before_submission($USER->id); 601 if (!$canupdatesubmission) { 602 throw new moodle_exception('nopermissions', 'error', '', 'update submission'); 603 } 604 605 // Prepare the submission object. 606 $submission->title = trim($params['title']); 607 if (empty($submission->title)) { 608 throw new moodle_exception('errorinvalidparam', 'webservice', '', 'title'); 609 } 610 $submission->content_editor = array( 611 'text' => $params['content'], 612 'format' => $params['contentformat'], 613 'itemid' => $params['inlineattachmentsid'], 614 ); 615 $submission->attachment_filemanager = $params['attachmentsid']; 616 617 $errors = $workshop->validate_submission_data((array) $submission); 618 // We can get several errors, return them in warnings. 619 if (!empty($errors)) { 620 $status = false; 621 foreach ($errors as $itemname => $message) { 622 $warnings[] = array( 623 'item' => $itemname, 624 'itemid' => 0, 625 'warningcode' => 'fielderror', 626 'message' => s($message) 627 ); 628 } 629 } else { 630 $status = true; 631 $submission->id = $workshop->edit_submission($submission); 632 } 633 634 return array( 635 'status' => $status, 636 'warnings' => $warnings 637 ); 638 } 639 640 /** 641 * Returns the description of the external function return value. 642 * 643 * @return external_description 644 * @since Moodle 3.4 645 */ 646 public static function update_submission_returns() { 647 return new external_single_structure(array( 648 'status' => new external_value(PARAM_BOOL, 'True if the submission was updated false otherwise.'), 649 'warnings' => new external_warnings() 650 )); 651 } 652 653 /** 654 * Returns the description of the external function parameters. 655 * 656 * @return external_function_parameters 657 * @since Moodle 3.4 658 */ 659 public static function delete_submission_parameters() { 660 return new external_function_parameters( 661 array( 662 'submissionid' => new external_value(PARAM_INT, 'Submission id'), 663 ) 664 ); 665 } 666 667 668 /** 669 * Deletes the given submission. 670 * 671 * @param int $submissionid the submission id. 672 * @return array containing the result status and warnings. 673 * @since Moodle 3.4 674 * @throws moodle_exception 675 */ 676 public static function delete_submission($submissionid) { 677 global $USER, $DB; 678 679 $params = self::validate_parameters(self::delete_submission_parameters(), array('submissionid' => $submissionid)); 680 $warnings = array(); 681 682 // Get and validate the submission and workshop. 683 $submission = $DB->get_record('workshop_submissions', array('id' => $params['submissionid']), '*', MUST_EXIST); 684 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 685 686 // Check if we can delete the submission. 687 if (!has_capability('mod/workshop:deletesubmissions', $context)) { 688 require_capability('mod/workshop:submit', $context); 689 // We can delete our own submission, on time and not yet assessed. 690 $candeletesubmission = $submission->authorid == $USER->id; 691 $candeletesubmission = $candeletesubmission && $workshop->modifying_submission_allowed($USER->id); 692 $candeletesubmission = $candeletesubmission && count($workshop->get_assessments_of_submission($submission->id)) == 0; 693 if (!$candeletesubmission) { 694 throw new moodle_exception('nopermissions', 'error', '', 'delete submission'); 695 } 696 } 697 698 $workshop->delete_submission($submission); 699 700 return array( 701 'status' => true, 702 'warnings' => $warnings 703 ); 704 } 705 706 /** 707 * Returns the description of the external function return value. 708 * 709 * @return external_description 710 * @since Moodle 3.4 711 */ 712 public static function delete_submission_returns() { 713 return new external_single_structure(array( 714 'status' => new external_value(PARAM_BOOL, 'True if the submission was deleted.'), 715 'warnings' => new external_warnings() 716 )); 717 } 718 719 /** 720 * Helper method for returning the submission data according the current user capabilities and current phase. 721 * 722 * @param stdClass $submission the submission data 723 * @param workshop $workshop the workshop class 724 * @param bool $canviewauthorpublished whether the user has the capability mod/workshop:viewauthorpublished on 725 * @param bool $canviewauthornames whether the user has the capability mod/workshop:vviewauthornames on 726 * @param bool $canviewallsubmissions whether the user has the capability mod/workshop:viewallsubmissions on 727 * @return stdClass object with the submission data filtered 728 * @since Moodle 3.4 729 */ 730 protected static function prepare_submission_for_external($submission, workshop $workshop, $canviewauthorpublished = null, 731 $canviewauthornames = null, $canviewallsubmissions = null) { 732 global $USER; 733 734 if (is_null($canviewauthorpublished)) { 735 $canviewauthorpublished = has_capability('mod/workshop:viewauthorpublished', $workshop->context); 736 } 737 if (is_null($canviewauthornames)) { 738 $canviewauthornames = has_capability('mod/workshop:viewauthornames', $workshop->context); 739 } 740 if (is_null($canviewallsubmissions)) { 741 $canviewallsubmissions = has_capability('mod/workshop:viewallsubmissions', $workshop->context); 742 } 743 744 $ownsubmission = $submission->authorid == $USER->id; 745 if (!$canviewauthornames && !$ownsubmission) { 746 $submission->authorid = 0; 747 } 748 749 // Remove grade, gradeover, gradeoverby, feedbackauthor and timegraded for non-teachers or invalid phase. 750 // WS mod_workshop_external::get_grades should be used for retrieving grades by students. 751 if ($workshop->phase < workshop::PHASE_EVALUATION || !$canviewallsubmissions) { 752 $properties = submission_exporter::properties_definition(); 753 foreach ($properties as $attribute => $settings) { 754 // Special case, the feedbackauthor (and who did it) should be returned if the workshop is closed and 755 // the user can view it. 756 if (($attribute == 'feedbackauthor' || $attribute == 'gradeoverby') && 757 $workshop->phase == workshop::PHASE_CLOSED && $ownsubmission) { 758 continue; 759 } 760 if (!empty($settings['optional'])) { 761 unset($submission->{$attribute}); 762 } 763 } 764 } 765 return $submission; 766 } 767 768 /** 769 * Returns description of method parameters 770 * 771 * @return external_function_parameters 772 * @since Moodle 3.4 773 */ 774 public static function get_submissions_parameters() { 775 return new external_function_parameters( 776 array( 777 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id.'), 778 'userid' => new external_value(PARAM_INT, 'Get submissions done by this user. Use 0 or empty for the current user', 779 VALUE_DEFAULT, 0), 780 'groupid' => new external_value(PARAM_INT, 'Group id, 0 means that the function will determine the user group. 781 It will return submissions done by users in the given group.', 782 VALUE_DEFAULT, 0), 783 'page' => new external_value(PARAM_INT, 'The page of records to return.', VALUE_DEFAULT, 0), 784 'perpage' => new external_value(PARAM_INT, 'The number of records to return per page.', VALUE_DEFAULT, 0), 785 ) 786 ); 787 } 788 789 /** 790 * Retrieves all the workshop submissions visible by the current user or the one done by the given user 791 * (except example submissions). 792 * 793 * @param int $workshopid the workshop instance id 794 * @param int $userid get submissions done by this user 795 * @param int $groupid (optional) group id, 0 means that the function will determine the user group 796 * @param int $page page of records to return 797 * @param int $perpage number of records to return per page 798 * @return array of warnings and the entries 799 * @since Moodle 3.4 800 * @throws moodle_exception 801 */ 802 public static function get_submissions($workshopid, $userid = 0, $groupid = 0, $page = 0, $perpage = 0) { 803 global $PAGE, $USER; 804 805 $params = array('workshopid' => $workshopid, 'userid' => $userid, 'groupid' => $groupid, 806 'page' => $page, 'perpage' => $perpage); 807 $params = self::validate_parameters(self::get_submissions_parameters(), $params); 808 $submissions = $warnings = array(); 809 810 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']); 811 812 if (empty($params['groupid'])) { 813 // Check to see if groups are being used here. 814 if ($groupmode = groups_get_activity_groupmode($cm)) { 815 $groupid = groups_get_activity_group($cm); 816 // Determine is the group is visible to user (this is particullary for the group 0 -> all groups). 817 if (!groups_group_visible($groupid, $course, $cm)) { 818 throw new moodle_exception('notingroup'); 819 } 820 } else { 821 $groupid = 0; 822 } 823 } 824 825 if (!empty($params['userid']) && $params['userid'] != $USER->id) { 826 $user = core_user::get_user($params['userid'], '*', MUST_EXIST); 827 core_user::require_active_user($user); 828 if (!$workshop->check_group_membership($user->id)) { 829 throw new moodle_exception('notingroup'); 830 } 831 } 832 833 $totalfilesize = 0; 834 list($submissionsrecords, $totalcount) = 835 $workshop->get_visible_submissions($params['userid'], $groupid, $params['page'], $params['perpage']); 836 837 if ($totalcount) { 838 839 $canviewauthorpublished = has_capability('mod/workshop:viewauthorpublished', $context); 840 $canviewauthornames = has_capability('mod/workshop:viewauthornames', $context); 841 $canviewallsubmissions = has_capability('mod/workshop:viewallsubmissions', $context); 842 843 $related = array('context' => $context); 844 foreach ($submissionsrecords as $submission) { 845 $submission = self::prepare_submission_for_external($submission, $workshop, $canviewauthorpublished, 846 $canviewauthornames, $canviewallsubmissions); 847 848 $exporter = new submission_exporter($submission, $related); 849 $submissions[] = $exporter->export($PAGE->get_renderer('core')); 850 } 851 852 // Retrieve total files size for the submissions (so external clients know how many data they'd need to download). 853 $fs = get_file_storage(); 854 $files = $fs->get_area_files($context->id, 'mod_workshop', array('submission_content', 'submission_attachment')); 855 foreach ($files as $file) { 856 if ($file->is_directory()) { 857 continue; 858 } 859 $totalfilesize += $file->get_filesize(); 860 } 861 } 862 863 return array( 864 'submissions' => $submissions, 865 'totalcount' => $totalcount, 866 'totalfilesize' => $totalfilesize, 867 ); 868 } 869 870 /** 871 * Returns description of method result value 872 * 873 * @return external_description 874 * @since Moodle 3.4 875 */ 876 public static function get_submissions_returns() { 877 return new external_single_structure( 878 array( 879 'submissions' => new external_multiple_structure( 880 submission_exporter::get_read_structure() 881 ), 882 'totalcount' => new external_value(PARAM_INT, 'Total count of submissions.'), 883 'totalfilesize' => new external_value(PARAM_INT, 'Total size (bytes) of the files attached to all the 884 submissions (even the ones not returned due to pagination).'), 885 'warnings' => new external_warnings() 886 ) 887 ); 888 } 889 890 /** 891 * Helper method for validating a submission. 892 * 893 * @param stdClass $submission submission object 894 * @param workshop $workshop workshop instance 895 * @return void 896 * @since Moodle 3.4 897 */ 898 protected static function validate_submission($submission, workshop $workshop) { 899 global $USER; 900 901 $workshopclosed = $workshop->phase == workshop::PHASE_CLOSED; 902 $canviewpublished = has_capability('mod/workshop:viewpublishedsubmissions', $workshop->context); 903 904 $canview = $submission->authorid == $USER->id; // I did it. 905 $canview = $canview || !empty($workshop->get_assessment_of_submission_by_user($submission->id, $USER->id)); // I reviewed. 906 $canview = $canview || has_capability('mod/workshop:viewallsubmissions', $workshop->context); // I can view all. 907 $canview = $canview || ($submission->published && $workshopclosed && $canviewpublished); // It has been published. 908 909 if ($canview) { 910 // Here we should check if the user share group. 911 if ($submission->authorid != $USER->id && 912 !groups_user_groups_visible($workshop->course, $submission->authorid, $workshop->cm)) { 913 throw new moodle_exception('notingroup'); 914 } 915 } else { 916 throw new moodle_exception('nopermissions', 'error', '', 'view submission'); 917 } 918 } 919 920 /** 921 * Returns the description of the external function parameters. 922 * 923 * @return external_function_parameters 924 * @since Moodle 3.4 925 */ 926 public static function get_submission_parameters() { 927 return new external_function_parameters( 928 array( 929 'submissionid' => new external_value(PARAM_INT, 'Submission id'), 930 ) 931 ); 932 } 933 934 935 /** 936 * Retrieves the given submission. 937 * 938 * @param int $submissionid the submission id 939 * @return array containing the submission and warnings. 940 * @since Moodle 3.4 941 * @throws moodle_exception 942 */ 943 public static function get_submission($submissionid) { 944 global $USER, $DB, $PAGE; 945 946 $params = self::validate_parameters(self::get_submission_parameters(), array('submissionid' => $submissionid)); 947 $warnings = array(); 948 949 // Get and validate the submission and workshop. 950 $submission = $DB->get_record('workshop_submissions', array('id' => $params['submissionid']), '*', MUST_EXIST); 951 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 952 953 self::validate_submission($submission, $workshop); 954 955 $submission = self::prepare_submission_for_external($submission, $workshop); 956 957 $related = array('context' => $context); 958 $exporter = new submission_exporter($submission, $related); 959 return array( 960 'submission' => $exporter->export($PAGE->get_renderer('core')), 961 'warnings' => $warnings 962 ); 963 } 964 965 /** 966 * Returns description of method result value 967 * 968 * @return external_description 969 * @since Moodle 3.4 970 */ 971 public static function get_submission_returns() { 972 return new external_single_structure( 973 array( 974 'submission' => submission_exporter::get_read_structure(), 975 'warnings' => new external_warnings() 976 ) 977 ); 978 } 979 980 /** 981 * Helper method for validating if the current user can view the submission assessments. 982 * 983 * @param stdClass $submission submission object 984 * @param workshop $workshop workshop instance 985 * @return void 986 * @since Moodle 3.4 987 */ 988 protected static function check_view_submission_assessments($submission, workshop $workshop) { 989 global $USER; 990 991 $ownsubmission = $submission->authorid == $USER->id; 992 $canview = has_capability('mod/workshop:viewallassessments', $workshop->context) || 993 ($ownsubmission && $workshop->assessments_available()); 994 995 if ($canview) { 996 // Here we should check if the user share group. 997 if ($submission->authorid != $USER->id && 998 !groups_user_groups_visible($workshop->course, $submission->authorid, $workshop->cm)) { 999 throw new moodle_exception('notingroup'); 1000 } 1001 } else { 1002 throw new moodle_exception('nopermissions', 'error', '', 'view assessment'); 1003 } 1004 } 1005 1006 /** 1007 * Helper method for returning the assessment data according the current user capabilities and current phase. 1008 * 1009 * @param stdClass $assessment the assessment data 1010 * @param workshop $workshop the workshop class 1011 * @return stdClass object with the assessment data filtered or null if is not viewable yet 1012 * @since Moodle 3.4 1013 */ 1014 protected static function prepare_assessment_for_external($assessment, workshop $workshop) { 1015 global $USER; 1016 static $canviewallassessments = null; 1017 static $canviewreviewers = null; 1018 static $canoverridegrades = null; 1019 1020 // Remove all the properties that does not belong to the assessment table. 1021 $properties = assessment_exporter::properties_definition(); 1022 foreach ($assessment as $key => $value) { 1023 if (!isset($properties[$key])) { 1024 unset($assessment->{$key}); 1025 } 1026 } 1027 1028 if (is_null($canviewallassessments)) { 1029 $canviewallassessments = has_capability('mod/workshop:viewallassessments', $workshop->context); 1030 } 1031 if (is_null($canviewreviewers)) { 1032 $canviewreviewers = has_capability('mod/workshop:viewreviewernames', $workshop->context); 1033 } 1034 if (is_null($canoverridegrades)) { 1035 $canoverridegrades = has_capability('mod/workshop:overridegrades', $workshop->context); 1036 } 1037 1038 $isreviewer = $assessment->reviewerid == $USER->id; 1039 1040 if (!$isreviewer && is_null($assessment->grade) && !$canviewallassessments) { 1041 // Students do not see peer-assessment that are not graded yet. 1042 return null; 1043 } 1044 1045 // Remove the feedback for the reviewer if: 1046 // I can't see it in the evaluation phase because I'm not a teacher or the reviewer AND 1047 // I can't see it in the assessment phase because I'm not a teacher. 1048 if (($workshop->phase < workshop::PHASE_EVALUATION || !($isreviewer || $canviewallassessments)) && 1049 ($workshop->phase < workshop::PHASE_ASSESSMENT || !$canviewallassessments) ) { 1050 // Remove all the feedback information (all the optional fields). 1051 foreach ($properties as $attribute => $settings) { 1052 if (!empty($settings['optional'])) { 1053 unset($assessment->{$attribute}); 1054 } 1055 } 1056 } 1057 1058 if (!$isreviewer && !$canviewreviewers) { 1059 $assessment->reviewerid = 0; 1060 } 1061 1062 return $assessment; 1063 } 1064 1065 /** 1066 * Returns the description of the external function parameters. 1067 * 1068 * @return external_function_parameters 1069 * @since Moodle 3.4 1070 */ 1071 public static function get_submission_assessments_parameters() { 1072 return new external_function_parameters( 1073 array( 1074 'submissionid' => new external_value(PARAM_INT, 'Submission id'), 1075 ) 1076 ); 1077 } 1078 1079 1080 /** 1081 * Retrieves the given submission assessments. 1082 * 1083 * @param int $submissionid the submission id 1084 * @return array containing the assessments and warnings. 1085 * @since Moodle 3.4 1086 * @throws moodle_exception 1087 */ 1088 public static function get_submission_assessments($submissionid) { 1089 global $USER, $DB, $PAGE; 1090 1091 $params = self::validate_parameters(self::get_submission_assessments_parameters(), array('submissionid' => $submissionid)); 1092 $warnings = $assessments = array(); 1093 1094 // Get and validate the submission and workshop. 1095 $submission = $DB->get_record('workshop_submissions', array('id' => $params['submissionid']), '*', MUST_EXIST); 1096 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 1097 1098 // Check that we can get the assessments and get them. 1099 self::check_view_submission_assessments($submission, $workshop); 1100 $assessmentsrecords = $workshop->get_assessments_of_submission($submission->id); 1101 1102 $related = array('context' => $context); 1103 foreach ($assessmentsrecords as $assessment) { 1104 $assessment = self::prepare_assessment_for_external($assessment, $workshop); 1105 if (empty($assessment)) { 1106 continue; 1107 } 1108 $exporter = new assessment_exporter($assessment, $related); 1109 $assessments[] = $exporter->export($PAGE->get_renderer('core')); 1110 } 1111 1112 return array( 1113 'assessments' => $assessments, 1114 'warnings' => $warnings 1115 ); 1116 } 1117 1118 /** 1119 * Returns description of method result value 1120 * 1121 * @return external_description 1122 * @since Moodle 3.4 1123 */ 1124 public static function get_submission_assessments_returns() { 1125 return new external_single_structure( 1126 array( 1127 'assessments' => new external_multiple_structure( 1128 assessment_exporter::get_read_structure() 1129 ), 1130 'warnings' => new external_warnings() 1131 ) 1132 ); 1133 } 1134 1135 /** 1136 * Returns the description of the external function parameters. 1137 * 1138 * @return external_function_parameters 1139 * @since Moodle 3.4 1140 */ 1141 public static function get_assessment_parameters() { 1142 return new external_function_parameters( 1143 array( 1144 'assessmentid' => new external_value(PARAM_INT, 'Assessment id'), 1145 ) 1146 ); 1147 } 1148 1149 1150 /** 1151 * Retrieves the given assessment. 1152 * 1153 * @param int $assessmentid the assessment id 1154 * @return array containing the assessment and warnings. 1155 * @since Moodle 3.4 1156 * @throws moodle_exception 1157 */ 1158 public static function get_assessment($assessmentid) { 1159 global $DB, $PAGE; 1160 1161 $params = self::validate_parameters(self::get_assessment_parameters(), array('assessmentid' => $assessmentid)); 1162 $warnings = array(); 1163 1164 // Get and validate the assessment, submission and workshop. 1165 $assessment = $DB->get_record('workshop_assessments', array('id' => $params['assessmentid']), '*', MUST_EXIST); 1166 $submission = $DB->get_record('workshop_submissions', array('id' => $assessment->submissionid), '*', MUST_EXIST); 1167 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 1168 1169 // Check that we can get the assessment. 1170 $workshop->check_view_assessment($assessment, $submission); 1171 1172 $assessment = $workshop->get_assessment_by_id($assessment->id); 1173 $assessment = self::prepare_assessment_for_external($assessment, $workshop); 1174 if (empty($assessment)) { 1175 throw new moodle_exception('nopermissions', 'error', '', 'view assessment'); 1176 } 1177 $related = array('context' => $context); 1178 $exporter = new assessment_exporter($assessment, $related); 1179 1180 return array( 1181 'assessment' => $exporter->export($PAGE->get_renderer('core')), 1182 'warnings' => $warnings 1183 ); 1184 } 1185 1186 /** 1187 * Returns description of method result value 1188 * 1189 * @return external_description 1190 * @since Moodle 3.4 1191 */ 1192 public static function get_assessment_returns() { 1193 return new external_single_structure( 1194 array( 1195 'assessment' => assessment_exporter::get_read_structure(), 1196 'warnings' => new external_warnings() 1197 ) 1198 ); 1199 } 1200 1201 /** 1202 * Returns the description of the external function parameters. 1203 * 1204 * @return external_function_parameters 1205 * @since Moodle 3.4 1206 */ 1207 public static function get_assessment_form_definition_parameters() { 1208 return new external_function_parameters( 1209 array( 1210 'assessmentid' => new external_value(PARAM_INT, 'Assessment id'), 1211 'mode' => new external_value(PARAM_ALPHA, 'The form mode (assessment or preview)', VALUE_DEFAULT, 'assessment'), 1212 ) 1213 ); 1214 } 1215 1216 1217 /** 1218 * Retrieves the assessment form definition (data required to be able to display the assessment form). 1219 * 1220 * @param int $assessmentid the assessment id 1221 * @param string $mode the form mode (assessment or preview) 1222 * @return array containing the assessment and warnings. 1223 * @since Moodle 3.4 1224 * @throws moodle_exception 1225 */ 1226 public static function get_assessment_form_definition($assessmentid, $mode = 'assessment') { 1227 global $DB, $USER; 1228 1229 $params = self::validate_parameters( 1230 self::get_assessment_form_definition_parameters(), array('assessmentid' => $assessmentid, 'mode' => $mode) 1231 ); 1232 $warnings = $pending = array(); 1233 1234 if ($params['mode'] != 'assessment' && $params['mode'] != 'preview') { 1235 throw new invalid_parameter_exception('Invalid value for mode parameter (value: ' . $params['mode'] . ')'); 1236 } 1237 1238 // Get and validate the assessment, submission and workshop. 1239 $assessment = $DB->get_record('workshop_assessments', array('id' => $params['assessmentid']), '*', MUST_EXIST); 1240 $submission = $DB->get_record('workshop_submissions', array('id' => $assessment->submissionid), '*', MUST_EXIST); 1241 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 1242 1243 // Check we can view the assessment (so we can get the form data). 1244 $workshop->check_view_assessment($assessment, $submission); 1245 1246 $cansetassessmentweight = has_capability('mod/workshop:allocate', $context); 1247 $pending = $workshop->get_pending_assessments_by_reviewer($assessment->reviewerid, $assessment->id); 1248 1249 // Retrieve the data from the strategy plugin. 1250 $strategy = $workshop->grading_strategy_instance(); 1251 $strategyname = str_replace('_strategy', '', get_class($strategy)); // Get strategy name. 1252 $mform = $strategy->get_assessment_form(null, $params['mode'], $assessment, true, 1253 array('editableweight' => $cansetassessmentweight, 'pending' => !empty($pending))); 1254 $formdata = $mform->get_customdata(); 1255 1256 $result = array( 1257 'dimenssionscount' => $formdata['nodims'], 1258 'descriptionfiles' => external_util::get_area_files($context->id, $strategyname, 'description'), 1259 'warnings' => $warnings 1260 ); 1261 // Include missing dimension fields. 1262 for ($i = 0; $i < $formdata['nodims']; $i++) { 1263 $formdata['fields']->{'gradeid__idx_' . $i} = 0; 1264 $formdata['fields']->{'peercomment__idx_' . $i} = ''; 1265 } 1266 1267 // Convert all the form data for external. 1268 foreach (array('options', 'fields', 'current') as $typeofdata) { 1269 $result[$typeofdata] = array(); 1270 1271 if (!empty($formdata[$typeofdata])) { 1272 $alldata = (array) $formdata[$typeofdata]; 1273 foreach ($alldata as $key => $val) { 1274 if (strpos($key, 'description__idx_')) { 1275 // Format dimension description. 1276 $id = str_replace('description__idx_', '', $key); 1277 list($val, $format) = external_format_text($val, $alldata['dimensionid__idx_' . $id . 'format'], 1278 $context->id, $strategyname, 'description', $alldata['dimensionid__idx_' . $id]); 1279 } 1280 $result[$typeofdata][] = array( 1281 'name' => $key, 1282 'value' => $val 1283 ); 1284 } 1285 } 1286 } 1287 1288 // Get dimensions info. 1289 $grader = $workshop->grading_strategy_instance(); 1290 $result['dimensionsinfo'] = $grader->get_dimensions_info(); 1291 1292 return $result; 1293 } 1294 1295 /** 1296 * Returns description of method result value 1297 * 1298 * @return external_description 1299 * @since Moodle 3.4 1300 */ 1301 public static function get_assessment_form_definition_returns() { 1302 return new external_single_structure( 1303 array( 1304 'dimenssionscount' => new external_value(PARAM_INT, 'The number of dimenssions used by the form.'), 1305 'descriptionfiles' => new external_files('Files in the description text'), 1306 'options' => new external_multiple_structure( 1307 new external_single_structure( 1308 array( 1309 'name' => new external_value(PARAM_ALPHANUMEXT, 'Option name.'), 1310 'value' => new external_value(PARAM_NOTAGS, 'Option value.') 1311 ) 1312 ), 'The form options.' 1313 ), 1314 'fields' => new external_multiple_structure( 1315 new external_single_structure( 1316 array( 1317 'name' => new external_value(PARAM_ALPHANUMEXT, 'Field name.'), 1318 'value' => new external_value(PARAM_RAW, 'Field default value.') 1319 ) 1320 ), 'The form fields.' 1321 ), 1322 'current' => new external_multiple_structure( 1323 new external_single_structure( 1324 array( 1325 'name' => new external_value(PARAM_ALPHANUMEXT, 'Field name.'), 1326 'value' => new external_value(PARAM_RAW, 'Current field value.') 1327 ) 1328 ), 'The current field values.' 1329 ), 1330 'dimensionsinfo' => new external_multiple_structure( 1331 new external_single_structure( 1332 array( 1333 'id' => new external_value(PARAM_INT, 'Dimension id.'), 1334 'min' => new external_value(PARAM_FLOAT, 'Minimum grade for the dimension.'), 1335 'max' => new external_value(PARAM_FLOAT, 'Maximum grade for the dimension.'), 1336 'weight' => new external_value(PARAM_TEXT, 'The weight of the dimension.'), 1337 'scale' => new external_value(PARAM_TEXT, 'Scale items (if used).', VALUE_OPTIONAL), 1338 ) 1339 ), 'The dimensions general information.' 1340 ), 1341 'warnings' => new external_warnings() 1342 ) 1343 ); 1344 } 1345 1346 /** 1347 * Returns the description of the external function parameters. 1348 * 1349 * @return external_function_parameters 1350 * @since Moodle 3.4 1351 */ 1352 public static function get_reviewer_assessments_parameters() { 1353 return new external_function_parameters( 1354 array( 1355 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id.'), 1356 'userid' => new external_value(PARAM_INT, 'User id who did the assessment review (empty or 0 for current user).', 1357 VALUE_DEFAULT, 0), 1358 ) 1359 ); 1360 } 1361 1362 1363 /** 1364 * Retrieves all the assessments reviewed by the given user. 1365 * 1366 * @param int $workshopid the workshop instance id 1367 * @param int $userid the reviewer user id 1368 * @return array containing the user assessments and warnings. 1369 * @since Moodle 3.4 1370 * @throws moodle_exception 1371 */ 1372 public static function get_reviewer_assessments($workshopid, $userid = 0) { 1373 global $USER, $DB, $PAGE; 1374 1375 $params = self::validate_parameters( 1376 self::get_reviewer_assessments_parameters(), array('workshopid' => $workshopid, 'userid' => $userid) 1377 ); 1378 $warnings = $assessments = array(); 1379 1380 // Get and validate the submission and workshop. 1381 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']); 1382 1383 // Extra checks so only users with permissions can view other users assessments. 1384 if (empty($params['userid']) || $params['userid'] == $USER->id) { 1385 $userid = $USER->id; 1386 list($assessed, $notice) = $workshop->check_examples_assessed_before_assessment($userid); 1387 if (!$assessed) { 1388 throw new moodle_exception($notice, 'mod_workshop'); 1389 } 1390 if ($workshop->phase < workshop::PHASE_ASSESSMENT) { // Can view assessments only in assessment phase onwards. 1391 throw new moodle_exception('nopermissions', 'error', '', 'view assessments'); 1392 } 1393 } else { 1394 require_capability('mod/workshop:viewallassessments', $context); 1395 $user = core_user::get_user($params['userid'], '*', MUST_EXIST); 1396 core_user::require_active_user($user); 1397 if (!$workshop->check_group_membership($user->id)) { 1398 throw new moodle_exception('notingroup'); 1399 } 1400 $userid = $user->id; 1401 } 1402 // Now get all my assessments (includes those pending review). 1403 $assessmentsrecords = $workshop->get_assessments_by_reviewer($userid); 1404 1405 $related = array('context' => $context); 1406 foreach ($assessmentsrecords as $assessment) { 1407 $assessment = self::prepare_assessment_for_external($assessment, $workshop); 1408 if (empty($assessment)) { 1409 continue; 1410 } 1411 $exporter = new assessment_exporter($assessment, $related); 1412 $assessments[] = $exporter->export($PAGE->get_renderer('core')); 1413 } 1414 1415 return array( 1416 'assessments' => $assessments, 1417 'warnings' => $warnings 1418 ); 1419 } 1420 1421 /** 1422 * Returns description of method result value 1423 * 1424 * @return external_description 1425 * @since Moodle 3.4 1426 */ 1427 public static function get_reviewer_assessments_returns() { 1428 return new external_single_structure( 1429 array( 1430 'assessments' => new external_multiple_structure( 1431 assessment_exporter::get_read_structure() 1432 ), 1433 'warnings' => new external_warnings() 1434 ) 1435 ); 1436 } 1437 1438 /** 1439 * Returns the description of the external function parameters. 1440 * 1441 * @return external_function_parameters 1442 * @since Moodle 3.4 1443 */ 1444 public static function update_assessment_parameters() { 1445 return new external_function_parameters( 1446 array( 1447 'assessmentid' => new external_value(PARAM_INT, 'Assessment id.'), 1448 'data' => new external_multiple_structure ( 1449 new external_single_structure( 1450 array( 1451 'name' => new external_value(PARAM_ALPHANUMEXT, 1452 'The assessment data (use WS get_assessment_form_definition for obtaining the data to sent). 1453 Apart from that data, you can optionally send: 1454 feedbackauthor (str); the feedback for the submission author 1455 feedbackauthorformat (int); the format of the feedbackauthor 1456 feedbackauthorinlineattachmentsid (int); the draft file area for the editor attachments 1457 feedbackauthorattachmentsid (int); the draft file area id for the feedback attachments' 1458 ), 1459 'value' => new external_value(PARAM_RAW, 'The value of the option.') 1460 ) 1461 ), 'Assessment data' 1462 ) 1463 ) 1464 ); 1465 } 1466 1467 1468 /** 1469 * Updates an assessment. 1470 * 1471 * @param int $assessmentid the assessment id 1472 * @param array $data the assessment data 1473 * @return array indicates if the assessment was updated, the new raw grade and possible warnings. 1474 * @since Moodle 3.4 1475 * @throws moodle_exception 1476 */ 1477 public static function update_assessment($assessmentid, $data) { 1478 global $DB, $USER; 1479 1480 $params = self::validate_parameters( 1481 self::update_assessment_parameters(), array('assessmentid' => $assessmentid, 'data' => $data) 1482 ); 1483 $warnings = array(); 1484 1485 // Get and validate the assessment, submission and workshop. 1486 $assessment = $DB->get_record('workshop_assessments', array('id' => $params['assessmentid']), '*', MUST_EXIST); 1487 $submission = $DB->get_record('workshop_submissions', array('id' => $assessment->submissionid), '*', MUST_EXIST); 1488 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 1489 1490 // Check we can edit the assessment. 1491 $workshop->check_edit_assessment($assessment, $submission); 1492 1493 // Process data. 1494 $data = new stdClass; 1495 $data->feedbackauthor_editor = array(); 1496 1497 foreach ($params['data'] as $wsdata) { 1498 $name = trim($wsdata['name']); 1499 switch ($name) { 1500 case 'feedbackauthor': 1501 $data->feedbackauthor_editor['text'] = $wsdata['value']; 1502 break; 1503 case 'feedbackauthorformat': 1504 $data->feedbackauthor_editor['format'] = clean_param($wsdata['value'], PARAM_FORMAT); 1505 break; 1506 case 'feedbackauthorinlineattachmentsid': 1507 $data->feedbackauthor_editor['itemid'] = clean_param($wsdata['value'], PARAM_INT); 1508 break; 1509 case 'feedbackauthorattachmentsid': 1510 $data->feedbackauthorattachment_filemanager = clean_param($wsdata['value'], PARAM_INT); 1511 break; 1512 default: 1513 $data->{$wsdata['name']} = $wsdata['value']; // Validation will be done in the form->validation. 1514 } 1515 } 1516 1517 $cansetassessmentweight = has_capability('mod/workshop:allocate', $context); 1518 $pending = $workshop->get_pending_assessments_by_reviewer($assessment->reviewerid, $assessment->id); 1519 // Retrieve the data from the strategy plugin. 1520 $strategy = $workshop->grading_strategy_instance(); 1521 $mform = $strategy->get_assessment_form(null, 'assessment', $assessment, true, 1522 array('editableweight' => $cansetassessmentweight, 'pending' => !empty($pending))); 1523 1524 $errors = $mform->validation((array) $data, array()); 1525 // We can get several errors, return them in warnings. 1526 if (!empty($errors)) { 1527 $status = false; 1528 $rawgrade = null; 1529 foreach ($errors as $itemname => $message) { 1530 $warnings[] = array( 1531 'item' => $itemname, 1532 'itemid' => 0, 1533 'warningcode' => 'fielderror', 1534 'message' => s($message) 1535 ); 1536 } 1537 } else { 1538 $rawgrade = $workshop->edit_assessment($assessment, $submission, $data, $strategy); 1539 $status = true; 1540 } 1541 1542 return array( 1543 'status' => $status, 1544 'rawgrade' => $rawgrade, 1545 'warnings' => $warnings, 1546 ); 1547 } 1548 1549 /** 1550 * Returns description of method result value 1551 * 1552 * @return external_description 1553 * @since Moodle 3.4 1554 */ 1555 public static function update_assessment_returns() { 1556 return new external_single_structure( 1557 array( 1558 'status' => new external_value(PARAM_BOOL, 'status: true if the assessment was added or updated false otherwise.'), 1559 'rawgrade' => new external_value(PARAM_FLOAT, 'Raw percentual grade (0.00000 to 100.00000) for submission.', 1560 VALUE_OPTIONAL), 1561 'warnings' => new external_warnings() 1562 ) 1563 ); 1564 } 1565 1566 /** 1567 * Returns the description of the external function parameters. 1568 * 1569 * @return external_external_function_parameters 1570 * @since Moodle 3.4 1571 */ 1572 public static function get_grades_parameters() { 1573 return new external_function_parameters ( 1574 array( 1575 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id.'), 1576 'userid' => new external_value(PARAM_INT, 'User id (empty or 0 for current user).', VALUE_DEFAULT, 0), 1577 ) 1578 ); 1579 } 1580 1581 /** 1582 * Returns the grades information for the given workshop and user. 1583 * 1584 * @param int $workshopid workshop instance id 1585 * @param int $userid user id 1586 * @return array of warnings and the user plan 1587 * @since Moodle 3.4 1588 * @throws moodle_exception 1589 */ 1590 public static function get_grades($workshopid, $userid = 0) { 1591 global $USER; 1592 1593 $params = array( 1594 'workshopid' => $workshopid, 1595 'userid' => $userid, 1596 ); 1597 $params = self::validate_parameters(self::get_grades_parameters(), $params); 1598 $warnings = array(); 1599 1600 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']); 1601 1602 // Extra checks so only users with permissions can view other users plans. 1603 if (empty($params['userid']) || $params['userid'] == $USER->id) { 1604 $userid = $USER->id; 1605 } else { 1606 require_capability('mod/workshop:viewallassessments', $context); 1607 $user = core_user::get_user($params['userid'], '*', MUST_EXIST); 1608 core_user::require_active_user($user); 1609 if (!$workshop->check_group_membership($user->id)) { 1610 throw new moodle_exception('notingroup'); 1611 } 1612 $userid = $user->id; 1613 } 1614 1615 $finalgrades = $workshop->get_gradebook_grades($userid); 1616 1617 $result = array('warnings' => $warnings); 1618 if ($finalgrades !== false) { 1619 if (!empty($finalgrades->submissiongrade)) { 1620 if (is_numeric($finalgrades->submissiongrade->grade)) { 1621 $result['submissionrawgrade'] = $finalgrades->submissiongrade->grade; 1622 } 1623 $result['submissionlongstrgrade'] = $finalgrades->submissiongrade->str_long_grade; 1624 $result['submissiongradehidden'] = $finalgrades->submissiongrade->hidden; 1625 } 1626 if (!empty($finalgrades->assessmentgrade)) { 1627 if (is_numeric($finalgrades->assessmentgrade->grade)) { 1628 $result['assessmentrawgrade'] = $finalgrades->assessmentgrade->grade; 1629 } 1630 $result['assessmentlongstrgrade'] = $finalgrades->assessmentgrade->str_long_grade; 1631 $result['assessmentgradehidden'] = $finalgrades->assessmentgrade->hidden; 1632 } 1633 } 1634 1635 return $result; 1636 } 1637 1638 /** 1639 * Returns description of method result value. 1640 * 1641 * @return external_single_structure 1642 * @since Moodle 3.4 1643 */ 1644 public static function get_grades_returns() { 1645 return new external_single_structure( 1646 array( 1647 'assessmentrawgrade' => new external_value(PARAM_FLOAT, 'The assessment raw (numeric) grade.', VALUE_OPTIONAL), 1648 'assessmentlongstrgrade' => new external_value(PARAM_NOTAGS, 'The assessment string grade.', VALUE_OPTIONAL), 1649 'assessmentgradehidden' => new external_value(PARAM_BOOL, 'Whether the grade is hidden or not.', VALUE_OPTIONAL), 1650 'submissionrawgrade' => new external_value(PARAM_FLOAT, 'The submission raw (numeric) grade.', VALUE_OPTIONAL), 1651 'submissionlongstrgrade' => new external_value(PARAM_NOTAGS, 'The submission string grade.', VALUE_OPTIONAL), 1652 'submissiongradehidden' => new external_value(PARAM_BOOL, 'Whether the grade is hidden or not.', VALUE_OPTIONAL), 1653 'warnings' => new external_warnings(), 1654 ) 1655 ); 1656 } 1657 1658 /** 1659 * Returns the description of the external function parameters. 1660 * 1661 * @return external_function_parameters 1662 * @since Moodle 3.4 1663 */ 1664 public static function evaluate_assessment_parameters() { 1665 return new external_function_parameters( 1666 array( 1667 'assessmentid' => new external_value(PARAM_INT, 'Assessment id.'), 1668 'feedbacktext' => new external_value(PARAM_RAW, 'The feedback for the reviewer.', VALUE_DEFAULT, ''), 1669 'feedbackformat' => new external_value(PARAM_INT, 'The feedback format for text.', VALUE_DEFAULT, FORMAT_MOODLE), 1670 'weight' => new external_value(PARAM_INT, 'The new weight for the assessment.', VALUE_DEFAULT, 1), 1671 'gradinggradeover' => new external_value(PARAM_ALPHANUMEXT, 'The new grading grade.', VALUE_DEFAULT, ''), 1672 ) 1673 ); 1674 } 1675 1676 1677 /** 1678 * Evaluates an assessment (used by teachers for provide feedback to the reviewer). 1679 * 1680 * @param int $assessmentid the assessment id 1681 * @param str $feedbacktext the feedback for the reviewer 1682 * @param int $feedbackformat the feedback format for the reviewer text 1683 * @param int $weight the new weight for the assessment 1684 * @param mixed $gradinggradeover the new grading grade (empty for no overriding the grade) 1685 * @return array containing the status and warnings. 1686 * @since Moodle 3.4 1687 * @throws moodle_exception 1688 */ 1689 public static function evaluate_assessment($assessmentid, $feedbacktext = '', $feedbackformat = FORMAT_MOODLE, $weight = 1, 1690 $gradinggradeover = '') { 1691 global $DB; 1692 1693 $params = self::validate_parameters( 1694 self::evaluate_assessment_parameters(), 1695 array( 1696 'assessmentid' => $assessmentid, 1697 'feedbacktext' => $feedbacktext, 1698 'feedbackformat' => $feedbackformat, 1699 'weight' => $weight, 1700 'gradinggradeover' => $gradinggradeover, 1701 ) 1702 ); 1703 $warnings = array(); 1704 1705 // Get and validate the assessment, submission and workshop. 1706 $assessment = $DB->get_record('workshop_assessments', array('id' => $params['assessmentid']), '*', MUST_EXIST); 1707 $submission = $DB->get_record('workshop_submissions', array('id' => $assessment->submissionid), '*', MUST_EXIST); 1708 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 1709 1710 // Check we can evaluate the assessment. 1711 $workshop->check_view_assessment($assessment, $submission); 1712 $cansetassessmentweight = has_capability('mod/workshop:allocate', $context); 1713 $canoverridegrades = has_capability('mod/workshop:overridegrades', $context); 1714 if (!$canoverridegrades && !$cansetassessmentweight) { 1715 throw new moodle_exception('nopermissions', 'error', '', 'evaluate assessments'); 1716 } 1717 1718 // Process data. 1719 $data = new stdClass; 1720 $data->asid = $assessment->id; 1721 $data->feedbackreviewer_editor = array( 1722 'text' => $params['feedbacktext'], 1723 'format' => $params['feedbackformat'], 1724 ); 1725 $data->weight = $params['weight']; 1726 $data->gradinggradeover = $params['gradinggradeover']; 1727 1728 $options = array( 1729 'editable' => true, 1730 'editableweight' => $cansetassessmentweight, 1731 'overridablegradinggrade' => $canoverridegrades 1732 ); 1733 $feedbackform = $workshop->get_feedbackreviewer_form(null, $assessment, $options); 1734 1735 $errors = $feedbackform->validation((array) $data, array()); 1736 // Extra checks for the new grade and weight. 1737 $possibleweights = workshop::available_assessment_weights_list(); 1738 if ($data->weight < 0 || $data->weight > max(array_keys($possibleweights))) { 1739 $errors['weight'] = 'The new weight must be higher or equal to 0 and cannot be higher than the maximum weight for 1740 assessment.'; 1741 } 1742 if (is_numeric($data->gradinggradeover) && 1743 ($data->gradinggradeover < 0 || $data->gradinggradeover > $workshop->gradinggrade)) { 1744 $errors['gradinggradeover'] = 'The new grade must be higher or equal to 0 and cannot be higher than the maximum grade 1745 for assessment.'; 1746 } 1747 1748 // We can get several errors, return them in warnings. 1749 if (!empty($errors)) { 1750 $status = false; 1751 foreach ($errors as $itemname => $message) { 1752 $warnings[] = array( 1753 'item' => $itemname, 1754 'itemid' => 0, 1755 'warningcode' => 'fielderror', 1756 'message' => s($message) 1757 ); 1758 } 1759 } else { 1760 $workshop->evaluate_assessment($assessment, $data, $cansetassessmentweight, $canoverridegrades); 1761 $status = true; 1762 } 1763 1764 return array( 1765 'status' => $status, 1766 'warnings' => $warnings, 1767 ); 1768 } 1769 1770 /** 1771 * Returns description of method result value 1772 * 1773 * @return external_description 1774 * @since Moodle 3.4 1775 */ 1776 public static function evaluate_assessment_returns() { 1777 return new external_single_structure( 1778 array( 1779 'status' => new external_value(PARAM_BOOL, 'status: true if the assessment was evaluated, false otherwise.'), 1780 'warnings' => new external_warnings() 1781 ) 1782 ); 1783 } 1784 1785 /** 1786 * Returns description of method parameters 1787 * 1788 * @return external_function_parameters 1789 * @since Moodle 3.4 1790 */ 1791 public static function get_grades_report_parameters() { 1792 return new external_function_parameters( 1793 array( 1794 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id.'), 1795 'groupid' => new external_value(PARAM_INT, 'Group id, 0 means that the function will determine the user group.', 1796 VALUE_DEFAULT, 0), 1797 'sortby' => new external_value(PARAM_ALPHA, 'sort by this element: lastname, firstname, submissiontitle, 1798 submissionmodified, submissiongrade, gradinggrade.', VALUE_DEFAULT, 'lastname'), 1799 'sortdirection' => new external_value(PARAM_ALPHA, 'sort direction: ASC or DESC', VALUE_DEFAULT, 'ASC'), 1800 'page' => new external_value(PARAM_INT, 'The page of records to return.', VALUE_DEFAULT, 0), 1801 'perpage' => new external_value(PARAM_INT, 'The number of records to return per page.', VALUE_DEFAULT, 0), 1802 ) 1803 ); 1804 } 1805 1806 /** 1807 * Retrieves the assessment grades report. 1808 * 1809 * @param int $workshopid the workshop instance id 1810 * @param int $groupid (optional) group id, 0 means that the function will determine the user group 1811 * @param string $sortby sort by this element 1812 * @param string $sortdirection sort direction: ASC or DESC 1813 * @param int $page page of records to return 1814 * @param int $perpage number of records to return per page 1815 * @return array of warnings and the report data 1816 * @since Moodle 3.4 1817 * @throws moodle_exception 1818 */ 1819 public static function get_grades_report($workshopid, $groupid = 0, $sortby = 'lastname', $sortdirection = 'ASC', 1820 $page = 0, $perpage = 0) { 1821 global $USER; 1822 1823 $params = array('workshopid' => $workshopid, 'groupid' => $groupid, 'sortby' => $sortby, 'sortdirection' => $sortdirection, 1824 'page' => $page, 'perpage' => $perpage); 1825 $params = self::validate_parameters(self::get_grades_report_parameters(), $params); 1826 $submissions = $warnings = array(); 1827 1828 $sortallowedvalues = array('lastname', 'firstname', 'submissiontitle', 'submissionmodified', 'submissiongrade', 1829 'gradinggrade'); 1830 if (!in_array($params['sortby'], $sortallowedvalues)) { 1831 throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' . 1832 'allowed values are: ' . implode(',', $sortallowedvalues)); 1833 } 1834 1835 $sortdirection = strtoupper($params['sortdirection']); 1836 $directionallowedvalues = array('ASC', 'DESC'); 1837 if (!in_array($sortdirection, $directionallowedvalues)) { 1838 throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' . 1839 'allowed values are: ' . implode(',', $directionallowedvalues)); 1840 } 1841 1842 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']); 1843 require_capability('mod/workshop:viewallassessments', $context); 1844 1845 if (!empty($params['groupid'])) { 1846 $groupid = $params['groupid']; 1847 // Determine is the group is visible to user. 1848 if (!groups_group_visible($groupid, $course, $cm)) { 1849 throw new moodle_exception('notingroup'); 1850 } 1851 } else { 1852 // Check to see if groups are being used here. 1853 if ($groupmode = groups_get_activity_groupmode($cm)) { 1854 $groupid = groups_get_activity_group($cm); 1855 // Determine is the group is visible to user (this is particullary for the group 0 -> all groups). 1856 if (!groups_group_visible($groupid, $course, $cm)) { 1857 throw new moodle_exception('notingroup'); 1858 } 1859 } else { 1860 $groupid = 0; 1861 } 1862 } 1863 1864 if ($workshop->phase >= workshop::PHASE_SUBMISSION) { 1865 $showauthornames = has_capability('mod/workshop:viewauthornames', $context); 1866 $showreviewernames = has_capability('mod/workshop:viewreviewernames', $context); 1867 1868 if ($workshop->phase >= workshop::PHASE_EVALUATION) { 1869 $showsubmissiongrade = true; 1870 $showgradinggrade = true; 1871 } else { 1872 $showsubmissiongrade = false; 1873 $showgradinggrade = false; 1874 } 1875 1876 $data = $workshop->prepare_grading_report_data($USER->id, $groupid, $params['page'], $params['perpage'], 1877 $params['sortby'], $sortdirection); 1878 1879 if (!empty($data)) { 1880 // Populate the display options for the submissions report. 1881 $reportopts = new stdclass(); 1882 $reportopts->showauthornames = $showauthornames; 1883 $reportopts->showreviewernames = $showreviewernames; 1884 $reportopts->sortby = $params['sortby']; 1885 $reportopts->sorthow = $sortdirection; 1886 $reportopts->showsubmissiongrade = $showsubmissiongrade; 1887 $reportopts->showgradinggrade = $showgradinggrade; 1888 $reportopts->workshopphase = $workshop->phase; 1889 1890 $report = new workshop_grading_report($data, $reportopts); 1891 return array( 1892 'report' => $report->export_data_for_external(), 1893 'warnings' => array(), 1894 ); 1895 } 1896 } 1897 throw new moodle_exception('nothingfound', 'workshop'); 1898 } 1899 1900 /** 1901 * Returns description of method result value 1902 * 1903 * @return external_description 1904 * @since Moodle 3.4 1905 */ 1906 public static function get_grades_report_returns() { 1907 1908 $reviewstructure = new external_single_structure( 1909 array( 1910 'userid' => new external_value(PARAM_INT, 'The id of the user (0 when is configured to do not display names).'), 1911 'assessmentid' => new external_value(PARAM_INT, 'The id of the assessment.'), 1912 'submissionid' => new external_value(PARAM_INT, 'The id of the submission assessed.'), 1913 'grade' => new external_value(PARAM_FLOAT, 'The grade for submission.'), 1914 'gradinggrade' => new external_value(PARAM_FLOAT, 'The grade for assessment.'), 1915 'gradinggradeover' => new external_value(PARAM_FLOAT, 'The aggregated grade overrided.'), 1916 'weight' => new external_value(PARAM_INT, 'The weight of the assessment for aggregation.'), 1917 ) 1918 ); 1919 1920 return new external_single_structure( 1921 array( 1922 'report' => new external_single_structure( 1923 array( 1924 'grades' => new external_multiple_structure( 1925 new external_single_structure( 1926 array( 1927 'userid' => new external_value(PARAM_INT, 'The id of the user being displayed in the report.'), 1928 'submissionid' => new external_value(PARAM_INT, 'Submission id.'), 1929 'submissiontitle' => new external_value(PARAM_RAW, 'Submission title.'), 1930 'submissionmodified' => new external_value(PARAM_INT, 'Timestamp submission was updated.'), 1931 'submissiongrade' => new external_value(PARAM_FLOAT, 'Aggregated grade for the submission.', 1932 VALUE_OPTIONAL), 1933 'gradinggrade' => new external_value(PARAM_FLOAT, 'Computed grade for the assessment.', 1934 VALUE_OPTIONAL), 1935 'submissiongradeover' => new external_value(PARAM_FLOAT, 'Grade for the assessment overrided 1936 by the teacher.', VALUE_OPTIONAL), 1937 'submissiongradeoverby' => new external_value(PARAM_INT, 'The id of the user who overrided 1938 the grade.', VALUE_OPTIONAL), 1939 'submissionpublished' => new external_value(PARAM_INT, 'Whether is a submission published.', 1940 VALUE_OPTIONAL), 1941 'reviewedby' => new external_multiple_structure($reviewstructure, 'The users who reviewed the 1942 user submission.', VALUE_OPTIONAL), 1943 'reviewerof' => new external_multiple_structure($reviewstructure, 'The assessments the user 1944 reviewed.', VALUE_OPTIONAL), 1945 ) 1946 ) 1947 ), 1948 'totalcount' => new external_value(PARAM_INT, 'Number of total submissions.'), 1949 ) 1950 ), 1951 'warnings' => new external_warnings() 1952 ) 1953 ); 1954 } 1955 1956 /** 1957 * Describes the parameters for view_submission. 1958 * 1959 * @return external_function_parameters 1960 * @since Moodle 3.4 1961 */ 1962 public static function view_submission_parameters() { 1963 return new external_function_parameters ( 1964 array( 1965 'submissionid' => new external_value(PARAM_INT, 'Submission id'), 1966 ) 1967 ); 1968 } 1969 1970 /** 1971 * Trigger the submission viewed event. 1972 * 1973 * @param int $submissionid submission id 1974 * @return array of warnings and status result 1975 * @since Moodle 3.4 1976 * @throws moodle_exception 1977 */ 1978 public static function view_submission($submissionid) { 1979 global $DB; 1980 1981 $params = self::validate_parameters(self::view_submission_parameters(), array('submissionid' => $submissionid)); 1982 $warnings = array(); 1983 1984 // Get and validate the submission and workshop. 1985 $submission = $DB->get_record('workshop_submissions', array('id' => $params['submissionid']), '*', MUST_EXIST); 1986 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 1987 1988 self::validate_submission($submission, $workshop); 1989 1990 $workshop->set_submission_viewed($submission); 1991 1992 $result = array( 1993 'status' => true, 1994 'warnings' => $warnings, 1995 ); 1996 return $result; 1997 } 1998 1999 /** 2000 * Describes the view_submission return value. 2001 * 2002 * @return external_single_structure 2003 * @since Moodle 3.4 2004 */ 2005 public static function view_submission_returns() { 2006 return new external_single_structure( 2007 array( 2008 'status' => new external_value(PARAM_BOOL, 'status: true if success'), 2009 'warnings' => new external_warnings(), 2010 ) 2011 ); 2012 } 2013 2014 /** 2015 * Returns the description of the external function parameters. 2016 * 2017 * @return external_function_parameters 2018 * @since Moodle 3.4 2019 */ 2020 public static function evaluate_submission_parameters() { 2021 return new external_function_parameters( 2022 array( 2023 'submissionid' => new external_value(PARAM_INT, 'submission id.'), 2024 'feedbacktext' => new external_value(PARAM_RAW, 'The feedback for the author.', VALUE_DEFAULT, ''), 2025 'feedbackformat' => new external_value(PARAM_INT, 'The feedback format for text.', VALUE_DEFAULT, FORMAT_MOODLE), 2026 'published' => new external_value(PARAM_BOOL, 'Publish the submission for others?.', VALUE_DEFAULT, false), 2027 'gradeover' => new external_value(PARAM_ALPHANUMEXT, 'The new submission grade.', VALUE_DEFAULT, ''), 2028 ) 2029 ); 2030 } 2031 2032 2033 /** 2034 * Evaluates a submission (used by teachers for provide feedback or override the submission grade). 2035 * 2036 * @param int $submissionid the submission id 2037 * @param str $feedbacktext the feedback for the author 2038 * @param int $feedbackformat the feedback format for the reviewer text 2039 * @param bool $published whether to publish the submission for other users 2040 * @param mixed $gradeover the new submission grade (empty for no overriding the grade) 2041 * @return array containing the status and warnings. 2042 * @since Moodle 3.4 2043 * @throws moodle_exception 2044 */ 2045 public static function evaluate_submission($submissionid, $feedbacktext = '', $feedbackformat = FORMAT_MOODLE, $published = 1, 2046 $gradeover = '') { 2047 global $DB; 2048 2049 $params = self::validate_parameters( 2050 self::evaluate_submission_parameters(), 2051 array( 2052 'submissionid' => $submissionid, 2053 'feedbacktext' => $feedbacktext, 2054 'feedbackformat' => $feedbackformat, 2055 'published' => $published, 2056 'gradeover' => $gradeover, 2057 ) 2058 ); 2059 $warnings = array(); 2060 2061 // Get and validate the submission, submission and workshop. 2062 $submission = $DB->get_record('workshop_submissions', array('id' => $params['submissionid']), '*', MUST_EXIST); 2063 list($workshop, $course, $cm, $context) = self::validate_workshop($submission->workshopid); 2064 2065 // Check we can evaluate the submission. 2066 self::validate_submission($submission, $workshop); 2067 $canpublish = has_capability('mod/workshop:publishsubmissions', $context); 2068 $canoverride = ($workshop->phase == workshop::PHASE_EVALUATION && 2069 has_capability('mod/workshop:overridegrades', $context)); 2070 2071 if (!$canpublish && !$canoverride) { 2072 throw new moodle_exception('nopermissions', 'error', '', 'evaluate submission'); 2073 } 2074 2075 // Process data. 2076 $data = new stdClass; 2077 $data->id = $submission->id; 2078 $data->feedbackauthor_editor = array( 2079 'text' => $params['feedbacktext'], 2080 'format' => $params['feedbackformat'], 2081 ); 2082 $data->published = $params['published']; 2083 $data->gradeover = $params['gradeover']; 2084 2085 $options = array( 2086 'editable' => true, 2087 'editablepublished' => $canpublish, 2088 'overridablegrade' => $canoverride 2089 ); 2090 $feedbackform = $workshop->get_feedbackauthor_form(null, $submission, $options); 2091 2092 $errors = $feedbackform->validation((array) $data, array()); 2093 // Extra checks for the new grade (if set). 2094 if (is_numeric($data->gradeover) && $data->gradeover > $workshop->grade) { 2095 $errors['gradeover'] = 'The new grade cannot be higher than the maximum grade for submission.'; 2096 } 2097 2098 // We can get several errors, return them in warnings. 2099 if (!empty($errors)) { 2100 $status = false; 2101 foreach ($errors as $itemname => $message) { 2102 $warnings[] = array( 2103 'item' => $itemname, 2104 'itemid' => 0, 2105 'warningcode' => 'fielderror', 2106 'message' => s($message) 2107 ); 2108 } 2109 } else { 2110 $workshop->evaluate_submission($submission, $data, $canpublish, $canoverride); 2111 $status = true; 2112 } 2113 2114 return array( 2115 'status' => $status, 2116 'warnings' => $warnings, 2117 ); 2118 } 2119 2120 /** 2121 * Returns description of method result value 2122 * 2123 * @return external_description 2124 * @since Moodle 3.4 2125 */ 2126 public static function evaluate_submission_returns() { 2127 return new external_single_structure( 2128 array( 2129 'status' => new external_value(PARAM_BOOL, 'status: true if the submission was evaluated, false otherwise.'), 2130 'warnings' => new external_warnings() 2131 ) 2132 ); 2133 } 2134 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
