| [ Index ] |
PHP Cross Reference of moodle-2.8 |
[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 * Checks whether the users is allow to be served a particular file. 392 * @param question_attempt $qa the question attempt being displayed. 393 * @param question_display_options $options the options that control display of the question. 394 * @param string $component the name of the component we are serving files for. 395 * @param string $filearea the name of the file area. 396 * @param array $args the remaining bits of the file path. 397 * @param bool $forcedownload whether the user must be forced to download the file. 398 * @return bool true if the user can access this file. 399 */ 400 public function check_file_access($qa, $options, $component, $filearea, $args, $forcedownload) { 401 if ($component == 'question' && $filearea == 'questiontext') { 402 // Question text always visible. 403 return true; 404 405 } else if ($component == 'question' && $filearea == 'generalfeedback') { 406 return $options->generalfeedback; 407 408 } else { 409 // Unrecognised component or filearea. 410 return false; 411 } 412 } 413 } 414 415 416 /** 417 * This class represents a 'question' that actually does not allow the student 418 * to respond, like the description 'question' type. 419 * 420 * @copyright 2009 The Open University 421 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 422 */ 423 class question_information_item extends question_definition { 424 public function __construct() { 425 parent::__construct(); 426 $this->defaultmark = 0; 427 $this->penalty = 0; 428 $this->length = 0; 429 } 430 431 public function make_behaviour(question_attempt $qa, $preferredbehaviour) { 432 return question_engine::make_behaviour('informationitem', $qa, $preferredbehaviour); 433 } 434 435 public function get_expected_data() { 436 return array(); 437 } 438 439 public function get_correct_response() { 440 return array(); 441 } 442 443 public function get_question_summary() { 444 return null; 445 } 446 } 447 448 449 /** 450 * Interface that a {@link question_definition} must implement to be usable by 451 * the manual graded behaviour. 452 * 453 * @copyright 2009 The Open University 454 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 455 */ 456 interface question_manually_gradable { 457 /** 458 * Used by many of the behaviours, to work out whether the student's 459 * response to the question is complete. That is, whether the question attempt 460 * should move to the COMPLETE or INCOMPLETE state. 461 * 462 * @param array $response responses, as returned by 463 * {@link question_attempt_step::get_qt_data()}. 464 * @return bool whether this response is a complete answer to this question. 465 */ 466 public function is_complete_response(array $response); 467 468 /** 469 * Use by many of the behaviours to determine whether the student's 470 * response has changed. This is normally used to determine that a new set 471 * of responses can safely be discarded. 472 * 473 * @param array $prevresponse the responses previously recorded for this question, 474 * as returned by {@link question_attempt_step::get_qt_data()} 475 * @param array $newresponse the new responses, in the same format. 476 * @return bool whether the two sets of responses are the same - that is 477 * whether the new set of responses can safely be discarded. 478 */ 479 public function is_same_response(array $prevresponse, array $newresponse); 480 481 /** 482 * Produce a plain text summary of a response. 483 * @param $response a response, as might be passed to {@link grade_response()}. 484 * @return string a plain text summary of that response, that could be used in reports. 485 */ 486 public function summarise_response(array $response); 487 488 /** 489 * Categorise the student's response according to the categories defined by 490 * get_possible_responses. 491 * @param $response a response, as might be passed to {@link grade_response()}. 492 * @return array subpartid => {@link question_classified_response} objects. 493 * returns an empty array if no analysis is possible. 494 */ 495 public function classify_response(array $response); 496 } 497 498 499 /** 500 * This class is used in the return value from 501 * {@link question_manually_gradable::classify_response()}. 502 * 503 * @copyright 2010 The Open University 504 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 505 */ 506 class question_classified_response { 507 /** 508 * @var string the classification of this response the student gave to this 509 * part of the question. Must match one of the responseclasses returned by 510 * {@link question_type::get_possible_responses()}. 511 */ 512 public $responseclassid; 513 /** @var string the actual response the student gave to this part. */ 514 public $response; 515 /** @var number the fraction this part of the response earned. */ 516 public $fraction; 517 /** 518 * Constructor, just an easy way to set the fields. 519 * @param string $responseclassid see the field descriptions above. 520 * @param string $response see the field descriptions above. 521 * @param number $fraction see the field descriptions above. 522 */ 523 public function __construct($responseclassid, $response, $fraction) { 524 $this->responseclassid = $responseclassid; 525 $this->response = $response; 526 $this->fraction = $fraction; 527 } 528 529 public static function no_response() { 530 return new question_classified_response(null, get_string('noresponse', 'question'), null); 531 } 532 } 533 534 535 /** 536 * Interface that a {@link question_definition} must implement to be usable by 537 * the various automatic grading behaviours. 538 * 539 * @copyright 2009 The Open University 540 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 541 */ 542 interface question_automatically_gradable extends question_manually_gradable { 543 /** 544 * Use by many of the behaviours to determine whether the student 545 * has provided enough of an answer for the question to be graded automatically, 546 * or whether it must be considered aborted. 547 * 548 * @param array $response responses, as returned by 549 * {@link question_attempt_step::get_qt_data()}. 550 * @return bool whether this response can be graded. 551 */ 552 public function is_gradable_response(array $response); 553 554 /** 555 * In situations where is_gradable_response() returns false, this method 556 * should generate a description of what the problem is. 557 * @return string the message. 558 */ 559 public function get_validation_error(array $response); 560 561 /** 562 * Grade a response to the question, returning a fraction between 563 * get_min_fraction() and get_max_fraction(), and the corresponding {@link question_state} 564 * right, partial or wrong. 565 * @param array $response responses, as returned by 566 * {@link question_attempt_step::get_qt_data()}. 567 * @return array (float, integer) the fraction, and the state. 568 */ 569 public function grade_response(array $response); 570 571 /** 572 * Get one of the question hints. The question_attempt is passed in case 573 * the question type wants to do something complex. For example, the 574 * multiple choice with multiple responses question type will turn off most 575 * of the hint options if the student has selected too many opitions. 576 * @param int $hintnumber Which hint to display. Indexed starting from 0 577 * @param question_attempt $qa The question_attempt. 578 */ 579 public function get_hint($hintnumber, question_attempt $qa); 580 581 /** 582 * Generate a brief, plain-text, summary of the correct answer to this question. 583 * This is used by various reports, and can also be useful when testing. 584 * This method will return null if such a summary is not possible, or 585 * inappropriate. 586 * @return string|null a plain text summary of the right answer to this question. 587 */ 588 public function get_right_answer_summary(); 589 } 590 591 592 /** 593 * Interface that a {@link question_definition} must implement to be usable by 594 * the interactivecountback behaviour. 595 * 596 * @copyright 2010 The Open University 597 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 598 */ 599 interface question_automatically_gradable_with_countback extends question_automatically_gradable { 600 /** 601 * Work out a final grade for this attempt, taking into account all the 602 * tries the student made. 603 * @param array $responses the response for each try. Each element of this 604 * array is a response array, as would be passed to {@link grade_response()}. 605 * There may be between 1 and $totaltries responses. 606 * @param int $totaltries The maximum number of tries allowed. 607 * @return numeric the fraction that should be awarded for this 608 * sequence of response. 609 */ 610 public function compute_final_grade($responses, $totaltries); 611 } 612 613 614 /** 615 * This class represents a real question. That is, one that is not a 616 * {@link question_information_item}. 617 * 618 * @copyright 2009 The Open University 619 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 620 */ 621 abstract class question_with_responses extends question_definition 622 implements question_manually_gradable { 623 public function classify_response(array $response) { 624 return array(); 625 } 626 } 627 628 629 /** 630 * This class represents a question that can be graded automatically. 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_graded_automatically extends question_with_responses 636 implements question_automatically_gradable { 637 /** @var Some question types have the option to show the number of sub-parts correct. */ 638 public $shownumcorrect = false; 639 640 public function is_gradable_response(array $response) { 641 return $this->is_complete_response($response); 642 } 643 644 public function get_right_answer_summary() { 645 $correctresponse = $this->get_correct_response(); 646 if (empty($correctresponse)) { 647 return null; 648 } 649 return $this->summarise_response($correctresponse); 650 } 651 652 /** 653 * Check a request for access to a file belonging to a combined feedback field. 654 * @param question_attempt $qa the question attempt being displayed. 655 * @param question_display_options $options the options that control display of the question. 656 * @param string $filearea the name of the file area. 657 * @return bool whether access to the file should be allowed. 658 */ 659 protected function check_combined_feedback_file_access($qa, $options, $filearea) { 660 $state = $qa->get_state(); 661 662 if (!$state->is_finished()) { 663 $response = $qa->get_last_qt_data(); 664 if (!$this->is_gradable_response($response)) { 665 return false; 666 } 667 list($notused, $state) = $this->grade_response($response); 668 } 669 670 return $options->feedback && $state->get_feedback_class() . 'feedback' == $filearea; 671 } 672 673 /** 674 * Check a request for access to a file belonging to a hint. 675 * @param question_attempt $qa the question attempt being displayed. 676 * @param question_display_options $options the options that control display of the question. 677 * @param array $args the remaining bits of the file path. 678 * @return bool whether access to the file should be allowed. 679 */ 680 protected function check_hint_file_access($qa, $options, $args) { 681 if (!$options->feedback) { 682 return false; 683 } 684 $hint = $qa->get_applicable_hint(); 685 $hintid = reset($args); // Itemid is hint id. 686 return $hintid == $hint->id; 687 } 688 689 public function get_hint($hintnumber, question_attempt $qa) { 690 if (!isset($this->hints[$hintnumber])) { 691 return null; 692 } 693 return $this->hints[$hintnumber]; 694 } 695 696 public function format_hint(question_hint $hint, question_attempt $qa) { 697 return $this->format_text($hint->hint, $hint->hintformat, $qa, 698 'question', 'hint', $hint->id); 699 } 700 } 701 702 703 /** 704 * This class represents a question that can be graded automatically with 705 * countback grading in interactive mode. 706 * 707 * @copyright 2010 The Open University 708 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 709 */ 710 abstract class question_graded_automatically_with_countback 711 extends question_graded_automatically 712 implements question_automatically_gradable_with_countback { 713 714 public function make_behaviour(question_attempt $qa, $preferredbehaviour) { 715 if ($preferredbehaviour == 'interactive') { 716 return question_engine::make_behaviour('interactivecountback', 717 $qa, $preferredbehaviour); 718 } 719 return question_engine::make_archetypal_behaviour($preferredbehaviour, $qa); 720 } 721 } 722 723 724 /** 725 * This class represents a question that can be graded automatically by using 726 * a {@link question_grading_strategy}. 727 * 728 * @copyright 2009 The Open University 729 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 730 */ 731 abstract class question_graded_by_strategy extends question_graded_automatically { 732 /** @var question_grading_strategy the strategy to use for grading. */ 733 protected $gradingstrategy; 734 735 /** @param question_grading_strategy $strategy the strategy to use for grading. */ 736 public function __construct(question_grading_strategy $strategy) { 737 parent::__construct(); 738 $this->gradingstrategy = $strategy; 739 } 740 741 public function get_correct_response() { 742 $answer = $this->get_correct_answer(); 743 if (!$answer) { 744 return array(); 745 } 746 747 return array('answer' => $answer->answer); 748 } 749 750 /** 751 * Get an answer that contains the feedback and fraction that should be 752 * awarded for this resonse. 753 * @param array $response a response. 754 * @return question_answer the matching answer. 755 */ 756 public function get_matching_answer(array $response) { 757 return $this->gradingstrategy->grade($response); 758 } 759 760 /** 761 * @return question_answer an answer that contains the a response that would 762 * get full marks. 763 */ 764 public function get_correct_answer() { 765 return $this->gradingstrategy->get_correct_answer(); 766 } 767 768 public function grade_response(array $response) { 769 $answer = $this->get_matching_answer($response); 770 if ($answer) { 771 return array($answer->fraction, 772 question_state::graded_state_for_fraction($answer->fraction)); 773 } else { 774 return array(0, question_state::$gradedwrong); 775 } 776 } 777 778 public function classify_response(array $response) { 779 if (empty($response['answer'])) { 780 return array($this->id => question_classified_response::no_response()); 781 } 782 783 $ans = $this->get_matching_answer($response); 784 if (!$ans) { 785 return array($this->id => new question_classified_response( 786 0, $response['answer'], 0)); 787 } 788 789 return array($this->id => new question_classified_response( 790 $ans->id, $response['answer'], $ans->fraction)); 791 } 792 } 793 794 795 /** 796 * Class to represent a question answer, loaded from the question_answers table 797 * in the database. 798 * 799 * @copyright 2009 The Open University 800 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 801 */ 802 class question_answer { 803 /** @var integer the answer id. */ 804 public $id; 805 806 /** @var string the answer. */ 807 public $answer; 808 809 /** @var integer one of the FORMAT_... constans. */ 810 public $answerformat = FORMAT_PLAIN; 811 812 /** @var number the fraction this answer is worth. */ 813 public $fraction; 814 815 /** @var string the feedback for this answer. */ 816 public $feedback; 817 818 /** @var integer one of the FORMAT_... constans. */ 819 public $feedbackformat; 820 821 /** 822 * Constructor. 823 * @param int $id the answer. 824 * @param string $answer the answer. 825 * @param number $fraction the fraction this answer is worth. 826 * @param string $feedback the feedback for this answer. 827 * @param int $feedbackformat the format of the feedback. 828 */ 829 public function __construct($id, $answer, $fraction, $feedback, $feedbackformat) { 830 $this->id = $id; 831 $this->answer = $answer; 832 $this->fraction = $fraction; 833 $this->feedback = $feedback; 834 $this->feedbackformat = $feedbackformat; 835 } 836 } 837 838 839 /** 840 * Class to represent a hint associated with a question. 841 * Used by iteractive mode, etc. A question has an array of these. 842 * 843 * @copyright 2010 The Open University 844 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 845 */ 846 class question_hint { 847 /** @var integer The hint id. */ 848 public $id; 849 /** @var string The feedback hint to be shown. */ 850 public $hint; 851 /** @var integer The corresponding text FORMAT_... type. */ 852 public $hintformat; 853 854 /** 855 * Constructor. 856 * @param int the hint id from the database. 857 * @param string $hint The hint text 858 * @param int the corresponding text FORMAT_... type. 859 */ 860 public function __construct($id, $hint, $hintformat) { 861 $this->id = $id; 862 $this->hint = $hint; 863 $this->hintformat = $hintformat; 864 } 865 866 /** 867 * Create a basic hint from a row loaded from the question_hints table in the database. 868 * @param object $row with $row->hint set. 869 * @return question_hint 870 */ 871 public static function load_from_record($row) { 872 return new question_hint($row->id, $row->hint, $row->hintformat); 873 } 874 875 /** 876 * Adjust this display options according to the hint settings. 877 * @param question_display_options $options 878 */ 879 public function adjust_display_options(question_display_options $options) { 880 // Do nothing. 881 } 882 } 883 884 885 /** 886 * An extension of {@link question_hint} for questions like match and multiple 887 * choice with multile answers, where there are options for whether to show the 888 * number of parts right at each stage, and to reset the wrong parts. 889 * 890 * @copyright 2010 The Open University 891 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 892 */ 893 class question_hint_with_parts extends question_hint { 894 /** @var boolean option to show the number of sub-parts of the question that were right. */ 895 public $shownumcorrect; 896 897 /** @var boolean option to clear the parts of the question that were wrong on retry. */ 898 public $clearwrong; 899 900 /** 901 * Constructor. 902 * @param int the hint id from the database. 903 * @param string $hint The hint text 904 * @param int the corresponding text FORMAT_... type. 905 * @param bool $shownumcorrect whether the number of right parts should be shown 906 * @param bool $clearwrong whether the wrong parts should be reset. 907 */ 908 public function __construct($id, $hint, $hintformat, $shownumcorrect, $clearwrong) { 909 parent::__construct($id, $hint, $hintformat); 910 $this->shownumcorrect = $shownumcorrect; 911 $this->clearwrong = $clearwrong; 912 } 913 914 /** 915 * Create a basic hint from a row loaded from the question_hints table in the database. 916 * @param object $row with $row->hint, ->shownumcorrect and ->clearwrong set. 917 * @return question_hint_with_parts 918 */ 919 public static function load_from_record($row) { 920 return new question_hint_with_parts($row->id, $row->hint, $row->hintformat, 921 $row->shownumcorrect, $row->clearwrong); 922 } 923 924 public function adjust_display_options(question_display_options $options) { 925 parent::adjust_display_options($options); 926 if ($this->clearwrong) { 927 $options->clearwrong = true; 928 } 929 $options->numpartscorrect = $this->shownumcorrect; 930 } 931 } 932 933 934 /** 935 * This question_grading_strategy interface. Used to share grading code between 936 * questions that that subclass {@link question_graded_by_strategy}. 937 * 938 * @copyright 2009 The Open University 939 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 940 */ 941 interface question_grading_strategy { 942 /** 943 * Return a question answer that describes the outcome (fraction and feeback) 944 * for a particular respons. 945 * @param array $response the response. 946 * @return question_answer the answer describing the outcome. 947 */ 948 public function grade(array $response); 949 950 /** 951 * @return question_answer an answer that contains the a response that would 952 * get full marks. 953 */ 954 public function get_correct_answer(); 955 } 956 957 958 /** 959 * This interface defines the methods that a {@link question_definition} must 960 * implement if it is to be graded by the 961 * {@link question_first_matching_answer_grading_strategy}. 962 * 963 * @copyright 2009 The Open University 964 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 965 */ 966 interface question_response_answer_comparer { 967 /** @return array of {@link question_answers}. */ 968 public function get_answers(); 969 970 /** 971 * @param array $response the response. 972 * @param question_answer $answer an answer. 973 * @return bool whether the response matches the answer. 974 */ 975 public function compare_response_with_answer(array $response, question_answer $answer); 976 } 977 978 979 /** 980 * This grading strategy is used by question types like shortanswer an numerical. 981 * It gets a list of possible answers from the question, and returns the first one 982 * that matches the given response. It returns the first answer with fraction 1.0 983 * when asked for the correct answer. 984 * 985 * @copyright 2009 The Open University 986 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 987 */ 988 class question_first_matching_answer_grading_strategy implements question_grading_strategy { 989 /** 990 * @var question_response_answer_comparer (presumably also a 991 * {@link question_definition}) the question we are doing the grading for. 992 */ 993 protected $question; 994 995 /** 996 * @param question_response_answer_comparer $question (presumably also a 997 * {@link question_definition}) the question we are doing the grading for. 998 */ 999 public function __construct(question_response_answer_comparer $question) { 1000 $this->question = $question; 1001 } 1002 1003 public function grade(array $response) { 1004 foreach ($this->question->get_answers() as $aid => $answer) { 1005 if ($this->question->compare_response_with_answer($response, $answer)) { 1006 $answer->id = $aid; 1007 return $answer; 1008 } 1009 } 1010 return null; 1011 } 1012 1013 public function get_correct_answer() { 1014 foreach ($this->question->get_answers() as $answer) { 1015 $state = question_state::graded_state_for_fraction($answer->fraction); 1016 if ($state == question_state::$gradedright) { 1017 return $answer; 1018 } 1019 } 1020 return null; 1021 } 1022 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Fri Nov 28 20:29:05 2014 | Cross-referenced by PHPXref 0.7.1 |