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