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