MDL-32188 question CBM: fix hard-coded numbers -> constants.
[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
d1b7e03d
TH
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) {
2daffca5 100 $behaviouroutput = $this->get_renderer($qoutput->get_page());
d1b7e03d
TH
101 $options = clone($options);
102 $this->adjust_display_options($options);
103 return $qoutput->question($this->qa, $behaviouroutput, $qtoutput, $options, $number);
104 }
105
7a719748
TH
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.
f7970e3c
TH
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.
7a719748
TH
114 */
115 public function check_file_access($options, $component, $filearea, $args, $forcedownload) {
116 $this->adjust_display_options($options);
1631ceea
TH
117 return $this->question->check_file_access($this->qa, $options, $component,
118 $filearea, $args, $forcedownload);
7a719748
TH
119 }
120
d1b7e03d 121 /**
2daffca5 122 * @param moodle_page $page the page to render for.
d1b7e03d
TH
123 * @return qbehaviour_renderer get the appropriate renderer to use for this model.
124 */
2daffca5
TH
125 public function get_renderer(moodle_page $page) {
126 return $page->get_renderer(get_class($this));
d1b7e03d
TH
127 }
128
129 /**
130 * Make any changes to the display options before a question is rendered, so
131 * that it can be displayed in a way that is appropriate for the statue it is
132 * currently in. For example, by default, if the question is finished, we
133 * ensure that it is only ever displayed read-only.
134 * @param question_display_options $options the options to adjust. Just change
135 * the properties of this object - objects are passed by referece.
136 */
137 public function adjust_display_options(question_display_options $options) {
138 if (!$this->qa->has_marks()) {
139 $options->correctness = false;
140 $options->numpartscorrect = false;
141 }
142 if ($this->qa->get_state()->is_finished()) {
143 $options->readonly = true;
144 $options->numpartscorrect = $options->numpartscorrect &&
145 $this->qa->get_state()->is_partially_correct() &&
146 !empty($this->question->shownumcorrect);
147 } else {
148 $options->hide_all_feedback();
149 }
150 }
151
152 /**
153 * Get the most applicable hint for the question in its current state.
154 * @return question_hint the most applicable hint, or null, if none.
155 */
156 public function get_applicable_hint() {
157 return null;
158 }
159
160 /**
161 * What is the minimum fraction that can be scored for this question.
ef31a283 162 * Normally this will be based on $this->question->get_min_fraction(),
4e3d8293 163 * but may be modified in some way by the behaviour.
d1b7e03d
TH
164 *
165 * @return number the minimum fraction when this question is attempted under
4e3d8293 166 * this behaviour.
d1b7e03d
TH
167 */
168 public function get_min_fraction() {
169 return 0;
170 }
171
4e3d8293
TH
172 /**
173 * Return the maximum possible fraction that can be scored for this question.
174 * Normally this will be based on $this->question->get_max_fraction(),
175 * but may be modified in some way by the behaviour.
176 *
177 * @return number the maximum fraction when this question is attempted under
178 * this behaviour.
179 */
180 public function get_max_fraction() {
181 return $this->question->get_max_fraction();
182 }
183
d1b7e03d
TH
184 /**
185 * Return an array of the behaviour variables that could be submitted
186 * as part of a question of this type, with their types, so they can be
187 * properly cleaned.
188 * @return array variable name => PARAM_... constant.
189 */
190 public function get_expected_data() {
191 if (!$this->qa->get_state()->is_finished()) {
192 return array();
193 }
194
195 $vars = array('comment' => PARAM_RAW);
196 if ($this->qa->get_max_mark()) {
197 $vars['mark'] = question_attempt::PARAM_MARK;
61cca0b7 198 $vars['maxmark'] = PARAM_FLOAT;
d1b7e03d
TH
199 }
200 return $vars;
201 }
202
203 /**
204 * Return an array of question type variables for the question in its current
205 * state. Normally, if {@link adjust_display_options()} would set
206 * {@link question_display_options::$readonly} to true, then this method
207 * should return an empty array, otherwise it should return
208 * $this->question->get_expected_data(). Thus, there should be little need to
209 * override this method.
210 * @return array|string variable name => PARAM_... constant, or, as a special case
211 * that should only be used in unavoidable, the constant question_attempt::USE_RAW_DATA
212 * meaning take all the raw submitted data belonging to this question.
213 */
214 public function get_expected_qt_data() {
215 $fakeoptions = new question_display_options();
216 $fakeoptions->readonly = false;
217 $this->adjust_display_options($fakeoptions);
218 if ($fakeoptions->readonly) {
219 return array();
220 } else {
221 return $this->question->get_expected_data();
222 }
223 }
224
225 /**
226 * Return an array of any im variables, and the value required to get full
227 * marks.
228 * @return array variable name => value.
229 */
230 public function get_correct_response() {
231 return array();
232 }
233
234 /**
235 * Generate a brief, plain-text, summary of this question. This is used by
236 * various reports. This should show the particular variant of the question
237 * as presented to students. For example, the calculated quetsion type would
238 * fill in the particular numbers that were presented to the student.
239 * This method will return null if such a summary is not possible, or
240 * inappropriate.
241 *
242 * Normally, this method delegates to {question_definition::get_question_summary()}.
243 *
244 * @return string|null a plain text summary of this question.
245 */
246 public function get_question_summary() {
ec3d4ef5 247 return $this->question->get_question_summary();
d1b7e03d
TH
248 }
249
250 /**
251 * Generate a brief, plain-text, summary of the correct answer to this question.
252 * This is used by various reports, and can also be useful when testing.
253 * This method will return null if such a summary is not possible, or
254 * inappropriate.
255 *
256 * @return string|null a plain text summary of the right answer to this question.
257 */
258 public function get_right_answer_summary() {
259 return null;
260 }
261
262 /**
263 * Used by {@link start_based_on()} to get the data needed to start a new
264 * attempt from the point this attempt has go to.
265 * @return array name => value pairs.
266 */
267 public function get_resume_data() {
268 $olddata = $this->qa->get_step(0)->get_all_data();
269 $olddata = $this->qa->get_last_qt_data() + $olddata;
270 $olddata = $this->get_our_resume_data() + $olddata;
271 return $olddata;
272 }
273
274 /**
275 * Used by {@link start_based_on()} to get the data needed to start a new
276 * attempt from the point this attempt has go to.
277 * @return unknown_type
278 */
279 protected function get_our_resume_data() {
280 return array();
281 }
282
283 /**
d50b05e6 284 * @return question_possible_response[] where keys are subpartid or an empty array if no classification is possible.
d1b7e03d
TH
285 */
286 public function classify_response() {
287 return $this->question->classify_response($this->qa->get_last_qt_data());
288 }
289
290 /**
291 * Generate a brief textual description of the current state of the question,
292 * normally displayed under the question number.
293 *
f7970e3c 294 * @param bool $showcorrectness Whether right/partial/wrong states should
d1b7e03d
TH
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 }
301
c7df5006 302 public abstract function summarise_action(question_attempt_step $step);
d1b7e03d
TH
303
304 /**
ef31a283
TH
305 * Initialise the first step in a question attempt when a new
306 * {@link question_attempt} is being started.
d1b7e03d 307 *
f8e28244
RK
308 * This method must call $this->question->start_attempt($step, $variant), and may
309 * perform additional processing if the behaviour requries it.
d1b7e03d 310 *
ef31a283
TH
311 * @param question_attempt_step $step the first step of the
312 * question_attempt being started.
1da821bb 313 * @param int $variant which variant of the question to use.
d1b7e03d 314 */
1da821bb
TH
315 public function init_first_step(question_attempt_step $step, $variant) {
316 $this->question->start_attempt($step, $variant);
f8e28244
RK
317 $step->set_state(question_state::$todo);
318 }
319
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);
d1b7e03d
TH
334 }
335
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.
f7970e3c 341 * @return bool whether the new response is the same as we already have.
d1b7e03d
TH
342 */
343 protected function is_same_comment($pendingstep) {
344 $previouscomment = $this->qa->get_last_behaviour_var('comment');
345 $newcomment = $pendingstep->get_behaviour_var('comment');
346
347 if (is_null($previouscomment) && !html_is_blank($newcomment) ||
348 $previouscomment != $newcomment) {
349 return false;
350 }
351
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');
355
356 if (is_null($previousfraction)) {
357 return is_null($newmark) || $newmark === '';
358 } else if (is_null($newmark) || $newmark === '') {
359 return false;
360 }
361
362 $newfraction = $newmark / $pendingstep->get_behaviour_var('maxmark');
363
364 return abs($newfraction - $previousfraction) < 0.0000001;
365 }
366
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
1631ceea
TH
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()}.
f7970e3c 409 * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
d1b7e03d
TH
410 */
411 public abstract function process_action(question_attempt_pending_step $pendingstep);
412
0a606a2b
TH
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 }
425
d1b7e03d
TH
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.
f7970e3c 431 * @return bool either {@link question_attempt::KEEP}
d1b7e03d
TH
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 }
437
438 if ($this->is_same_comment($pendingstep)) {
439 return question_attempt::DISCARD;
440 }
441
442 if ($pendingstep->has_behaviour_var('mark')) {
1631ceea
TH
443 $fraction = $pendingstep->get_behaviour_var('mark') /
444 $pendingstep->get_behaviour_var('maxmark');
d1b7e03d
TH
445 if ($pendingstep->get_behaviour_var('mark') === '') {
446 $fraction = null;
4e3d8293 447 } else if ($fraction > $this->qa->get_max_fraction() || $fraction < $this->qa->get_min_fraction()) {
d1b7e03d 448 throw new coding_exception('Score out of range when processing ' .
15dd7727 449 'a manual grading action.', 'Question ' . $this->question->id .
ee326d5e 450 ', slot ' . $this->qa->get_slot() . ', fraction ' . $fraction);
d1b7e03d
TH
451 }
452 $pendingstep->set_fraction($fraction);
453 }
454
1631ceea
TH
455 $pendingstep->set_state($this->qa->get_state()->corresponding_commented_state(
456 $pendingstep->get_fraction()));
d1b7e03d
TH
457 return question_attempt::KEEP;
458 }
459
460 /**
461 * @param $comment the comment text to format. If omitted,
462 * $this->qa->get_manual_comment() is used.
7a719748 463 * @param $commentformat the format of the comment, one of the FORMAT_... constants.
d1b7e03d
TH
464 * @return string the comment, ready to be output.
465 */
7a719748 466 public function format_comment($comment = null, $commentformat = null) {
0ff4bd08 467 $formatoptions = new stdClass();
d1b7e03d
TH
468 $formatoptions->noclean = true;
469 $formatoptions->para = false;
470
471 if (is_null($comment)) {
7a719748 472 list($comment, $commentformat) = $this->qa->get_manual_comment();
d1b7e03d
TH
473 }
474
7a719748 475 return format_text($comment, $commentformat, $formatoptions);
d1b7e03d
TH
476 }
477
478 /**
479 * @return string a summary of a manual comment action.
480 * @param unknown_type $step
481 */
482 protected function summarise_manual_comment($step) {
0ff4bd08 483 $a = new stdClass();
d1b7e03d
TH
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 }
490
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 }
499
500 public function summarise_start($step) {
501 return get_string('started', 'question');
502 }
503
504 public function summarise_finish($step) {
505 return get_string('attemptfinished', 'question');
506 }
507}
508
509
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 *
f7970e3c
TH
515 * @copyright 2009 The Open University
516 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
d1b7e03d
TH
517 */
518abstract class question_behaviour_with_save extends question_behaviour {
519 public function required_question_definition_type() {
520 return 'question_manually_gradable';
521 }
522
f8e28244
RK
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 }
529
d1b7e03d
TH
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.
f7970e3c 534 * @return bool whether the new response is the same as we already have.
d1b7e03d
TH
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 }
540
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.
f7970e3c 548 * @return bool whether the new response is complete.
d1b7e03d
TH
549 */
550 protected function is_complete_response(question_attempt_step $pendingstep) {
551 return $this->question->is_complete_response($pendingstep->get_qt_data());
552 }
553
0a606a2b
TH
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 }
559
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 }
564
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 }
572
573 // OK, we need to save.
574 return $this->process_save($pendingstep);
575 }
576
d1b7e03d
TH
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.
f7970e3c 582 * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
d1b7e03d
TH
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()) {
88f0eb15 588 throw new coding_exception('Question is not active, cannot process_actions.');
d1b7e03d
TH
589 }
590
591 if ($this->is_same_response($pendingstep)) {
592 return question_attempt::DISCARD;
593 }
594
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 }
602
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 }
607
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 }
616
617
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 }
626}
627
628
629/**
630 * This helper class contains the constants and methods required for
c4efeb2b 631 * manipulating scores for certainty based marking.
d1b7e03d 632 *
f7970e3c
TH
633 * @copyright 2009 The Open University
634 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
d1b7e03d
TH
635 */
636abstract 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 /**#@-*/
642
643 /** @var array list of all the certainty levels. */
644 public static $certainties = array(self::LOW, self::MED, self::HIGH);
645
646 /**#@+ @var array coefficients used to adjust the fraction based on certainty.. */
647 protected static $factor = array(
648 self::LOW => 0.333333333333333,
649 self::MED => 1.333333333333333,
650 self::HIGH => 3,
651 );
652 protected static $offset = array(
653 self::LOW => 0,
654 self::MED => -0.666666666666667,
655 self::HIGH => -2,
656 );
657 /**#@-*/
658
659 /**
f7970e3c 660 * @return int the default certaintly level that should be assuemd if
d1b7e03d
TH
661 * the student does not choose one.
662 */
663 public static function default_certainty() {
664 return self::LOW;
665 }
666
667 /**
c4efeb2b 668 * Given a fraction, and a certainty, compute the adjusted fraction.
d1b7e03d 669 * @param number $fraction the raw fraction for this question.
c4efeb2b
TH
670 * @param int $certainty one of the certainty level constants.
671 * @return number the adjusted fraction taking the certainty into account.
d1b7e03d
TH
672 */
673 public static function adjust_fraction($fraction, $certainty) {
674 return self::$offset[$certainty] + self::$factor[$certainty] * $fraction;
675 }
676
677 /**
f7970e3c 678 * @param int $certainty one of the LOW/MED/HIGH constants.
c4efeb2b 679 * @return string a textual description of this certainty.
d1b7e03d
TH
680 */
681 public static function get_string($certainty) {
682 return get_string('certainty' . $certainty, 'qbehaviour_deferredcbm');
683 }
684
685 public static function summary_with_certainty($summary, $certainty) {
686 if (is_null($certainty)) {
687 return $summary;
688 }
689 return $summary . ' [' . self::get_string($certainty) . ']';
690 }
691}