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