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