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