Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 401 and 402] [Versions 401 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  }