MDL-32188 question CBM: alter score handling.
[moodle.git] / question / behaviour / behaviourbase.php
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/>.
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  */
27 defined('MOODLE_INTERNAL') || die();
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 {
44     /** @var question_attempt the question attempt we are managing. */
45     protected $qa;
47     /** @var question_definition shortcut to $qa->get_question(). */
48     protected $question;
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     }
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);
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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         }
195         $vars = array('comment' => PARAM_RAW);
196         if ($this->qa->get_max_mark()) {
197             $vars['mark'] = question_attempt::PARAM_MARK;
198             $vars['maxmark'] = PARAM_FLOAT;
199         }
200         return $vars;
201     }
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     }
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     }
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     }
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     }
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     }
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     }
283     /**
284      * @return question_possible_response[] where keys are subpartid or an empty array if no classification is possible.
285      */
286     public function classify_response() {
287         return $this->question->classify_response($this->qa->get_last_qt_data());
288     }
290     /**
291      * Generate a brief textual description of the current state of the question,
292      * normally displayed under the question number.
293      *
294      * @param bool $showcorrectness Whether right/partial/wrong states should
295      * be distinguised.
296      * @return string a brief summary of the current state of the qestion attempt.
297      */
298     public function get_state_string($showcorrectness) {
299         return $this->qa->get_state()->default_string($showcorrectness);
300     }
302     public abstract function summarise_action(question_attempt_step $step);
304     /**
305      * Initialise the first step in a question attempt when a new
306      * {@link question_attempt} is being started.
307      *
308      * This method must call $this->question->start_attempt($step, $variant), and may
309      * perform additional processing if the behaviour requries it.
310      *
311      * @param question_attempt_step $step the first step of the
312      *      question_attempt being started.
313      * @param int $variant which variant of the question to use.
314      */
315     public function init_first_step(question_attempt_step $step, $variant) {
316         $this->question->start_attempt($step, $variant);
317         $step->set_state(question_state::$todo);
318     }
320     /**
321      * When an attempt is started based on a previous attempt (see
322      * {@link question_attempt::start_based_on}) this method is called to setup
323      * the new attempt.
324      *
325      * This method must call $this->question->apply_attempt_state($step), and may
326      * perform additional processing if the behaviour requries it.
327      *
328      * @param question_attempt_step The first step of the {@link question_attempt}
329      *      being loaded.
330      */
331     public function apply_attempt_state(question_attempt_step $step) {
332         $this->question->apply_attempt_state($step);
333         $step->set_state(question_state::$todo);
334     }
336     /**
337      * Checks whether two manual grading actions are the same. That is, whether
338      * the comment, and the mark (if given) is the same.
339      *
340      * @param question_attempt_step $pendingstep contains the new responses.
341      * @return bool whether the new response is the same as we already have.
342      */
343     protected function is_same_comment($pendingstep) {
344         $previouscomment = $this->qa->get_last_behaviour_var('comment');
345         $newcomment = $pendingstep->get_behaviour_var('comment');
347         if (is_null($previouscomment) && !html_is_blank($newcomment) ||
348                 $previouscomment != $newcomment) {
349             return false;
350         }
352         // So, now we know the comment is the same, so check the mark, if present.
353         $previousfraction = $this->qa->get_fraction();
354         $newmark = $pendingstep->get_behaviour_var('mark');
356         if (is_null($previousfraction)) {
357             return is_null($newmark) || $newmark === '';
358         } else if (is_null($newmark) || $newmark === '') {
359             return false;
360         }
362         $newfraction = $newmark / $pendingstep->get_behaviour_var('maxmark');
364         return abs($newfraction - $previousfraction) < 0.0000001;
365     }
367     /**
368      * The main entry point for processing an action.
369      *
370      * All the various operations that can be performed on a
371      * {@link question_attempt} get channeled through this function, except for
372      * {@link question_attempt::start()} which goes to {@link init_first_step()}.
373      * {@link question_attempt::finish()} becomes an action with im vars
374      * finish => 1, and manual comment/grade becomes an action with im vars
375      * comment => comment text, and mark => ..., max_mark => ... if the question
376      * is graded.
377      *
378      * This method should first determine whether the action is significant. For
379      * example, if no actual action is being performed, but instead the current
380      * responses are being saved, and there has been no change since the last
381      * set of responses that were saved, this the action is not significatn. In
382      * this case, this method should return {@link question_attempt::DISCARD}.
383      * Otherwise it should return {@link question_attempt::KEEP}.
384      *
385      * If the action is significant, this method should also perform any
386      * necessary updates to $pendingstep. For example, it should call
387      * {@link question_attempt_step::set_state()} to set the state that results
388      * from this action, and if this is a grading action, it should call
389      * {@link question_attempt_step::set_fraction()}.
390      *
391      * This method can also call {@link question_attempt_step::set_behaviour_var()} to
392      * store additional infomation. There are two main uses for this. This can
393      * be used to store the result of any randomisation done. It is important to
394      * store the result of randomisation once, and then in future use the same
395      * outcome if the actions are ever replayed. This is how regrading works.
396      * The other use is to cache the result of expensive computations performed
397      * on the raw response data, so that subsequent display and review of the
398      * question does not have to repeat the same expensive computations.
399      *
400      * Often this method is implemented as a dispatching method that examines
401      * the pending step to determine the kind of action being performed, and
402      * then calls a more specific method like {@link process_save()} or
403      * {@link process_comment()}. Look at some of the standard behaviours
404      * for examples.
405      *
406      * @param question_attempt_pending_step $pendingstep a partially initialised step
407      *      containing all the information about the action that is being peformed. This
408      *      information can be accessed using {@link question_attempt_step::get_behaviour_var()}.
409      * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
410      */
411     public abstract function process_action(question_attempt_pending_step $pendingstep);
413     /**
414      * Auto-saved data. By default this does nothing. interesting processing is
415      * done in {@link question_behaviour_with_save}.
416      *
417      * @param question_attempt_pending_step $pendingstep a partially initialised step
418      *      containing all the information about the action that is being peformed. This
419      *      information can be accessed using {@link question_attempt_step::get_behaviour_var()}.
420      * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
421      */
422     public function process_autosave(question_attempt_pending_step $pendingstep) {
423         return question_attempt::DISCARD;
424     }
426     /**
427      * Implementation of processing a manual comment/grade action that should
428      * be suitable for most subclasses.
429      * @param question_attempt_pending_step $pendingstep a partially initialised step
430      *      containing all the information about the action that is being peformed.
431      * @return bool either {@link question_attempt::KEEP}
432      */
433     public function process_comment(question_attempt_pending_step $pendingstep) {
434         if (!$this->qa->get_state()->is_finished()) {
435             throw new coding_exception('Cannot manually grade a question before it is finshed.');
436         }
438         if ($this->is_same_comment($pendingstep)) {
439             return question_attempt::DISCARD;
440         }
442         if ($pendingstep->has_behaviour_var('mark')) {
443             $fraction = $pendingstep->get_behaviour_var('mark') /
444                             $pendingstep->get_behaviour_var('maxmark');
445             if ($pendingstep->get_behaviour_var('mark') === '') {
446                 $fraction = null;
447             } else if ($fraction > $this->qa->get_max_fraction() || $fraction < $this->qa->get_min_fraction()) {
448                 throw new coding_exception('Score out of range when processing ' .
449                         'a manual grading action.', 'Question ' . $this->question->id .
450                                 ', slot ' . $this->qa->get_slot() . ', fraction ' . $fraction);
451             }
452             $pendingstep->set_fraction($fraction);
453         }
455         $pendingstep->set_state($this->qa->get_state()->corresponding_commented_state(
456                 $pendingstep->get_fraction()));
457         return question_attempt::KEEP;
458     }
460     /**
461      * @param $comment the comment text to format. If omitted,
462      *      $this->qa->get_manual_comment() is used.
463      * @param $commentformat the format of the comment, one of the FORMAT_... constants.
464      * @return string the comment, ready to be output.
465      */
466     public function format_comment($comment = null, $commentformat = null) {
467         $formatoptions = new stdClass();
468         $formatoptions->noclean = true;
469         $formatoptions->para = false;
471         if (is_null($comment)) {
472             list($comment, $commentformat) = $this->qa->get_manual_comment();
473         }
475         return format_text($comment, $commentformat, $formatoptions);
476     }
478     /**
479      * @return string a summary of a manual comment action.
480      * @param unknown_type $step
481      */
482     protected function summarise_manual_comment($step) {
483         $a = new stdClass();
484         if ($step->has_behaviour_var('comment')) {
485             $a->comment = shorten_text(html_to_text($this->format_comment(
486                     $step->get_behaviour_var('comment')), 0, false), 200);
487         } else {
488             $a->comment = '';
489         }
491         $mark = $step->get_behaviour_var('mark');
492         if (is_null($mark) || $mark === '') {
493             return get_string('commented', 'question', $a->comment);
494         } else {
495             $a->mark = $mark / $step->get_behaviour_var('maxmark') * $this->qa->get_max_mark();
496             return get_string('manuallygraded', 'question', $a);
497         }
498     }
500     public function summarise_start($step) {
501         return get_string('started', 'question');
502     }
504     public function summarise_finish($step) {
505         return get_string('attemptfinished', 'question');
506     }
510 /**
511  * A subclass of {@link question_behaviour} that implements a save
512  * action that is suitable for most questions that implement the
513  * {@link question_manually_gradable} interface.
514  *
515  * @copyright  2009 The Open University
516  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
517  */
518 abstract class question_behaviour_with_save extends question_behaviour {
519     public function required_question_definition_type() {
520         return 'question_manually_gradable';
521     }
523     public function apply_attempt_state(question_attempt_step $step) {
524         parent::apply_attempt_state($step);
525         if ($this->question->is_complete_response($step->get_qt_data())) {
526             $step->set_state(question_state::$complete);
527         }
528     }
530     /**
531      * Work out whether the response in $pendingstep are significantly different
532      * from the last set of responses we have stored.
533      * @param question_attempt_step $pendingstep contains the new responses.
534      * @return bool whether the new response is the same as we already have.
535      */
536     protected function is_same_response(question_attempt_step $pendingstep) {
537         return $this->question->is_same_response(
538                 $this->qa->get_last_step()->get_qt_data(), $pendingstep->get_qt_data());
539     }
541     /**
542      * Work out whether the response in $pendingstep represent a complete answer
543      * to the question. Normally this will call
544      * {@link question_manually_gradable::is_complete_response}, but some
545      * behaviours, for example the CBM ones, have their own parts to the
546      * response.
547      * @param question_attempt_step $pendingstep contains the new responses.
548      * @return bool whether the new response is complete.
549      */
550     protected function is_complete_response(question_attempt_step $pendingstep) {
551         return $this->question->is_complete_response($pendingstep->get_qt_data());
552     }
554     public function process_autosave(question_attempt_pending_step $pendingstep) {
555         // If already finished. Nothing to do.
556         if ($this->qa->get_state()->is_finished()) {
557             return question_attempt::DISCARD;
558         }
560         // If the new data is the same as we already have, then we don't need it.
561         if ($this->is_same_response($pendingstep)) {
562             return question_attempt::DISCARD;
563         }
565         // Repeat that test discarding any existing autosaved data.
566         if ($this->qa->has_autosaved_step()) {
567             $this->qa->discard_autosaved_step();
568             if ($this->is_same_response($pendingstep)) {
569                 return question_attempt::DISCARD;
570             }
571         }
573         // OK, we need to save.
574         return $this->process_save($pendingstep);
575     }
577     /**
578      * Implementation of processing a save action that should be suitable for
579      * most subclasses.
580      * @param question_attempt_pending_step $pendingstep a partially initialised step
581      *      containing all the information about the action that is being peformed.
582      * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
583      */
584     public function process_save(question_attempt_pending_step $pendingstep) {
585         if ($this->qa->get_state()->is_finished()) {
586             return question_attempt::DISCARD;
587         } else if (!$this->qa->get_state()->is_active()) {
588             throw new coding_exception('Question is not active, cannot process_actions.');
589         }
591         if ($this->is_same_response($pendingstep)) {
592             return question_attempt::DISCARD;
593         }
595         if ($this->is_complete_response($pendingstep)) {
596             $pendingstep->set_state(question_state::$complete);
597         } else {
598             $pendingstep->set_state(question_state::$todo);
599         }
600         return question_attempt::KEEP;
601     }
603     public function summarise_submit(question_attempt_step $step) {
604         return get_string('submitted', 'question',
605                 $this->question->summarise_response($step->get_qt_data()));
606     }
608     public function summarise_save(question_attempt_step $step) {
609         $data = $step->get_submitted_data();
610         if (empty($data)) {
611             return $this->summarise_start($step);
612         }
613         return get_string('saved', 'question',
614                 $this->question->summarise_response($step->get_qt_data()));
615     }
618     public function summarise_finish($step) {
619         $data = $step->get_qt_data();
620         if ($data) {
621             return get_string('attemptfinishedsubmitting', 'question',
622                     $this->question->summarise_response($data));
623         }
624         return get_string('attemptfinished', 'question');
625     }
629 /**
630  * This helper class contains the constants and methods required for
631  * manipulating scores for certainty based marking.
632  *
633  * @copyright  2009 The Open University
634  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
635  */
636 abstract class question_cbm {
637     /**#@+ @var integer named constants for the certainty levels. */
638     const LOW = 1;
639     const MED = 2;
640     const HIGH = 3;
641     /**#@-*/
643     /** @var array list of all the certainty levels. */
644     public static $certainties = array(self::LOW, self::MED, self::HIGH);
646     /**#@+ @var array coefficients used to adjust the fraction based on certainty. */
647     protected static $rightscore = array(
648         self::LOW  => 1,
649         self::MED  => 2,
650         self::HIGH => 3,
651     );
652     protected static $wrongscore = array(
653         self::LOW  =>  0,
654         self::MED  => -2,
655         self::HIGH => -6,
656     );
657     /**#@-*/
659     /**
660      * @return int the default certaintly level that should be assuemd if
661      * the student does not choose one.
662      */
663     public static function default_certainty() {
664         return self::LOW;
665     }
667     /**
668      * Given a fraction, and a certainty, compute the adjusted fraction.
669      * @param number $fraction the raw fraction for this question.
670      * @param int $certainty one of the certainty level constants.
671      * @return number the adjusted fraction taking the certainty into account.
672      */
673     public static function adjust_fraction($fraction, $certainty) {
674         if ($fraction <= 0.00000005) {
675             return self::$wrongscore[$certainty];
676         } else {
677             return self::$rightscore[$certainty] * $fraction;
678         }
679     }
681     /**
682      * @param int $certainty one of the LOW/MED/HIGH constants.
683      * @return string a textual description of this certainty.
684      */
685     public static function get_string($certainty) {
686         return get_string('certainty' . $certainty, 'qbehaviour_deferredcbm');
687     }
689     public static function summary_with_certainty($summary, $certainty) {
690         if (is_null($certainty)) {
691             return $summary;
692         }
693         return $summary . ' [' . self::get_string($certainty) . ']';
694     }