2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * This file defines the class {@link question_definition} and its subclasses.
20 * The type hierarchy is quite complex. Here is a summary:
21 * - question_definition
22 * - question_information_item
23 * - question_with_responses implements question_manually_gradable
24 * - question_graded_automatically implements question_automatically_gradable
25 * - question_graded_automatically_with_countback implements question_automatically_gradable_with_countback
26 * - question_graded_by_strategy
29 * - question_classified_response
32 * - question_hint_with_parts
33 * - question_first_matching_answer_grading_strategy implements question_grading_strategy
36 * - question_response_answer_comparer
39 * @subpackage questiontypes
40 * @copyright 2009 The Open University
41 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
45 defined('MOODLE_INTERNAL') ||
die();
49 * The definition of a question of a particular type.
51 * This class is a close match to the question table in the database.
52 * Definitions of question of a particular type normally subclass one of the
53 * more specific classes {@link question_with_responses},
54 * {@link question_graded_automatically} or {@link question_information_item}.
56 * @copyright 2009 The Open University
57 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
59 abstract class question_definition
{
60 /** @var integer id of the question in the datase, or null if this question
61 * is not in the database. */
64 /** @var integer question category id. */
67 /** @var integer question context id. */
70 /** @var integer parent question id. */
73 /** @var question_type the question type this question is. */
76 /** @var string question name. */
79 /** @var string question text. */
82 /** @var integer question test format. */
83 public $questiontextformat;
85 /** @var string question general feedback. */
86 public $generalfeedback;
88 /** @var integer question test format. */
89 public $generalfeedbackformat;
91 /** @var number what this quetsion is marked out of, by default. */
92 public $defaultmark = 1;
94 /** @var integer How many question numbers this question consumes. */
97 /** @var number penalty factor of this question. */
100 /** @var string unique identifier of this question. */
103 /** @var string unique identifier of this version of this question. */
106 /** @var boolean whethre this question has been deleted/hidden in the question bank. */
109 /** @var integer timestamp when this question was created. */
112 /** @var integer timestamp when this question was modified. */
113 public $timemodified;
115 /** @var integer userid of the use who created this question. */
118 /** @var integer userid of the use who modified this question. */
121 /** @var array of question_hints. */
122 public $hints = array();
125 * Constructor. Normally to get a question, you call
126 * {@link question_bank::load_question()}, but questions can be created
127 * directly, for example in unit test code.
128 * @return unknown_type
130 public function __construct() {
134 * @return the name of the question type (for example multichoice) that this
137 public function get_type_name() {
138 return $this->qtype
->name();
142 * Creat the appropriate behaviour for an attempt at this quetsion,
143 * given the desired (archetypal) behaviour.
145 * This default implementation will suit most normal graded questions.
147 * If your question is of a patricular type, then it may need to do something
148 * different. For example, if your question can only be graded manually, then
149 * it should probably return a manualgraded behaviour, irrespective of
152 * If your question wants to do somthing especially complicated is some situations,
153 * then you may wish to return a particular behaviour related to the
154 * one asked for. For example, you migth want to return a
155 * qbehaviour_interactive_adapted_for_myqtype.
157 * @param question_attempt $qa the attempt we are creating a behaviour for.
158 * @param string $preferredbehaviour the requested type of behaviour.
159 * @return question_behaviour the new behaviour object.
161 public function make_behaviour(question_attempt
$qa, $preferredbehaviour) {
162 return question_engine
::make_archetypal_behaviour($preferredbehaviour, $qa);
166 * Start a new attempt at this question, storing any information that will
167 * be needed later in the step.
169 * This is where the question can do any initialisation required on a
170 * per-attempt basis. For example, this is where the multiple choice
171 * question type randomly shuffles the choices (if that option is set).
173 * Any information about how the question has been set up for this attempt
174 * should be stored in the $step, by calling $step->set_qt_var(...).
176 * @param question_attempt_step The first step of the {@link question_attempt}
177 * being started. Can be used to store state.
178 * @param int $varant which variant of this question to start. Will be between
179 * 1 and {@link get_num_variants()} inclusive.
181 public function start_attempt(question_attempt_step
$step, $variant) {
185 * When an in-progress {@link question_attempt} is re-loaded from the
186 * database, this method is called so that the question can re-initialise
187 * its internal state as needed by this attempt.
189 * For example, the multiple choice question type needs to set the order
190 * of the choices to the order that was set up when start_attempt was called
191 * originally. All the information required to do this should be in the
192 * $step object, which is the first step of the question_attempt being loaded.
194 * @param question_attempt_step The first step of the {@link question_attempt}
197 public function apply_attempt_state(question_attempt_step
$step) {
201 * Generate a brief, plain-text, summary of this question. This is used by
202 * various reports. This should show the particular variant of the question
203 * as presented to students. For example, the calculated quetsion type would
204 * fill in the particular numbers that were presented to the student.
205 * This method will return null if such a summary is not possible, or
207 * @return string|null a plain text summary of this question.
209 public function get_question_summary() {
210 return $this->html_to_text($this->questiontext
, $this->questiontextformat
);
214 * @return int the number of vaiants that this question has.
216 public function get_num_variants() {
221 * @return string that can be used to seed the pseudo-random selection of a
224 public function get_variants_selection_seed() {
229 * Some questions can return a negative mark if the student gets it wrong.
231 * This method returns the lowest mark the question can return, on the
232 * fraction scale. that is, where the maximum possible mark is 1.0.
234 * @return float minimum fraction this question will ever return.
236 public function get_min_fraction() {
241 * Some questions can return a mark greater than the maximum.
243 * This method returns the lowest highest the question can return, on the
244 * fraction scale. that is, where the nominal maximum mark is 1.0.
246 * @return float maximum fraction this question will ever return.
248 public function get_max_fraction() {
253 * Given a response, rest the parts that are wrong.
254 * @param array $response a response
255 * @return array a cleaned up response with the wrong bits reset.
257 public function clear_wrong_from_response(array $response) {
262 * Return the number of subparts of this response that are right.
263 * @param array $response a response
264 * @return array with two elements, the number of correct subparts, and
265 * the total number of subparts.
267 public function get_num_parts_right(array $response) {
268 return array(null, null);
272 * @param moodle_page the page we are outputting to.
273 * @return qtype_renderer the renderer to use for outputting this question.
275 public function get_renderer(moodle_page
$page) {
276 return $page->get_renderer($this->qtype
->plugin_name());
280 * What data may be included in the form submission when a student submits
281 * this question in its current state?
283 * This information is used in calls to optional_param. The parameter name
284 * has {@link question_attempt::get_field_prefix()} automatically prepended.
286 * @return array|string variable name => PARAM_... constant, or, as a special case
287 * that should only be used in unavoidable, the constant question_attempt::USE_RAW_DATA
288 * meaning take all the raw submitted data belonging to this question.
290 public abstract function get_expected_data();
293 * What data would need to be submitted to get this question correct.
294 * If there is more than one correct answer, this method should just
295 * return one possibility. If it is not possible to compute a correct
296 * response, this method should return null.
298 * @return array|null parameter name => value.
300 public abstract function get_correct_response();
304 * Takes an array of values representing a student response represented in a way that is understandable by a human and
305 * transforms that to the response as the POST values returned from the HTML form that takes the student response during a
306 * student attempt. Primarily this is used when reading csv values from a file of student responses in order to be able to
307 * simulate the student interaction with a quiz.
309 * In most cases the array will just be returned as is. Some question types will need to transform the keys of the array,
310 * as the meaning of the keys in the html form is deliberately obfuscated so that someone looking at the html does not get an
311 * advantage. The values that represent the response might also be changed in order to more meaningful to a human.
313 * See the examples of question types that have overridden this in core and also see the csv files of simulated student
314 * responses used in unit tests in :
315 * - mod/quiz/tests/fixtures/stepsXX.csv
316 * - mod/quiz/report/responses/tests/fixtures/steps00.csv
317 * - mod/quiz/report/statistics/tests/fixtures/stepsXX.csv
319 * Also see {@link https://github.com/jamiepratt/moodle-quiz_simulate}, a quiz report plug in for uploading and downloading
320 * student responses as csv files.
322 * @param array $simulatedresponse an array of data representing a student response
323 * @return array a response array as would be returned from the html form (but without prefixes)
325 public function prepare_simulated_post_data($simulatedresponse) {
326 return $simulatedresponse;
330 * Does the opposite of {@link prepare_simulated_post_data}.
332 * This takes a student response (the POST values returned from the HTML form that takes the student response during a
333 * student attempt) it then represents it in a way that is understandable by a human.
335 * Primarily this is used when creating a file of csv from real student responses in order later to be able to
336 * simulate the same student interaction with a quiz later.
338 * @param string[] $realresponse the response array as was returned from the form during a student attempt (without prefixes).
339 * @return string[] an array of data representing a student response.
341 public function get_student_response_values_for_simulation($realresponse) {
342 return $realresponse;
346 * Apply {@link format_text()} to some content with appropriate settings for
349 * @param string $text some content that needs to be output.
350 * @param int $format the FORMAT_... constant.
351 * @param question_attempt $qa the question attempt.
352 * @param string $component used for rewriting file area URLs.
353 * @param string $filearea used for rewriting file area URLs.
354 * @param bool $clean Whether the HTML needs to be cleaned. Generally,
355 * parts of the question do not need to be cleaned, and student input does.
356 * @return string the text formatted for output by format_text.
358 public function format_text($text, $format, $qa, $component, $filearea, $itemid,
360 $formatoptions = new stdClass();
361 $formatoptions->noclean
= !$clean;
362 $formatoptions->para
= false;
363 $text = $qa->rewrite_pluginfile_urls($text, $component, $filearea, $itemid);
364 return format_text($text, $format, $formatoptions);
368 * Convert some part of the question text to plain text. This might be used,
369 * for example, by get_response_summary().
370 * @param string $text The HTML to reduce to plain text.
371 * @param int $format the FORMAT_... constant.
372 * @return string the equivalent plain text.
374 public function html_to_text($text, $format) {
375 return question_utils
::to_plain_text($text, $format);
378 /** @return the result of applying {@link format_text()} to the question text. */
379 public function format_questiontext($qa) {
380 return $this->format_text($this->questiontext
, $this->questiontextformat
,
381 $qa, 'question', 'questiontext', $this->id
);
384 /** @return the result of applying {@link format_text()} to the general feedback. */
385 public function format_generalfeedback($qa) {
386 return $this->format_text($this->generalfeedback
, $this->generalfeedbackformat
,
387 $qa, 'question', 'generalfeedback', $this->id
);
391 * Take some HTML that should probably already be a single line, like a
392 * multiple choice choice, or the corresponding feedback, and make it so that
393 * it is suitable to go in a place where the HTML must be inline, like inside a <p> tag.
394 * @param string $html to HTML to fix up.
395 * @return string the fixed HTML.
397 public function make_html_inline($html) {
398 $html = preg_replace('~\s*<p>\s*~u', '', $html);
399 $html = preg_replace('~\s*</p>\s*~u', '<br />', $html);
400 $html = preg_replace('~(<br\s*/?>)+$~u', '', $html);
405 * Checks whether the users is allow to be served a particular file.
406 * @param question_attempt $qa the question attempt being displayed.
407 * @param question_display_options $options the options that control display of the question.
408 * @param string $component the name of the component we are serving files for.
409 * @param string $filearea the name of the file area.
410 * @param array $args the remaining bits of the file path.
411 * @param bool $forcedownload whether the user must be forced to download the file.
412 * @return bool true if the user can access this file.
414 public function check_file_access($qa, $options, $component, $filearea, $args, $forcedownload) {
415 if ($component == 'question' && $filearea == 'questiontext') {
416 // Question text always visible, but check it is the right question id.
417 return $args[0] == $this->id
;
419 } else if ($component == 'question' && $filearea == 'generalfeedback') {
420 return $options->generalfeedback
&& $args[0] == $this->id
;
423 // Unrecognised component or filearea.
431 * This class represents a 'question' that actually does not allow the student
432 * to respond, like the description 'question' type.
434 * @copyright 2009 The Open University
435 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
437 class question_information_item
extends question_definition
{
438 public function __construct() {
439 parent
::__construct();
440 $this->defaultmark
= 0;
445 public function make_behaviour(question_attempt
$qa, $preferredbehaviour) {
446 return question_engine
::make_behaviour('informationitem', $qa, $preferredbehaviour);
449 public function get_expected_data() {
453 public function get_correct_response() {
457 public function get_question_summary() {
464 * Interface that a {@link question_definition} must implement to be usable by
465 * the manual graded behaviour.
467 * @copyright 2009 The Open University
468 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
470 interface question_manually_gradable
{
472 * Use by many of the behaviours to determine whether the student
473 * has provided enough of an answer for the question to be graded automatically,
474 * or whether it must be considered aborted.
476 * @param array $response responses, as returned by
477 * {@link question_attempt_step::get_qt_data()}.
478 * @return bool whether this response can be graded.
480 public function is_gradable_response(array $response);
483 * Used by many of the behaviours, to work out whether the student's
484 * response to the question is complete. That is, whether the question attempt
485 * should move to the COMPLETE or INCOMPLETE state.
487 * @param array $response responses, as returned by
488 * {@link question_attempt_step::get_qt_data()}.
489 * @return bool whether this response is a complete answer to this question.
491 public function is_complete_response(array $response);
494 * Use by many of the behaviours to determine whether the student's
495 * response has changed. This is normally used to determine that a new set
496 * of responses can safely be discarded.
498 * @param array $prevresponse the responses previously recorded for this question,
499 * as returned by {@link question_attempt_step::get_qt_data()}
500 * @param array $newresponse the new responses, in the same format.
501 * @return bool whether the two sets of responses are the same - that is
502 * whether the new set of responses can safely be discarded.
504 public function is_same_response(array $prevresponse, array $newresponse);
507 * Produce a plain text summary of a response.
508 * @param $response a response, as might be passed to {@link grade_response()}.
509 * @return string a plain text summary of that response, that could be used in reports.
511 public function summarise_response(array $response);
514 * Categorise the student's response according to the categories defined by
515 * get_possible_responses.
516 * @param $response a response, as might be passed to {@link grade_response()}.
517 * @return array subpartid => {@link question_classified_response} objects.
518 * returns an empty array if no analysis is possible.
520 public function classify_response(array $response);
525 * This class is used in the return value from
526 * {@link question_manually_gradable::classify_response()}.
528 * @copyright 2010 The Open University
529 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
531 class question_classified_response
{
533 * @var string the classification of this response the student gave to this
534 * part of the question. Must match one of the responseclasses returned by
535 * {@link question_type::get_possible_responses()}.
537 public $responseclassid;
538 /** @var string the actual response the student gave to this part. */
540 /** @var number the fraction this part of the response earned. */
543 * Constructor, just an easy way to set the fields.
544 * @param string $responseclassid see the field descriptions above.
545 * @param string $response see the field descriptions above.
546 * @param number $fraction see the field descriptions above.
548 public function __construct($responseclassid, $response, $fraction) {
549 $this->responseclassid
= $responseclassid;
550 $this->response
= $response;
551 $this->fraction
= $fraction;
554 public static function no_response() {
555 return new question_classified_response(null, get_string('noresponse', 'question'), null);
561 * Interface that a {@link question_definition} must implement to be usable by
562 * the various automatic grading behaviours.
564 * @copyright 2009 The Open University
565 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
567 interface question_automatically_gradable
extends question_manually_gradable
{
569 * In situations where is_gradable_response() returns false, this method
570 * should generate a description of what the problem is.
571 * @return string the message.
573 public function get_validation_error(array $response);
576 * Grade a response to the question, returning a fraction between
577 * get_min_fraction() and get_max_fraction(), and the corresponding {@link question_state}
578 * right, partial or wrong.
579 * @param array $response responses, as returned by
580 * {@link question_attempt_step::get_qt_data()}.
581 * @return array (float, integer) the fraction, and the state.
583 public function grade_response(array $response);
586 * Get one of the question hints. The question_attempt is passed in case
587 * the question type wants to do something complex. For example, the
588 * multiple choice with multiple responses question type will turn off most
589 * of the hint options if the student has selected too many opitions.
590 * @param int $hintnumber Which hint to display. Indexed starting from 0
591 * @param question_attempt $qa The question_attempt.
593 public function get_hint($hintnumber, question_attempt
$qa);
596 * Generate a brief, plain-text, summary of the correct answer to this question.
597 * This is used by various reports, and can also be useful when testing.
598 * This method will return null if such a summary is not possible, or
600 * @return string|null a plain text summary of the right answer to this question.
602 public function get_right_answer_summary();
607 * Interface that a {@link question_definition} must implement to be usable by
608 * the interactivecountback behaviour.
610 * @copyright 2010 The Open University
611 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
613 interface question_automatically_gradable_with_countback
extends question_automatically_gradable
{
615 * Work out a final grade for this attempt, taking into account all the
616 * tries the student made.
617 * @param array $responses the response for each try. Each element of this
618 * array is a response array, as would be passed to {@link grade_response()}.
619 * There may be between 1 and $totaltries responses.
620 * @param int $totaltries The maximum number of tries allowed.
621 * @return numeric the fraction that should be awarded for this
622 * sequence of response.
624 public function compute_final_grade($responses, $totaltries);
629 * This class represents a real question. That is, one that is not a
630 * {@link question_information_item}.
632 * @copyright 2009 The Open University
633 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
635 abstract class question_with_responses
extends question_definition
636 implements question_manually_gradable
{
637 public function classify_response(array $response) {
641 public function is_gradable_response(array $response) {
642 return $this->is_complete_response($response);
648 * This class represents a question that can be graded automatically.
650 * @copyright 2009 The Open University
651 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
653 abstract class question_graded_automatically
extends question_with_responses
654 implements question_automatically_gradable
{
655 /** @var Some question types have the option to show the number of sub-parts correct. */
656 public $shownumcorrect = false;
658 public function get_right_answer_summary() {
659 $correctresponse = $this->get_correct_response();
660 if (empty($correctresponse)) {
663 return $this->summarise_response($correctresponse);
667 * Check a request for access to a file belonging to a combined feedback field.
668 * @param question_attempt $qa the question attempt being displayed.
669 * @param question_display_options $options the options that control display of the question.
670 * @param string $filearea the name of the file area.
671 * @param array $args the remaining bits of the file path.
672 * @return bool whether access to the file should be allowed.
674 protected function check_combined_feedback_file_access($qa, $options, $filearea, $args = null) {
675 $state = $qa->get_state();
677 if ($args === null) {
678 debugging('You must pass $args as the fourth argument to check_combined_feedback_file_access.',
680 $args = array($this->id
); // Fake it for now, so the rest of this method works.
683 if (!$state->is_finished()) {
684 $response = $qa->get_last_qt_data();
685 if (!$this->is_gradable_response($response)) {
688 list($notused, $state) = $this->grade_response($response);
691 return $options->feedback
&& $state->get_feedback_class() . 'feedback' == $filearea &&
692 $args[0] == $this->id
;
696 * Check a request for access to a file belonging to a hint.
697 * @param question_attempt $qa the question attempt being displayed.
698 * @param question_display_options $options the options that control display of the question.
699 * @param array $args the remaining bits of the file path.
700 * @return bool whether access to the file should be allowed.
702 protected function check_hint_file_access($qa, $options, $args) {
703 if (!$options->feedback
) {
706 $hint = $qa->get_applicable_hint();
707 $hintid = reset($args); // Itemid is hint id.
708 return $hintid == $hint->id
;
711 public function get_hint($hintnumber, question_attempt
$qa) {
712 if (!isset($this->hints
[$hintnumber])) {
715 return $this->hints
[$hintnumber];
718 public function format_hint(question_hint
$hint, question_attempt
$qa) {
719 return $this->format_text($hint->hint
, $hint->hintformat
, $qa,
720 'question', 'hint', $hint->id
);
726 * This class represents a question that can be graded automatically with
727 * countback grading in interactive mode.
729 * @copyright 2010 The Open University
730 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
732 abstract class question_graded_automatically_with_countback
733 extends question_graded_automatically
734 implements question_automatically_gradable_with_countback
{
736 public function make_behaviour(question_attempt
$qa, $preferredbehaviour) {
737 if ($preferredbehaviour == 'interactive') {
738 return question_engine
::make_behaviour('interactivecountback',
739 $qa, $preferredbehaviour);
741 return question_engine
::make_archetypal_behaviour($preferredbehaviour, $qa);
747 * This class represents a question that can be graded automatically by using
748 * a {@link question_grading_strategy}.
750 * @copyright 2009 The Open University
751 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
753 abstract class question_graded_by_strategy
extends question_graded_automatically
{
754 /** @var question_grading_strategy the strategy to use for grading. */
755 protected $gradingstrategy;
757 /** @param question_grading_strategy $strategy the strategy to use for grading. */
758 public function __construct(question_grading_strategy
$strategy) {
759 parent
::__construct();
760 $this->gradingstrategy
= $strategy;
763 public function get_correct_response() {
764 $answer = $this->get_correct_answer();
769 return array('answer' => $answer->answer
);
773 * Get an answer that contains the feedback and fraction that should be
774 * awarded for this resonse.
775 * @param array $response a response.
776 * @return question_answer the matching answer.
778 public function get_matching_answer(array $response) {
779 return $this->gradingstrategy
->grade($response);
783 * @return question_answer an answer that contains the a response that would
786 public function get_correct_answer() {
787 return $this->gradingstrategy
->get_correct_answer();
790 public function grade_response(array $response) {
791 $answer = $this->get_matching_answer($response);
793 return array($answer->fraction
,
794 question_state
::graded_state_for_fraction($answer->fraction
));
796 return array(0, question_state
::$gradedwrong);
800 public function classify_response(array $response) {
801 if (empty($response['answer'])) {
802 return array($this->id
=> question_classified_response
::no_response());
805 $ans = $this->get_matching_answer($response);
807 return array($this->id
=> new question_classified_response(
808 0, $response['answer'], 0));
811 return array($this->id
=> new question_classified_response(
812 $ans->id
, $response['answer'], $ans->fraction
));
818 * Class to represent a question answer, loaded from the question_answers table
821 * @copyright 2009 The Open University
822 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
824 class question_answer
{
825 /** @var integer the answer id. */
828 /** @var string the answer. */
831 /** @var integer one of the FORMAT_... constans. */
832 public $answerformat = FORMAT_PLAIN
;
834 /** @var number the fraction this answer is worth. */
837 /** @var string the feedback for this answer. */
840 /** @var integer one of the FORMAT_... constans. */
841 public $feedbackformat;
845 * @param int $id the answer.
846 * @param string $answer the answer.
847 * @param number $fraction the fraction this answer is worth.
848 * @param string $feedback the feedback for this answer.
849 * @param int $feedbackformat the format of the feedback.
851 public function __construct($id, $answer, $fraction, $feedback, $feedbackformat) {
853 $this->answer
= $answer;
854 $this->fraction
= $fraction;
855 $this->feedback
= $feedback;
856 $this->feedbackformat
= $feedbackformat;
862 * Class to represent a hint associated with a question.
863 * Used by iteractive mode, etc. A question has an array of these.
865 * @copyright 2010 The Open University
866 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
868 class question_hint
{
869 /** @var integer The hint id. */
871 /** @var string The feedback hint to be shown. */
873 /** @var integer The corresponding text FORMAT_... type. */
878 * @param int the hint id from the database.
879 * @param string $hint The hint text
880 * @param int the corresponding text FORMAT_... type.
882 public function __construct($id, $hint, $hintformat) {
885 $this->hintformat
= $hintformat;
889 * Create a basic hint from a row loaded from the question_hints table in the database.
890 * @param object $row with $row->hint set.
891 * @return question_hint
893 public static function load_from_record($row) {
894 return new question_hint($row->id
, $row->hint
, $row->hintformat
);
898 * Adjust this display options according to the hint settings.
899 * @param question_display_options $options
901 public function adjust_display_options(question_display_options
$options) {
908 * An extension of {@link question_hint} for questions like match and multiple
909 * choice with multile answers, where there are options for whether to show the
910 * number of parts right at each stage, and to reset the wrong parts.
912 * @copyright 2010 The Open University
913 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
915 class question_hint_with_parts
extends question_hint
{
916 /** @var boolean option to show the number of sub-parts of the question that were right. */
917 public $shownumcorrect;
919 /** @var boolean option to clear the parts of the question that were wrong on retry. */
924 * @param int the hint id from the database.
925 * @param string $hint The hint text
926 * @param int the corresponding text FORMAT_... type.
927 * @param bool $shownumcorrect whether the number of right parts should be shown
928 * @param bool $clearwrong whether the wrong parts should be reset.
930 public function __construct($id, $hint, $hintformat, $shownumcorrect, $clearwrong) {
931 parent
::__construct($id, $hint, $hintformat);
932 $this->shownumcorrect
= $shownumcorrect;
933 $this->clearwrong
= $clearwrong;
937 * Create a basic hint from a row loaded from the question_hints table in the database.
938 * @param object $row with $row->hint, ->shownumcorrect and ->clearwrong set.
939 * @return question_hint_with_parts
941 public static function load_from_record($row) {
942 return new question_hint_with_parts($row->id
, $row->hint
, $row->hintformat
,
943 $row->shownumcorrect
, $row->clearwrong
);
946 public function adjust_display_options(question_display_options
$options) {
947 parent
::adjust_display_options($options);
948 if ($this->clearwrong
) {
949 $options->clearwrong
= true;
951 $options->numpartscorrect
= $this->shownumcorrect
;
957 * This question_grading_strategy interface. Used to share grading code between
958 * questions that that subclass {@link question_graded_by_strategy}.
960 * @copyright 2009 The Open University
961 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
963 interface question_grading_strategy
{
965 * Return a question answer that describes the outcome (fraction and feeback)
966 * for a particular respons.
967 * @param array $response the response.
968 * @return question_answer the answer describing the outcome.
970 public function grade(array $response);
973 * @return question_answer an answer that contains the a response that would
976 public function get_correct_answer();
981 * This interface defines the methods that a {@link question_definition} must
982 * implement if it is to be graded by the
983 * {@link question_first_matching_answer_grading_strategy}.
985 * @copyright 2009 The Open University
986 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
988 interface question_response_answer_comparer
{
989 /** @return array of {@link question_answers}. */
990 public function get_answers();
993 * @param array $response the response.
994 * @param question_answer $answer an answer.
995 * @return bool whether the response matches the answer.
997 public function compare_response_with_answer(array $response, question_answer
$answer);
1002 * This grading strategy is used by question types like shortanswer an numerical.
1003 * It gets a list of possible answers from the question, and returns the first one
1004 * that matches the given response. It returns the first answer with fraction 1.0
1005 * when asked for the correct answer.
1007 * @copyright 2009 The Open University
1008 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1010 class question_first_matching_answer_grading_strategy
implements question_grading_strategy
{
1012 * @var question_response_answer_comparer (presumably also a
1013 * {@link question_definition}) the question we are doing the grading for.
1015 protected $question;
1018 * @param question_response_answer_comparer $question (presumably also a
1019 * {@link question_definition}) the question we are doing the grading for.
1021 public function __construct(question_response_answer_comparer
$question) {
1022 $this->question
= $question;
1025 public function grade(array $response) {
1026 foreach ($this->question
->get_answers() as $aid => $answer) {
1027 if ($this->question
->compare_response_with_answer($response, $answer)) {
1035 public function get_correct_answer() {
1036 foreach ($this->question
->get_answers() as $answer) {
1037 $state = question_state
::graded_state_for_fraction($answer->fraction
);
1038 if ($state == question_state
::$gradedright) {