[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   * Defines the question behaviour base class
  19   *
  20   * @package    moodlecore
  21   * @subpackage questionbehaviours
  22   * @copyright  2009 The Open University
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  
  27  defined('MOODLE_INTERNAL') || die();
  28  
  29  
  30  /**
  31   * The base class for question behaviours.
  32   *
  33   * A question behaviour is used by the question engine, specifically by
  34   * a {@link question_attempt} to manage the flow of actions a student can take
  35   * as they work through a question, and later, as a teacher manually grades it.
  36   * In turn, the behaviour will delegate certain processing to the
  37   * relevant {@link question_definition}.
  38   *
  39   * @copyright  2009 The Open University
  40   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  41   */
  42  abstract class question_behaviour {
  43  
  44      /** @var question_attempt the question attempt we are managing. */
  45      protected $qa;
  46  
  47      /** @var question_definition shortcut to $qa->get_question(). */
  48      protected $question;
  49  
  50      /**
  51       * Normally you should not call this constuctor directly. The appropriate
  52       * behaviour object is created automatically as part of
  53       * {@link question_attempt::start()}.
  54       * @param question_attempt $qa the question attempt we will be managing.
  55       * @param string $preferredbehaviour the type of behaviour that was actually
  56       *      requested. This information is not needed in most cases, the type of
  57       *      subclass is enough, but occasionally it is needed.
  58       */
  59      public function __construct(question_attempt $qa, $preferredbehaviour) {
  60          $this->qa = $qa;
  61          $this->question = $qa->get_question();
  62          if (!$this->is_compatible_question($this->question)) {
  63              throw new coding_exception('This behaviour (' . $this->get_name() .
  64                      ') cannot work with this question (' . get_class($this->question) . ')');
  65          }
  66      }
  67  
  68      /**
  69       * Some behaviours can only work with certing types of question. This method
  70       * allows the behaviour to verify that a question is compatible.
  71       *
  72       * This implementation is only provided for backwards-compatibility. You should
  73       * override this method if you are implementing a behaviour.
  74       *
  75       * @param question_definition $question the question.
  76       */
  77      public abstract function is_compatible_question(question_definition $question);
  78  
  79      /**
  80       * @return string the name of this behaviour. For example the name of
  81       * qbehaviour_mymodle is 'mymodel'.
  82       */
  83      public function get_name() {
  84          return substr(get_class($this), 11);
  85      }
  86  
  87      /**
  88       * Cause the question to be renderered. This gets the appropriate behaviour
  89       * renderer using {@link get_renderer()}, and adjusts the display
  90       * options using {@link adjust_display_options()} and then calls
  91       * {@link core_question_renderer::question()} to do the work.
  92       * @param question_display_options $options controls what should and should not be displayed.
  93       * @param unknown_type $number the question number to display.
  94       * @param core_question_renderer $qoutput the question renderer that will coordinate everything.
  95       * @param qtype_renderer $qtoutput the question type renderer that will be helping.
  96       * @return HTML fragment.
  97       */
  98      public function render(question_display_options $options, $number,
  99              core_question_renderer $qoutput, qtype_renderer $qtoutput) {
 100          $behaviouroutput = $this->get_renderer($qoutput->get_page());
 101          $options = clone($options);
 102          $this->adjust_display_options($options);
 103          return $qoutput->question($this->qa, $behaviouroutput, $qtoutput, $options, $number);
 104      }
 105  
 106      /**
 107       * Checks whether the users is allow to be served a particular file.
 108       * @param question_display_options $options the options that control display of the question.
 109       * @param string $component the name of the component we are serving files for.
 110       * @param string $filearea the name of the file area.
 111       * @param array $args the remaining bits of the file path.
 112       * @param bool $forcedownload whether the user must be forced to download the file.
 113       * @return bool true if the user can access this file.
 114       */
 115      public function check_file_access($options, $component, $filearea, $args, $forcedownload) {
 116          $this->adjust_display_options($options);
 117          return $this->question->check_file_access($this->qa, $options, $component,
 118                  $filearea, $args, $forcedownload);
 119      }
 120  
 121      /**
 122       * @param moodle_page $page the page to render for.
 123       * @return qbehaviour_renderer get the appropriate renderer to use for this model.
 124       */
 125      public function get_renderer(moodle_page $page) {
 126          return $page->get_renderer(get_class($this));
 127      }
 128  
 129      /**
 130       * Make any changes to the display options before a question is rendered, so
 131       * that it can be displayed in a way that is appropriate for the statue it is
 132       * currently in. For example, by default, if the question is finished, we
 133       * ensure that it is only ever displayed read-only.
 134       * @param question_display_options $options the options to adjust. Just change
 135       * the properties of this object - objects are passed by referece.
 136       */
 137      public function adjust_display_options(question_display_options $options) {
 138          if (!$this->qa->has_marks()) {
 139              $options->correctness = false;
 140              $options->numpartscorrect = false;
 141          }
 142          if ($this->qa->get_state()->is_finished()) {
 143              $options->readonly = true;
 144              $options->numpartscorrect = $options->numpartscorrect &&
 145                      $this->qa->get_state()->is_partially_correct() &&
 146                      !empty($this->question->shownumcorrect);
 147          } else {
 148              $options->hide_all_feedback();
 149          }
 150      }
 151  
 152      /**
 153       * Get the most applicable hint for the question in its current state.
 154       * @return question_hint the most applicable hint, or null, if none.
 155       */
 156      public function get_applicable_hint() {
 157          return null;
 158      }
 159  
 160      /**
 161       * What is the minimum fraction that can be scored for this question.
 162       * Normally this will be based on $this->question->get_min_fraction(),
 163       * but may be modified in some way by the behaviour.
 164       *
 165       * @return number the minimum fraction when this question is attempted under
 166       * this behaviour.
 167       */
 168      public function get_min_fraction() {
 169          return 0;
 170      }
 171  
 172      /**
 173       * Return the maximum possible fraction that can be scored for this question.
 174       * Normally this will be based on $this->question->get_max_fraction(),
 175       * but may be modified in some way by the behaviour.
 176       *
 177       * @return number the maximum fraction when this question is attempted under
 178       * this behaviour.
 179       */
 180      public function get_max_fraction() {
 181          return $this->question->get_max_fraction();
 182      }
 183  
 184      /**
 185       * Return an array of the behaviour variables that could be submitted
 186       * as part of a question of this type, with their types, so they can be
 187       * properly cleaned.
 188       * @return array variable name => PARAM_... constant.
 189       */
 190      public function get_expected_data() {
 191          if (!$this->qa->get_state()->is_finished()) {
 192              return array();
 193          }
 194  
 195          $vars = array('comment' => PARAM_RAW, 'commentformat' => PARAM_INT);
 196          if ($this->qa->get_max_mark()) {
 197              $vars['mark'] = question_attempt::PARAM_MARK;
 198              $vars['maxmark'] = PARAM_FLOAT;
 199          }
 200          return $vars;
 201      }
 202  
 203      /**
 204       * Return an array of question type variables for the question in its current
 205       * state. Normally, if {@link adjust_display_options()} would set
 206       * {@link question_display_options::$readonly} to true, then this method
 207       * should return an empty array, otherwise it should return
 208       * $this->question->get_expected_data(). Thus, there should be little need to
 209       * override this method.
 210       * @return array|string variable name => PARAM_... constant, or, as a special case
 211       *      that should only be used in unavoidable, the constant question_attempt::USE_RAW_DATA
 212       *      meaning take all the raw submitted data belonging to this question.
 213       */
 214      public function get_expected_qt_data() {
 215          $fakeoptions = new question_display_options();
 216          $fakeoptions->readonly = false;
 217          $this->adjust_display_options($fakeoptions);
 218          if ($fakeoptions->readonly) {
 219              return array();
 220          } else {
 221              return $this->question->get_expected_data();
 222          }
 223      }
 224  
 225      /**
 226       * Return an array of any im variables, and the value required to get full
 227       * marks.
 228       * @return array variable name => value.
 229       */
 230      public function get_correct_response() {
 231          return array();
 232      }
 233  
 234      /**
 235       * Generate a brief, plain-text, summary of this question. This is used by
 236       * various reports. This should show the particular variant of the question
 237       * as presented to students. For example, the calculated quetsion type would
 238       * fill in the particular numbers that were presented to the student.
 239       * This method will return null if such a summary is not possible, or
 240       * inappropriate.
 241       *
 242       * Normally, this method delegates to {question_definition::get_question_summary()}.
 243       *
 244       * @return string|null a plain text summary of this question.
 245       */
 246      public function get_question_summary() {
 247          return $this->question->get_question_summary();
 248      }
 249  
 250      /**
 251       * Generate a brief, plain-text, summary of the correct answer to this question.
 252       * This is used by various reports, and can also be useful when testing.
 253       * This method will return null if such a summary is not possible, or
 254       * inappropriate.
 255       *
 256       * @return string|null a plain text summary of the right answer to this question.
 257       */
 258      public function get_right_answer_summary() {
 259          return null;
 260      }
 261  
 262      /**
 263       * Used by {@link start_based_on()} to get the data needed to start a new
 264       * attempt from the point this attempt has go to.
 265       * @return array name => value pairs.
 266       */
 267      public function get_resume_data() {
 268          $olddata = $this->qa->get_step(0)->get_all_data();
 269          $olddata = $this->qa->get_last_qt_data() + $olddata;
 270          $olddata = $this->get_our_resume_data() + $olddata;
 271          return $olddata;
 272      }
 273  
 274      /**
 275       * Used by {@link start_based_on()} to get the data needed to start a new
 276       * attempt from the point this attempt has go to.
 277       * @return unknown_type
 278       */
 279      protected function get_our_resume_data() {
 280          return array();
 281      }
 282  
 283      /**
 284       * Classify responses for this question into a number of sub parts and response classes as defined by
 285       * {@link \question_type::get_possible_responses} for this question type.
 286       *
 287       * @param string $whichtries         which tries to analyse for response analysis. Will be one of
 288       *                                   question_attempt::FIRST_TRY, LAST_TRY or ALL_TRIES.
 289       *                                   Defaults to question_attempt::LAST_TRY.
 290       * @return (question_classified_response|array)[] If $whichtries is question_attempt::FIRST_TRY or LAST_TRY index is subpartid
 291       *                                   and values are question_classified_response instances.
 292       *                                   If $whichtries is question_attempt::ALL_TRIES then first key is submitted response no
 293       *                                   and the second key is subpartid.
 294       */
 295      public function classify_response($whichtries = question_attempt::LAST_TRY) {
 296          if ($whichtries == question_attempt::LAST_TRY) {
 297              return $this->question->classify_response($this->qa->get_last_qt_data());
 298          } else {
 299              $stepswithsubmit = $this->qa->get_steps_with_submitted_response_iterator();
 300              if ($whichtries == question_attempt::FIRST_TRY) {
 301                  return $this->question->classify_response($stepswithsubmit[1]->get_qt_data());
 302              } else {
 303                  $classifiedresponses = array();
 304                  foreach ($stepswithsubmit as $submittedresponseno => $step) {
 305                      $classifiedresponses[$submittedresponseno] = $this->question->classify_response($step->get_qt_data());
 306                  }
 307                  return $classifiedresponses;
 308              }
 309          }
 310      }
 311  
 312      /**
 313       * Generate a brief textual description of the current state of the question,
 314       * normally displayed under the question number.
 315       *
 316       * @param bool $showcorrectness Whether right/partial/wrong states should
 317       * be distinguised.
 318       * @return string a brief summary of the current state of the qestion attempt.
 319       */
 320      public function get_state_string($showcorrectness) {
 321          return $this->qa->get_state()->default_string($showcorrectness);
 322      }
 323  
 324      public abstract function summarise_action(question_attempt_step $step);
 325  
 326      /**
 327       * Initialise the first step in a question attempt when a new
 328       * {@link question_attempt} is being started.
 329       *
 330       * This method must call $this->question->start_attempt($step, $variant), and may
 331       * perform additional processing if the behaviour requries it.
 332       *
 333       * @param question_attempt_step $step the first step of the
 334       *      question_attempt being started.
 335       * @param int $variant which variant of the question to use.
 336       */
 337      public function init_first_step(question_attempt_step $step, $variant) {
 338          $this->question->start_attempt($step, $variant);
 339          $step->set_state(question_state::$todo);
 340      }
 341  
 342      /**
 343       * When an attempt is started based on a previous attempt (see
 344       * {@link question_attempt::start_based_on}) this method is called to setup
 345       * the new attempt.
 346       *
 347       * This method must call $this->question->apply_attempt_state($step), and may
 348       * perform additional processing if the behaviour requries it.
 349       *
 350       * @param question_attempt_step The first step of the {@link question_attempt}
 351       *      being loaded.
 352       */
 353      public function apply_attempt_state(question_attempt_step $step) {
 354          $this->question->apply_attempt_state($step);
 355          $step->set_state(question_state::$todo);
 356      }
 357  
 358      /**
 359       * Checks whether two manual grading actions are the same. That is, whether
 360       * the comment, and the mark (if given) is the same.
 361       *
 362       * @param question_attempt_step $pendingstep contains the new responses.
 363       * @return bool whether the new response is the same as we already have.
 364       */
 365      protected function is_same_comment($pendingstep) {
 366          $previouscomment = $this->qa->get_last_behaviour_var('comment');
 367          $newcomment = $pendingstep->get_behaviour_var('comment');
 368  
 369          if (is_null($previouscomment) && !html_is_blank($newcomment) ||
 370                  $previouscomment != $newcomment) {
 371              return false;
 372          }
 373  
 374          // So, now we know the comment is the same, so check the mark, if present.
 375          $previousfraction = $this->qa->get_fraction();
 376          $newmark = $pendingstep->get_behaviour_var('mark');
 377  
 378          if (is_null($previousfraction)) {
 379              return is_null($newmark) || $newmark === '';
 380          } else if (is_null($newmark) || $newmark === '') {
 381              return false;
 382          }
 383  
 384          $newfraction = $newmark / $pendingstep->get_behaviour_var('maxmark');
 385  
 386          return abs($newfraction - $previousfraction) < 0.0000001;
 387      }
 388  
 389      /**
 390       * The main entry point for processing an action.
 391       *
 392       * All the various operations that can be performed on a
 393       * {@link question_attempt} get channeled through this function, except for
 394       * {@link question_attempt::start()} which goes to {@link init_first_step()}.
 395       * {@link question_attempt::finish()} becomes an action with im vars
 396       * finish => 1, and manual comment/grade becomes an action with im vars
 397       * comment => comment text, and mark => ..., max_mark => ... if the question
 398       * is graded.
 399       *
 400       * This method should first determine whether the action is significant. For
 401       * example, if no actual action is being performed, but instead the current
 402       * responses are being saved, and there has been no change since the last
 403       * set of responses that were saved, this the action is not significatn. In
 404       * this case, this method should return {@link question_attempt::DISCARD}.
 405       * Otherwise it should return {@link question_attempt::KEEP}.
 406       *
 407       * If the action is significant, this method should also perform any
 408       * necessary updates to $pendingstep. For example, it should call
 409       * {@link question_attempt_step::set_state()} to set the state that results
 410       * from this action, and if this is a grading action, it should call
 411       * {@link question_attempt_step::set_fraction()}.
 412       *
 413       * This method can also call {@link question_attempt_step::set_behaviour_var()} to
 414       * store additional infomation. There are two main uses for this. This can
 415       * be used to store the result of any randomisation done. It is important to
 416       * store the result of randomisation once, and then in future use the same
 417       * outcome if the actions are ever replayed. This is how regrading works.
 418       * The other use is to cache the result of expensive computations performed
 419       * on the raw response data, so that subsequent display and review of the
 420       * question does not have to repeat the same expensive computations.
 421       *
 422       * Often this method is implemented as a dispatching method that examines
 423       * the pending step to determine the kind of action being performed, and
 424       * then calls a more specific method like {@link process_save()} or
 425       * {@link process_comment()}. Look at some of the standard behaviours
 426       * for examples.
 427       *
 428       * @param question_attempt_pending_step $pendingstep a partially initialised step
 429       *      containing all the information about the action that is being peformed. This
 430       *      information can be accessed using {@link question_attempt_step::get_behaviour_var()}.
 431       * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
 432       */
 433      public abstract function process_action(question_attempt_pending_step $pendingstep);
 434  
 435      /**
 436       * Auto-saved data. By default this does nothing. interesting processing is
 437       * done in {@link question_behaviour_with_save}.
 438       *
 439       * @param question_attempt_pending_step $pendingstep a partially initialised step
 440       *      containing all the information about the action that is being peformed. This
 441       *      information can be accessed using {@link question_attempt_step::get_behaviour_var()}.
 442       * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
 443       */
 444      public function process_autosave(question_attempt_pending_step $pendingstep) {
 445          return question_attempt::DISCARD;
 446      }
 447  
 448      /**
 449       * Implementation of processing a manual comment/grade action that should
 450       * be suitable for most subclasses.
 451       * @param question_attempt_pending_step $pendingstep a partially initialised step
 452       *      containing all the information about the action that is being peformed.
 453       * @return bool either {@link question_attempt::KEEP}
 454       */
 455      public function process_comment(question_attempt_pending_step $pendingstep) {
 456          if (!$this->qa->get_state()->is_finished()) {
 457              throw new coding_exception('Cannot manually grade a question before it is finshed.');
 458          }
 459  
 460          if ($this->is_same_comment($pendingstep)) {
 461              return question_attempt::DISCARD;
 462          }
 463  
 464          if ($pendingstep->has_behaviour_var('mark')) {
 465              $fraction = $pendingstep->get_behaviour_var('mark') /
 466                              $pendingstep->get_behaviour_var('maxmark');
 467              if ($pendingstep->get_behaviour_var('mark') === '') {
 468                  $fraction = null;
 469              } else if ($fraction > $this->qa->get_max_fraction() || $fraction < $this->qa->get_min_fraction()) {
 470                  throw new coding_exception('Score out of range when processing ' .
 471                          'a manual grading action.', 'Question ' . $this->question->id .
 472                                  ', slot ' . $this->qa->get_slot() . ', fraction ' . $fraction);
 473              }
 474              $pendingstep->set_fraction($fraction);
 475          }
 476  
 477          $pendingstep->set_state($this->qa->get_state()->corresponding_commented_state(
 478                  $pendingstep->get_fraction()));
 479          return question_attempt::KEEP;
 480      }
 481  
 482      /**
 483       * @param $comment the comment text to format. If omitted,
 484       *      $this->qa->get_manual_comment() is used.
 485       * @param $commentformat the format of the comment, one of the FORMAT_... constants.
 486       * @return string the comment, ready to be output.
 487       */
 488      public function format_comment($comment = null, $commentformat = null) {
 489          $formatoptions = new stdClass();
 490          $formatoptions->noclean = true;
 491          $formatoptions->para = false;
 492  
 493          if (is_null($comment)) {
 494              list($comment, $commentformat) = $this->qa->get_manual_comment();
 495          }
 496  
 497          return format_text($comment, $commentformat, $formatoptions);
 498      }
 499  
 500      /**
 501       * @return string a summary of a manual comment action.
 502       * @param unknown_type $step
 503       */
 504      protected function summarise_manual_comment($step) {
 505          $a = new stdClass();
 506          if ($step->has_behaviour_var('comment')) {
 507              $a->comment = shorten_text(html_to_text($this->format_comment(
 508                      $step->get_behaviour_var('comment')), 0, false), 200);
 509          } else {
 510              $a->comment = '';
 511          }
 512  
 513          $mark = $step->get_behaviour_var('mark');
 514          if (is_null($mark) || $mark === '') {
 515              return get_string('commented', 'question', $a->comment);
 516          } else {
 517              $a->mark = $mark / $step->get_behaviour_var('maxmark') * $this->qa->get_max_mark();
 518              return get_string('manuallygraded', 'question', $a);
 519          }
 520      }
 521  
 522      public function summarise_start($step) {
 523          return get_string('started', 'question');
 524      }
 525  
 526      public function summarise_finish($step) {
 527          return get_string('attemptfinished', 'question');
 528      }
 529  
 530      /**
 531       * Does this step include a response submitted by a student?
 532       *
 533       * This method should return true for any attempt explicitly submitted by a student. The question engine itself will also
 534       * automatically recognise any last saved response before the attempt is finished, you don't need to return true here for these
 535       * steps with responses which are not explicitly submitted by the student.
 536       *
 537       * @param question_attempt_step $step
 538       * @return bool is this a step within a question attempt that includes a submitted response by a student.
 539       */
 540      public function step_has_a_submitted_response($step) {
 541          return false;
 542      }
 543  }
 544  
 545  
 546  /**
 547   * A subclass of {@link question_behaviour} that implements a save
 548   * action that is suitable for most questions that implement the
 549   * {@link question_manually_gradable} interface.
 550   *
 551   * @copyright  2009 The Open University
 552   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 553   */
 554  abstract class question_behaviour_with_save extends question_behaviour {
 555      public function required_question_definition_type() {
 556          return 'question_manually_gradable';
 557      }
 558  
 559      public function apply_attempt_state(question_attempt_step $step) {
 560          parent::apply_attempt_state($step);
 561          if ($this->question->is_complete_response($step->get_qt_data())) {
 562              $step->set_state(question_state::$complete);
 563          }
 564      }
 565  
 566      /**
 567       * Work out whether the response in $pendingstep are significantly different
 568       * from the last set of responses we have stored.
 569       * @param question_attempt_step $pendingstep contains the new responses.
 570       * @return bool whether the new response is the same as we already have.
 571       */
 572      protected function is_same_response(question_attempt_step $pendingstep) {
 573          return $this->question->is_same_response(
 574                  $this->qa->get_last_step()->get_qt_data(), $pendingstep->get_qt_data());
 575      }
 576  
 577      /**
 578       * Work out whether the response in $pendingstep represent a complete answer
 579       * to the question. Normally this will call
 580       * {@link question_manually_gradable::is_complete_response}, but some
 581       * behaviours, for example the CBM ones, have their own parts to the
 582       * response.
 583       * @param question_attempt_step $pendingstep contains the new responses.
 584       * @return bool whether the new response is complete.
 585       */
 586      protected function is_complete_response(question_attempt_step $pendingstep) {
 587          return $this->question->is_complete_response($pendingstep->get_qt_data());
 588      }
 589  
 590      public function process_autosave(question_attempt_pending_step $pendingstep) {
 591          // If already finished. Nothing to do.
 592          if ($this->qa->get_state()->is_finished()) {
 593              return question_attempt::DISCARD;
 594          }
 595  
 596          // If the new data is the same as we already have, then we don't need it.
 597          if ($this->is_same_response($pendingstep)) {
 598              return question_attempt::DISCARD;
 599          }
 600  
 601          // Repeat that test discarding any existing autosaved data.
 602          if ($this->qa->has_autosaved_step()) {
 603              $this->qa->discard_autosaved_step();
 604              if ($this->is_same_response($pendingstep)) {
 605                  return question_attempt::DISCARD;
 606              }
 607          }
 608  
 609          // OK, we need to save.
 610          return $this->process_save($pendingstep);
 611      }
 612  
 613      /**
 614       * Implementation of processing a save action that should be suitable for
 615       * most subclasses.
 616       * @param question_attempt_pending_step $pendingstep a partially initialised step
 617       *      containing all the information about the action that is being peformed.
 618       * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
 619       */
 620      public function process_save(question_attempt_pending_step $pendingstep) {
 621          if ($this->qa->get_state()->is_finished()) {
 622              return question_attempt::DISCARD;
 623          } else if (!$this->qa->get_state()->is_active()) {
 624              throw new coding_exception('Question is not active, cannot process_actions.');
 625          }
 626  
 627          if ($this->is_same_response($pendingstep)) {
 628              return question_attempt::DISCARD;
 629          }
 630  
 631          if ($this->is_complete_response($pendingstep)) {
 632              $pendingstep->set_state(question_state::$complete);
 633          } else {
 634              $pendingstep->set_state(question_state::$todo);
 635          }
 636          return question_attempt::KEEP;
 637      }
 638  
 639      public function summarise_submit(question_attempt_step $step) {
 640          return get_string('submitted', 'question',
 641                  $this->question->summarise_response($step->get_qt_data()));
 642      }
 643  
 644      public function summarise_save(question_attempt_step $step) {
 645          $data = $step->get_submitted_data();
 646          if (empty($data)) {
 647              return $this->summarise_start($step);
 648          }
 649          return get_string('saved', 'question',
 650                  $this->question->summarise_response($step->get_qt_data()));
 651      }
 652  
 653  
 654      public function summarise_finish($step) {
 655          $data = $step->get_qt_data();
 656          if ($data) {
 657              return get_string('attemptfinishedsubmitting', 'question',
 658                      $this->question->summarise_response($data));
 659          }
 660          return get_string('attemptfinished', 'question');
 661      }
 662  }
 663  
 664  abstract class question_behaviour_with_multiple_tries extends question_behaviour_with_save {
 665      public function step_has_a_submitted_response($step) {
 666          return $step->has_behaviour_var('submit') && $step->get_state() != question_state::$invalid;
 667      }
 668  }
 669  
 670  /**
 671   * This helper class contains the constants and methods required for
 672   * manipulating scores for certainty based marking.
 673   *
 674   * @copyright  2009 The Open University
 675   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 676   */
 677  abstract class question_cbm {
 678      /**#@+ @var integer named constants for the certainty levels. */
 679      const LOW = 1;
 680      const MED = 2;
 681      const HIGH = 3;
 682      /**#@-*/
 683  
 684      /** @var array list of all the certainty levels. */
 685      public static $certainties = array(self::LOW, self::MED, self::HIGH);
 686  
 687      /**#@+ @var array coefficients used to adjust the fraction based on certainty. */
 688      protected static $rightscore = array(
 689          self::LOW  => 1,
 690          self::MED  => 2,
 691          self::HIGH => 3,
 692      );
 693      protected static $wrongscore = array(
 694          self::LOW  =>  0,
 695          self::MED  => -2,
 696          self::HIGH => -6,
 697      );
 698      /**#@-*/
 699  
 700      /**#@+ @var array upper and lower limits of the optimal window. */
 701      protected static $lowlimit = array(
 702          self::LOW  => 0,
 703          self::MED  => 0.666666666666667,
 704          self::HIGH => 0.8,
 705      );
 706      protected static $highlimit = array(
 707          self::LOW  => 0.666666666666667,
 708          self::MED  => 0.8,
 709          self::HIGH => 1,
 710      );
 711      /**#@-*/
 712  
 713      /**
 714       * @return int the default certaintly level that should be assuemd if
 715       * the student does not choose one.
 716       */
 717      public static function default_certainty() {
 718          return self::LOW;
 719      }
 720  
 721      /**
 722       * Given a fraction, and a certainty, compute the adjusted fraction.
 723       * @param number $fraction the raw fraction for this question.
 724       * @param int $certainty one of the certainty level constants.
 725       * @return number the adjusted fraction taking the certainty into account.
 726       */
 727      public static function adjust_fraction($fraction, $certainty) {
 728          if ($certainty == -1) {
 729              // Certainty -1 has never been used in standard Moodle, but is
 730              // used in Tony-Gardiner Medwin's patches to mean 'No idea' which
 731              // we intend to implement: MDL-42077. In the mean time, avoid
 732              // errors for people who have used TGM's patches.
 733              return 0;
 734          }
 735          if ($fraction <= 0.00000005) {
 736              return self::$wrongscore[$certainty];
 737          } else {
 738              return self::$rightscore[$certainty] * $fraction;
 739          }
 740      }
 741  
 742      /**
 743       * @param int $certainty one of the LOW/MED/HIGH constants.
 744       * @return string a textual description of this certainty.
 745       */
 746      public static function get_string($certainty) {
 747          return get_string('certainty' . $certainty, 'qbehaviour_deferredcbm');
 748      }
 749  
 750      /**
 751       * @param int $certainty one of the LOW/MED/HIGH constants.
 752       * @return string a short textual description of this certainty.
 753       */
 754      public static function get_short_string($certainty) {
 755          return get_string('certaintyshort' . $certainty, 'qbehaviour_deferredcbm');
 756      }
 757  
 758      /**
 759       * Add information about certainty to a response summary.
 760       * @param string $summary the response summary.
 761       * @param int $certainty the level of certainty to add.
 762       * @return string the summary with information about the certainty added.
 763       */
 764      public static function summary_with_certainty($summary, $certainty) {
 765          if (is_null($certainty)) {
 766              return $summary;
 767          }
 768          return $summary . ' [' . self::get_short_string($certainty) . ']';
 769      }
 770  
 771      /**
 772       * @param int $certainty one of the LOW/MED/HIGH constants.
 773       * @return float the lower limit of the optimal probability range for this certainty.
 774       */
 775      public static function optimal_probablility_low($certainty) {
 776          return self::$lowlimit[$certainty];
 777      }
 778  
 779      /**
 780       * @param int $certainty one of the LOW/MED/HIGH constants.
 781       * @return float the upper limit of the optimal probability range for this certainty.
 782       */
 783      public static function optimal_probablility_high($certainty) {
 784          return self::$highlimit[$certainty];
 785      }
 786  }