Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.3.x will end 7 October 2024 (12 months).
- Bug fixes for security issues in 4.3.x will end 21 April 2025 (18 months).
- PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.2.x is supported too.
/question/type/ -> questionbase.php (source)
Differences Between: [Versions 310 and 403] [Versions 311 and 403] [Versions 39 and 403] [Versions 400 and 403] [Versions 401 and 403] [Versions 402 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 * This file defines the class {@link question_definition} and its subclasses. 19 * 20 * The type hierarchy is quite complex. Here is a summary: 21 * - question_definition 22 * - question_information_item 23 * - question_with_responses implements question_manually_gradable 24 * - question_graded_automatically implements question_automatically_gradable 25 * - question_graded_automatically_with_countback implements question_automatically_gradable_with_countback 26 * - question_graded_by_strategy 27 * 28 * Other classes: 29 * - question_classified_response 30 * - question_answer 31 * - question_hint 32 * - question_hint_with_parts 33 * - question_first_matching_answer_grading_strategy implements question_grading_strategy 34 * 35 * Other interfaces: 36 * - question_response_answer_comparer 37 * 38 * @package moodlecore 39 * @subpackage questiontypes 40 * @copyright 2009 The Open University 41 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 42 */ 43 44 use core_question\output\question_version_info; 45 46 defined('MOODLE_INTERNAL') || die(); 47 48 49 /** 50 * The definition of a question of a particular type. 51 * 52 * This class is a close match to the question table in the database. 53 * Definitions of question of a particular type normally subclass one of the 54 * more specific classes {@link question_with_responses}, 55 * {@link question_graded_automatically} or {@link question_information_item}. 56 * 57 * @copyright 2009 The Open University 58 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 59 */ 60 abstract class question_definition { 61 /** @var integer id of the question in the datase, or null if this question 62 * is not in the database. */ 63 public $id; 64 65 /** @var integer question category id. */ 66 public $category; 67 68 /** @var integer question context id. */ 69 public $contextid; 70 71 /** @var integer parent question id. */ 72 public $parent = 0; 73 74 /** @var question_type the question type this question is. */ 75 public $qtype; 76 77 /** @var string question name. */ 78 public $name; 79 80 /** @var string question text. */ 81 public $questiontext; 82 83 /** @var integer question test format. */ 84 public $questiontextformat; 85 86 /** @var string question general feedback. */ 87 public $generalfeedback; 88 89 /** @var integer question test format. */ 90 public $generalfeedbackformat; 91 92 /** @var float what this quetsion is marked out of, by default. */ 93 public $defaultmark = 1; 94 95 /** @var integer How many question numbers this question consumes. */ 96 public $length = 1; 97 98 /** @var number penalty factor of this question. */ 99 public $penalty = 0; 100 101 /** @var string unique identifier of this question. */ 102 public $stamp; 103 104 /** @var string question idnumber. */ 105 public $idnumber; 106 107 /** @var integer timestamp when this question was created. */ 108 public $timecreated; 109 110 /** @var integer timestamp when this question was modified. */ 111 public $timemodified; 112 113 /** @var integer userid of the use who created this question. */ 114 public $createdby; 115 116 /** @var integer userid of the use who modified this question. */ 117 public $modifiedby; 118 119 /** @var array of question_hints. */ 120 public $hints = array(); 121 122 /** @var boolean question status hidden/ready/draft in the question bank. */ 123 public $status = \core_question\local\bank\question_version_status::QUESTION_STATUS_READY; 124 125 /** @var int Version id of the question in a question bank */ 126 public $versionid; 127 128 /** @var int Version number of the question in a question bank */ 129 public $version; 130 131 /** @var int Bank entry id for the question */ 132 public $questionbankentryid; 133 134 /** @var ?int The latest version of the question. null if we haven't checked yet. */ 135 protected $latestversion = null; 136 137 /** 138 * @var array of array of \core_customfield\data_controller objects indexed by fieldid for the questions custom fields. 139 */ 140 public $customfields = array(); 141 142 /** 143 * Constructor. Normally to get a question, you call 144 * {@link question_bank::load_question()}, but questions can be created 145 * directly, for example in unit test code. 146 */ 147 public function __construct() { 148 } 149 150 /** 151 * When a pending definition tries to read its latest version, fill in the latest version for all pending definitions 152 * 153 * @param string $name 154 * @return mixed 155 */ 156 public function __get($name) { 157 if ($name === 'latestversion') { 158 if (isset(question_version_info::$pendingdefinitions[$this->id])) { 159 question_version_info::populate_latest_versions(); 160 } 161 return $this->latestversion; 162 } 163 } 164 165 /** 166 * @return string the name of the question type (for example multichoice) that this 167 * question is. 168 */ 169 public function get_type_name() { 170 return $this->qtype->name(); 171 } 172 173 /** 174 * Creat the appropriate behaviour for an attempt at this quetsion, 175 * given the desired (archetypal) behaviour. 176 * 177 * This default implementation will suit most normal graded questions. 178 * 179 * If your question is of a patricular type, then it may need to do something 180 * different. For example, if your question can only be graded manually, then 181 * it should probably return a manualgraded behaviour, irrespective of 182 * what is asked for. 183 * 184 * If your question wants to do somthing especially complicated is some situations, 185 * then you may wish to return a particular behaviour related to the 186 * one asked for. For example, you migth want to return a 187 * qbehaviour_interactive_adapted_for_myqtype. 188 * 189 * @param question_attempt $qa the attempt we are creating a behaviour for. 190 * @param string $preferredbehaviour the requested type of behaviour. 191 * @return question_behaviour the new behaviour object. 192 */ 193 public function make_behaviour(question_attempt $qa, $preferredbehaviour) { 194 return question_engine::make_archetypal_behaviour($preferredbehaviour, $qa); 195 } 196 197 /** 198 * Start a new attempt at this question, storing any information that will 199 * be needed later in the step. 200 * 201 * This is where the question can do any initialisation required on a 202 * per-attempt basis. For example, this is where the multiple choice 203 * question type randomly shuffles the choices (if that option is set). 204 * 205 * Any information about how the question has been set up for this attempt 206 * should be stored in the $step, by calling $step->set_qt_var(...). 207 * 208 * @param question_attempt_step The first step of the {@link question_attempt} 209 * being started. Can be used to store state. 210 * @param int $varant which variant of this question to start. Will be between 211 * 1 and {@link get_num_variants()} inclusive. 212 */ 213 public function start_attempt(question_attempt_step $step, $variant) { 214 } 215 216 /** 217 * When an in-progress {@link question_attempt} is re-loaded from the 218 * database, this method is called so that the question can re-initialise 219 * its internal state as needed by this attempt. 220 * 221 * For example, the multiple choice question type needs to set the order 222 * of the choices to the order that was set up when start_attempt was called 223 * originally. All the information required to do this should be in the 224 * $step object, which is the first step of the question_attempt being loaded. 225 * 226 * @param question_attempt_step The first step of the {@link question_attempt} 227 * being loaded. 228 */ 229 public function apply_attempt_state(question_attempt_step $step) { 230 } 231 232 /** 233 * Verify if an attempt at this question can be re-graded using the other question version. 234 * 235 * To put it another way, will {@see update_attempt_state_date_from_old_version()} be able to work? 236 * 237 * It is expected that this relationship is symmetrical, so if you can regrade from V1 to V3, then 238 * you can change back from V3 to V1. 239 * 240 * @param question_definition $otherversion a different version of the question to use in the regrade. 241 * @return string|null null if the regrade can proceed, else a reason why not. 242 */ 243 public function validate_can_regrade_with_other_version(question_definition $otherversion): ?string { 244 if (get_class($otherversion) !== get_class($this)) { 245 return get_string('cannotregradedifferentqtype', 'question'); 246 } 247 248 return null; 249 } 250 251 /** 252 * Update the data representing the initial state of an attempt another version of this question, to allow for the changes. 253 * 254 * What is required is probably most easily understood using an example. Think about multiple choice questions. 255 * The first step has a variable '_order' which is a comma-separated list of question_answer ids. 256 * A different version of the question will have different question_answers with different ids. However, the list of 257 * choices should be similar, and so we need to shuffle the new list of ids in the same way that the old one was. 258 * 259 * Note: be sure to return all the data that was originally in $oldstep, while updating the fields that 260 * require it. Otherwise you might break features like 'Each attempt builds on last' in the quiz. 261 * 262 * This method should only be called if {@see validate_can_regrade_with_other_version()} did not 263 * flag up a potential problem. So, this method will throw a {@see coding_exception} if it is not 264 * possible to work out a return value. 265 * 266 * @param question_attempt_step $oldstep the first step of a {@see question_attempt} at $oldquestion. 267 * @param question_definition $oldquestion the previous version of the question, which $oldstate comes from. 268 * @return array the submit data which can be passed to {@see apply_attempt_state} to start 269 * an attempt at this version of this question, corresponding to the attempt at the old question. 270 * @throws coding_exception if this can't be done. 271 */ 272 public function update_attempt_state_data_for_new_version( 273 question_attempt_step $oldstep, question_definition $oldquestion) { 274 $message = $this->validate_can_regrade_with_other_version($oldquestion); 275 if ($message) { 276 throw new coding_exception($message); 277 } 278 279 return $oldstep->get_qt_data(); 280 } 281 282 /** 283 * Generate a brief, plain-text, summary of this question. This is used by 284 * various reports. This should show the particular variant of the question 285 * as presented to students. For example, the calculated quetsion type would 286 * fill in the particular numbers that were presented to the student. 287 * This method will return null if such a summary is not possible, or 288 * inappropriate. 289 * @return string|null a plain text summary of this question. 290 */ 291 public function get_question_summary() { 292 return $this->html_to_text($this->questiontext, $this->questiontextformat); 293 } 294 295 /** 296 * @return int the number of vaiants that this question has. 297 */ 298 public function get_num_variants() { 299 return 1; 300 } 301 302 /** 303 * @return string that can be used to seed the pseudo-random selection of a 304 * variant. 305 */ 306 public function get_variants_selection_seed() { 307 return $this->stamp; 308 } 309 310 /** 311 * Some questions can return a negative mark if the student gets it wrong. 312 * 313 * This method returns the lowest mark the question can return, on the 314 * fraction scale. that is, where the maximum possible mark is 1.0. 315 * 316 * @return float minimum fraction this question will ever return. 317 */ 318 public function get_min_fraction() { 319 return 0; 320 } 321 322 /** 323 * Some questions can return a mark greater than the maximum. 324 * 325 * This method returns the lowest highest the question can return, on the 326 * fraction scale. that is, where the nominal maximum mark is 1.0. 327 * 328 * @return float maximum fraction this question will ever return. 329 */ 330 public function get_max_fraction() { 331 return 1; 332 } 333 334 /** 335 * Given a response, rest the parts that are wrong. 336 * @param array $response a response 337 * @return array a cleaned up response with the wrong bits reset. 338 */ 339 public function clear_wrong_from_response(array $response) { 340 return array(); 341 } 342 343 /** 344 * Return the number of subparts of this response that are right. 345 * @param array $response a response 346 * @return array with two elements, the number of correct subparts, and 347 * the total number of subparts. 348 */ 349 public function get_num_parts_right(array $response) { 350 return array(null, null); 351 } 352 353 /** 354 * @param moodle_page the page we are outputting to. 355 * @return qtype_renderer the renderer to use for outputting this question. 356 */ 357 public function get_renderer(moodle_page $page) { 358 return $page->get_renderer($this->qtype->plugin_name()); 359 } 360 361 /** 362 * What data may be included in the form submission when a student submits 363 * this question in its current state? 364 * 365 * This information is used in calls to optional_param. The parameter name 366 * has {@link question_attempt::get_field_prefix()} automatically prepended. 367 * 368 * @return array|string variable name => PARAM_... constant, or, as a special case 369 * that should only be used in unavoidable, the constant question_attempt::USE_RAW_DATA 370 * meaning take all the raw submitted data belonging to this question. 371 */ 372 public abstract function get_expected_data(); 373 374 /** 375 * What data would need to be submitted to get this question correct. 376 * If there is more than one correct answer, this method should just 377 * return one possibility. If it is not possible to compute a correct 378 * response, this method should return null. 379 * 380 * @return array|null parameter name => value. 381 */ 382 public abstract function get_correct_response(); 383 384 385 /** 386 * Takes an array of values representing a student response represented in a way that is understandable by a human and 387 * transforms that to the response as the POST values returned from the HTML form that takes the student response during a 388 * student attempt. Primarily this is used when reading csv values from a file of student responses in order to be able to 389 * simulate the student interaction with a quiz. 390 * 391 * In most cases the array will just be returned as is. Some question types will need to transform the keys of the array, 392 * as the meaning of the keys in the html form is deliberately obfuscated so that someone looking at the html does not get an 393 * advantage. The values that represent the response might also be changed in order to more meaningful to a human. 394 * 395 * See the examples of question types that have overridden this in core and also see the csv files of simulated student 396 * responses used in unit tests in : 397 * - mod/quiz/tests/fixtures/stepsXX.csv 398 * - mod/quiz/report/responses/tests/fixtures/steps00.csv 399 * - mod/quiz/report/statistics/tests/fixtures/stepsXX.csv 400 * 401 * Also see {@link https://github.com/jamiepratt/moodle-quiz_simulate}, a quiz report plug in for uploading and downloading 402 * student responses as csv files. 403 * 404 * @param array $simulatedresponse an array of data representing a student response 405 * @return array a response array as would be returned from the html form (but without prefixes) 406 */ 407 public function prepare_simulated_post_data($simulatedresponse) { 408 return $simulatedresponse; 409 } 410 411 /** 412 * Does the opposite of {@link prepare_simulated_post_data}. 413 * 414 * This takes a student response (the POST values returned from the HTML form that takes the student response during a 415 * student attempt) it then represents it in a way that is understandable by a human. 416 * 417 * Primarily this is used when creating a file of csv from real student responses in order later to be able to 418 * simulate the same student interaction with a quiz later. 419 * 420 * @param string[] $realresponse the response array as was returned from the form during a student attempt (without prefixes). 421 * @return string[] an array of data representing a student response. 422 */ 423 public function get_student_response_values_for_simulation($realresponse) { 424 return $realresponse; 425 } 426 427 /** 428 * Apply {@link format_text()} to some content with appropriate settings for 429 * this question. 430 * 431 * @param string $text some content that needs to be output. 432 * @param int $format the FORMAT_... constant. 433 * @param question_attempt $qa the question attempt. 434 * @param string $component used for rewriting file area URLs. 435 * @param string $filearea used for rewriting file area URLs. 436 * @param bool $clean Whether the HTML needs to be cleaned. Generally, 437 * parts of the question do not need to be cleaned, and student input does. 438 * @return string the text formatted for output by format_text. 439 */ 440 public function format_text($text, $format, $qa, $component, $filearea, $itemid, 441 $clean = false) { 442 $formatoptions = new stdClass(); 443 $formatoptions->noclean = !$clean; 444 $formatoptions->para = false; 445 $text = $qa->rewrite_pluginfile_urls($text, $component, $filearea, $itemid); 446 return format_text($text, $format, $formatoptions); 447 } 448 449 /** 450 * Convert some part of the question text to plain text. This might be used, 451 * for example, by get_response_summary(). 452 * @param string $text The HTML to reduce to plain text. 453 * @param int $format the FORMAT_... constant. 454 * @return string the equivalent plain text. 455 */ 456 public function html_to_text($text, $format) { 457 return question_utils::to_plain_text($text, $format); 458 } 459 460 /** @return the result of applying {@link format_text()} to the question text. */ 461 public function format_questiontext($qa) { 462 return $this->format_text($this->questiontext, $this->questiontextformat, 463 $qa, 'question', 'questiontext', $this->id); 464 } 465 466 /** @return the result of applying {@link format_text()} to the general feedback. */ 467 public function format_generalfeedback($qa) { 468 return $this->format_text($this->generalfeedback, $this->generalfeedbackformat, 469 $qa, 'question', 'generalfeedback', $this->id); 470 } 471 472 /** 473 * Take some HTML that should probably already be a single line, like a 474 * multiple choice choice, or the corresponding feedback, and make it so that 475 * it is suitable to go in a place where the HTML must be inline, like inside a <p> tag. 476 * @param string $html to HTML to fix up. 477 * @return string the fixed HTML. 478 */ 479 public function make_html_inline($html) { 480 $html = preg_replace('~\s*<p>\s*~u', '', $html); 481 $html = preg_replace('~\s*</p>\s*~u', '<br />', $html); 482 $html = preg_replace('~(<br\s*/?>)+$~u', '', $html); 483 return trim($html); 484 } 485 486 /** 487 * Checks whether the users is allow to be served a particular file. 488 * @param question_attempt $qa the question attempt being displayed. 489 * @param question_display_options $options the options that control display of the question. 490 * @param string $component the name of the component we are serving files for. 491 * @param string $filearea the name of the file area. 492 * @param array $args the remaining bits of the file path. 493 * @param bool $forcedownload whether the user must be forced to download the file. 494 * @return bool true if the user can access this file. 495 */ 496 public function check_file_access($qa, $options, $component, $filearea, $args, $forcedownload) { 497 if ($component == 'question' && $filearea == 'questiontext') { 498 // Question text always visible, but check it is the right question id. 499 return $args[0] == $this->id; 500 501 } else if ($component == 'question' && $filearea == 'generalfeedback') { 502 return $options->generalfeedback && $args[0] == $this->id; 503 504 } else { 505 // Unrecognised component or filearea. 506 return false; 507 } 508 } 509 510 /** 511 * Return the question settings that define this question as structured data. 512 * 513 * This is used by external systems such as the Moodle mobile app, which want to display the question themselves, 514 * rather than using the renderer provided. 515 * 516 * This method should only return the data that the student is allowed to see or know, given the current state of 517 * the question. For example, do not include the 'General feedback' until the student has completed the question, 518 * and even then, only include it if the question_display_options say it should be visible. 519 * 520 * But, within those rules, it is recommended that you return all the settings for the question, 521 * to give maximum flexibility to the external system providing its own rendering of the question. 522 * 523 * @param question_attempt $qa the current attempt for which we are exporting the settings. 524 * @param question_display_options $options the question display options which say which aspects of the question 525 * should be visible. 526 * @return mixed structure representing the question settings. In web services, this will be JSON-encoded. 527 */ 528 public function get_question_definition_for_external_rendering(question_attempt $qa, question_display_options $options) { 529 530 debugging('This question does not implement the get_question_definition_for_external_rendering() method yet.', 531 DEBUG_DEVELOPER); 532 return null; 533 } 534 535 /** 536 * Set the latest version. 537 * 538 * Making $this->latestversion public would break the magic __get() behaviour above, so allow it to be set externally. 539 * 540 * @param int $latestversion 541 * @return void 542 */ 543 public function set_latest_version(int $latestversion): void { 544 $this->latestversion = $latestversion; 545 } 546 } 547 548 549 /** 550 * This class represents a 'question' that actually does not allow the student 551 * to respond, like the description 'question' type. 552 * 553 * @copyright 2009 The Open University 554 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 555 */ 556 class question_information_item extends question_definition { 557 public function __construct() { 558 parent::__construct(); 559 $this->defaultmark = 0; 560 $this->penalty = 0; 561 $this->length = 0; 562 } 563 564 public function make_behaviour(question_attempt $qa, $preferredbehaviour) { 565 return question_engine::make_behaviour('informationitem', $qa, $preferredbehaviour); 566 } 567 568 public function get_expected_data() { 569 return array(); 570 } 571 572 public function get_correct_response() { 573 return array(); 574 } 575 576 public function get_question_summary() { 577 return null; 578 } 579 } 580 581 582 /** 583 * Interface that a {@link question_definition} must implement to be usable by 584 * the manual graded behaviour. 585 * 586 * @copyright 2009 The Open University 587 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 588 */ 589 interface question_manually_gradable { 590 /** 591 * Use by many of the behaviours to determine whether the student 592 * has provided enough of an answer for the question to be graded automatically, 593 * or whether it must be considered aborted. 594 * 595 * @param array $response responses, as returned by 596 * {@link question_attempt_step::get_qt_data()}. 597 * @return bool whether this response can be graded. 598 */ 599 public function is_gradable_response(array $response); 600 601 /** 602 * Used by many of the behaviours, to work out whether the student's 603 * response to the question is complete. That is, whether the question attempt 604 * should move to the COMPLETE or INCOMPLETE state. 605 * 606 * @param array $response responses, as returned by 607 * {@link question_attempt_step::get_qt_data()}. 608 * @return bool whether this response is a complete answer to this question. 609 */ 610 public function is_complete_response(array $response); 611 612 /** 613 * Use by many of the behaviours to determine whether the student's 614 * response has changed. This is normally used to determine that a new set 615 * of responses can safely be discarded. 616 * 617 * @param array $prevresponse the responses previously recorded for this question, 618 * as returned by {@link question_attempt_step::get_qt_data()} 619 * @param array $newresponse the new responses, in the same format. 620 * @return bool whether the two sets of responses are the same - that is 621 * whether the new set of responses can safely be discarded. 622 */ 623 public function is_same_response(array $prevresponse, array $newresponse); 624 625 /** 626 * Produce a plain text summary of a response. 627 * @param array $response a response, as might be passed to {@link grade_response()}. 628 * @return string a plain text summary of that response, that could be used in reports. 629 */ 630 public function summarise_response(array $response); 631 632 /** 633 * If possible, construct a response that could have lead to the given 634 * response summary. This is basically the opposite of {@link summarise_response()} 635 * but it is intended only to be used for testing. 636 * 637 * @param string $summary a string, which might have come from summarise_response 638 * @return array a response that could have lead to that. 639 */ 640 public function un_summarise_response(string $summary); 641 642 /** 643 * Categorise the student's response according to the categories defined by 644 * get_possible_responses. 645 * @param $response a response, as might be passed to {@link grade_response()}. 646 * @return array subpartid => {@link question_classified_response} objects. 647 * returns an empty array if no analysis is possible. 648 */ 649 public function classify_response(array $response); 650 } 651 652 653 /** 654 * This class is used in the return value from 655 * {@link question_manually_gradable::classify_response()}. 656 * 657 * @copyright 2010 The Open University 658 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 659 */ 660 class question_classified_response { 661 /** 662 * @var string the classification of this response the student gave to this 663 * part of the question. Must match one of the responseclasses returned by 664 * {@link question_type::get_possible_responses()}. 665 */ 666 public $responseclassid; 667 /** @var string the actual response the student gave to this part. */ 668 public $response; 669 /** @var number the fraction this part of the response earned. */ 670 public $fraction; 671 /** 672 * Constructor, just an easy way to set the fields. 673 * @param string $responseclassid see the field descriptions above. 674 * @param string $response see the field descriptions above. 675 * @param number $fraction see the field descriptions above. 676 */ 677 public function __construct($responseclassid, $response, $fraction) { 678 $this->responseclassid = $responseclassid; 679 $this->response = $response; 680 $this->fraction = $fraction; 681 } 682 683 public static function no_response() { 684 return new question_classified_response(null, get_string('noresponse', 'question'), null); 685 } 686 } 687 688 689 /** 690 * Interface that a {@link question_definition} must implement to be usable by 691 * the various automatic grading behaviours. 692 * 693 * @copyright 2009 The Open University 694 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 695 */ 696 interface question_automatically_gradable extends question_manually_gradable { 697 /** 698 * In situations where is_gradable_response() returns false, this method 699 * should generate a description of what the problem is. 700 * @return string the message. 701 */ 702 public function get_validation_error(array $response); 703 704 /** 705 * Grade a response to the question, returning a fraction between 706 * get_min_fraction() and get_max_fraction(), and the corresponding {@link question_state} 707 * right, partial or wrong. 708 * @param array $response responses, as returned by 709 * {@link question_attempt_step::get_qt_data()}. 710 * @return array (float, integer) the fraction, and the state. 711 */ 712 public function grade_response(array $response); 713 714 /** 715 * Get one of the question hints. The question_attempt is passed in case 716 * the question type wants to do something complex. For example, the 717 * multiple choice with multiple responses question type will turn off most 718 * of the hint options if the student has selected too many opitions. 719 * @param int $hintnumber Which hint to display. Indexed starting from 0 720 * @param question_attempt $qa The question_attempt. 721 */ 722 public function get_hint($hintnumber, question_attempt $qa); 723 724 /** 725 * Generate a brief, plain-text, summary of the correct answer to this question. 726 * This is used by various reports, and can also be useful when testing. 727 * This method will return null if such a summary is not possible, or 728 * inappropriate. 729 * @return string|null a plain text summary of the right answer to this question. 730 */ 731 public function get_right_answer_summary(); 732 } 733 734 735 /** 736 * Interface that a {@link question_definition} must implement to be usable by 737 * the interactivecountback behaviour. 738 * 739 * @copyright 2010 The Open University 740 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 741 */ 742 interface question_automatically_gradable_with_countback extends question_automatically_gradable { 743 /** 744 * Work out a final grade for this attempt, taking into account all the 745 * tries the student made. 746 * @param array $responses the response for each try. Each element of this 747 * array is a response array, as would be passed to {@link grade_response()}. 748 * There may be between 1 and $totaltries responses. 749 * @param int $totaltries The maximum number of tries allowed. 750 * @return numeric the fraction that should be awarded for this 751 * sequence of response. 752 */ 753 public function compute_final_grade($responses, $totaltries); 754 } 755 756 757 /** 758 * This class represents a real question. That is, one that is not a 759 * {@link question_information_item}. 760 * 761 * @copyright 2009 The Open University 762 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 763 */ 764 abstract class question_with_responses extends question_definition 765 implements question_manually_gradable { 766 public function classify_response(array $response) { 767 return array(); 768 } 769 770 public function is_gradable_response(array $response) { 771 return $this->is_complete_response($response); 772 } 773 774 public function un_summarise_response(string $summary) { 775 throw new coding_exception('This question type (' . get_class($this) . 776 ' does not implement the un_summarise_response testing method.'); 777 } 778 } 779 780 781 /** 782 * This class represents a question that can be graded automatically. 783 * 784 * @copyright 2009 The Open University 785 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 786 */ 787 abstract class question_graded_automatically extends question_with_responses 788 implements question_automatically_gradable { 789 /** @var Some question types have the option to show the number of sub-parts correct. */ 790 public $shownumcorrect = false; 791 792 public function get_right_answer_summary() { 793 $correctresponse = $this->get_correct_response(); 794 if (empty($correctresponse)) { 795 return null; 796 } 797 return $this->summarise_response($correctresponse); 798 } 799 800 /** 801 * Check a request for access to a file belonging to a combined feedback field. 802 * @param question_attempt $qa the question attempt being displayed. 803 * @param question_display_options $options the options that control display of the question. 804 * @param string $filearea the name of the file area. 805 * @param array $args the remaining bits of the file path. 806 * @return bool whether access to the file should be allowed. 807 */ 808 protected function check_combined_feedback_file_access($qa, $options, $filearea, $args = null) { 809 $state = $qa->get_state(); 810 811 if ($args === null) { 812 debugging('You must pass $args as the fourth argument to check_combined_feedback_file_access.', 813 DEBUG_DEVELOPER); 814 $args = array($this->id); // Fake it for now, so the rest of this method works. 815 } 816 817 if (!$state->is_finished()) { 818 $response = $qa->get_last_qt_data(); 819 if (!$this->is_gradable_response($response)) { 820 return false; 821 } 822 list($notused, $state) = $this->grade_response($response); 823 } 824 825 return $options->feedback && $state->get_feedback_class() . 'feedback' == $filearea && 826 $args[0] == $this->id; 827 } 828 829 /** 830 * Check a request for access to a file belonging to a hint. 831 * @param question_attempt $qa the question attempt being displayed. 832 * @param question_display_options $options the options that control display of the question. 833 * @param array $args the remaining bits of the file path. 834 * @return bool whether access to the file should be allowed. 835 */ 836 protected function check_hint_file_access($qa, $options, $args) { 837 if (!$options->feedback) { 838 return false; 839 } 840 $hint = $qa->get_applicable_hint(); 841 $hintid = reset($args); // Itemid is hint id. 842 return $hintid == $hint->id; 843 } 844 845 public function get_hint($hintnumber, question_attempt $qa) { 846 if (!isset($this->hints[$hintnumber])) { 847 return null; 848 } 849 return $this->hints[$hintnumber]; 850 } 851 852 public function format_hint(question_hint $hint, question_attempt $qa) { 853 return $this->format_text($hint->hint, $hint->hintformat, $qa, 854 'question', 'hint', $hint->id); 855 } 856 } 857 858 859 /** 860 * This class represents a question that can be graded automatically with 861 * countback grading in interactive mode. 862 * 863 * @copyright 2010 The Open University 864 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 865 */ 866 abstract class question_graded_automatically_with_countback 867 extends question_graded_automatically 868 implements question_automatically_gradable_with_countback { 869 870 public function make_behaviour(question_attempt $qa, $preferredbehaviour) { 871 if ($preferredbehaviour == 'interactive') { 872 return question_engine::make_behaviour('interactivecountback', 873 $qa, $preferredbehaviour); 874 } 875 return question_engine::make_archetypal_behaviour($preferredbehaviour, $qa); 876 } 877 } 878 879 880 /** 881 * This class represents a question that can be graded automatically by using 882 * a {@link question_grading_strategy}. 883 * 884 * @copyright 2009 The Open University 885 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 886 */ 887 abstract class question_graded_by_strategy extends question_graded_automatically { 888 /** @var question_grading_strategy the strategy to use for grading. */ 889 protected $gradingstrategy; 890 891 /** @param question_grading_strategy $strategy the strategy to use for grading. */ 892 public function __construct(question_grading_strategy $strategy) { 893 parent::__construct(); 894 $this->gradingstrategy = $strategy; 895 } 896 897 public function get_correct_response() { 898 $answer = $this->get_correct_answer(); 899 if (!$answer) { 900 return array(); 901 } 902 903 return array('answer' => $answer->answer); 904 } 905 906 /** 907 * Get an answer that contains the feedback and fraction that should be 908 * awarded for this resonse. 909 * @param array $response a response. 910 * @return question_answer the matching answer. 911 */ 912 public function get_matching_answer(array $response) { 913 return $this->gradingstrategy->grade($response); 914 } 915 916 /** 917 * @return question_answer an answer that contains the a response that would 918 * get full marks. 919 */ 920 public function get_correct_answer() { 921 return $this->gradingstrategy->get_correct_answer(); 922 } 923 924 public function grade_response(array $response) { 925 $answer = $this->get_matching_answer($response); 926 if ($answer) { 927 return array($answer->fraction, 928 question_state::graded_state_for_fraction($answer->fraction)); 929 } else { 930 return array(0, question_state::$gradedwrong); 931 } 932 } 933 934 public function classify_response(array $response) { 935 if (empty($response['answer'])) { 936 return array($this->id => question_classified_response::no_response()); 937 } 938 939 $ans = $this->get_matching_answer($response); 940 if (!$ans) { 941 return array($this->id => new question_classified_response( 942 0, $response['answer'], 0)); 943 } 944 945 return array($this->id => new question_classified_response( 946 $ans->id, $response['answer'], $ans->fraction)); 947 } 948 } 949 950 951 /** 952 * Class to represent a question answer, loaded from the question_answers table 953 * in the database. 954 * 955 * @copyright 2009 The Open University 956 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 957 */ 958 class question_answer { 959 /** @var integer the answer id. */ 960 public $id; 961 962 /** @var string the answer. */ 963 public $answer; 964 965 /** @var integer one of the FORMAT_... constans. */ 966 public $answerformat = FORMAT_PLAIN; 967 968 /** @var number the fraction this answer is worth. */ 969 public $fraction; 970 971 /** @var string the feedback for this answer. */ 972 public $feedback; 973 974 /** @var integer one of the FORMAT_... constans. */ 975 public $feedbackformat; 976 977 /** 978 * Constructor. 979 * @param int $id the answer. 980 * @param string $answer the answer. 981 * @param number $fraction the fraction this answer is worth. 982 * @param string $feedback the feedback for this answer. 983 * @param int $feedbackformat the format of the feedback. 984 */ 985 public function __construct($id, $answer, $fraction, $feedback, $feedbackformat) { 986 $this->id = $id; 987 $this->answer = $answer; 988 $this->fraction = $fraction; 989 $this->feedback = $feedback; 990 $this->feedbackformat = $feedbackformat; 991 } 992 } 993 994 995 /** 996 * Class to represent a hint associated with a question. 997 * Used by iteractive mode, etc. A question has an array of these. 998 * 999 * @copyright 2010 The Open University 1000 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 1001 */ 1002 class question_hint { 1003 /** @var integer The hint id. */ 1004 public $id; 1005 /** @var string The feedback hint to be shown. */ 1006 public $hint; 1007 /** @var integer The corresponding text FORMAT_... type. */ 1008 public $hintformat; 1009 1010 /** 1011 * Constructor. 1012 * @param int the hint id from the database. 1013 * @param string $hint The hint text 1014 * @param int the corresponding text FORMAT_... type. 1015 */ 1016 public function __construct($id, $hint, $hintformat) { 1017 $this->id = $id; 1018 $this->hint = $hint; 1019 $this->hintformat = $hintformat; 1020 } 1021 1022 /** 1023 * Create a basic hint from a row loaded from the question_hints table in the database. 1024 * @param object $row with $row->hint set. 1025 * @return question_hint 1026 */ 1027 public static function load_from_record($row) { 1028 return new question_hint($row->id, $row->hint, $row->hintformat); 1029 } 1030 1031 /** 1032 * Adjust this display options according to the hint settings. 1033 * @param question_display_options $options 1034 */ 1035 public function adjust_display_options(question_display_options $options) { 1036 // Do nothing. 1037 } 1038 } 1039 1040 1041 /** 1042 * An extension of {@link question_hint} for questions like match and multiple 1043 * choice with multile answers, where there are options for whether to show the 1044 * number of parts right at each stage, and to reset the wrong parts. 1045 * 1046 * @copyright 2010 The Open University 1047 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 1048 */ 1049 class question_hint_with_parts extends question_hint { 1050 /** @var boolean option to show the number of sub-parts of the question that were right. */ 1051 public $shownumcorrect; 1052 1053 /** @var boolean option to clear the parts of the question that were wrong on retry. */ 1054 public $clearwrong; 1055 1056 /** 1057 * Constructor. 1058 * @param int the hint id from the database. 1059 * @param string $hint The hint text 1060 * @param int the corresponding text FORMAT_... type. 1061 * @param bool $shownumcorrect whether the number of right parts should be shown 1062 * @param bool $clearwrong whether the wrong parts should be reset. 1063 */ 1064 public function __construct($id, $hint, $hintformat, $shownumcorrect, $clearwrong) { 1065 parent::__construct($id, $hint, $hintformat); 1066 $this->shownumcorrect = $shownumcorrect; 1067 $this->clearwrong = $clearwrong; 1068 } 1069 1070 /** 1071 * Create a basic hint from a row loaded from the question_hints table in the database. 1072 * @param object $row with $row->hint, ->shownumcorrect and ->clearwrong set. 1073 * @return question_hint_with_parts 1074 */ 1075 public static function load_from_record($row) { 1076 return new question_hint_with_parts($row->id, $row->hint, $row->hintformat, 1077 $row->shownumcorrect, $row->clearwrong); 1078 } 1079 1080 public function adjust_display_options(question_display_options $options) { 1081 parent::adjust_display_options($options); 1082 if ($this->clearwrong) { 1083 $options->clearwrong = true; 1084 } 1085 $options->numpartscorrect = $this->shownumcorrect; 1086 } 1087 } 1088 1089 1090 /** 1091 * This question_grading_strategy interface. Used to share grading code between 1092 * questions that that subclass {@link question_graded_by_strategy}. 1093 * 1094 * @copyright 2009 The Open University 1095 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 1096 */ 1097 interface question_grading_strategy { 1098 /** 1099 * Return a question answer that describes the outcome (fraction and feeback) 1100 * for a particular respons. 1101 * @param array $response the response. 1102 * @return question_answer the answer describing the outcome. 1103 */ 1104 public function grade(array $response); 1105 1106 /** 1107 * @return question_answer an answer that contains the a response that would 1108 * get full marks. 1109 */ 1110 public function get_correct_answer(); 1111 } 1112 1113 1114 /** 1115 * This interface defines the methods that a {@link question_definition} must 1116 * implement if it is to be graded by the 1117 * {@link question_first_matching_answer_grading_strategy}. 1118 * 1119 * @copyright 2009 The Open University 1120 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 1121 */ 1122 interface question_response_answer_comparer { 1123 /** @return array of {@link question_answers}. */ 1124 public function get_answers(); 1125 1126 /** 1127 * @param array $response the response. 1128 * @param question_answer $answer an answer. 1129 * @return bool whether the response matches the answer. 1130 */ 1131 public function compare_response_with_answer(array $response, question_answer $answer); 1132 } 1133 1134 1135 /** 1136 * This grading strategy is used by question types like shortanswer an numerical. 1137 * It gets a list of possible answers from the question, and returns the first one 1138 * that matches the given response. It returns the first answer with fraction 1.0 1139 * when asked for the correct answer. 1140 * 1141 * @copyright 2009 The Open University 1142 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 1143 */ 1144 class question_first_matching_answer_grading_strategy implements question_grading_strategy { 1145 /** 1146 * @var question_response_answer_comparer (presumably also a 1147 * {@link question_definition}) the question we are doing the grading for. 1148 */ 1149 protected $question; 1150 1151 /** 1152 * @param question_response_answer_comparer $question (presumably also a 1153 * {@link question_definition}) the question we are doing the grading for. 1154 */ 1155 public function __construct(question_response_answer_comparer $question) { 1156 $this->question = $question; 1157 } 1158 1159 public function grade(array $response) { 1160 foreach ($this->question->get_answers() as $aid => $answer) { 1161 if ($this->question->compare_response_with_answer($response, $answer)) { 1162 $answer->id = $aid; 1163 return $answer; 1164 } 1165 } 1166 return null; 1167 } 1168 1169 public function get_correct_answer() { 1170 foreach ($this->question->get_answers() as $answer) { 1171 $state = question_state::graded_state_for_fraction($answer->fraction); 1172 if ($state == question_state::$gradedright) { 1173 return $answer; 1174 } 1175 } 1176 return null; 1177 } 1178 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
