d98855709ada3463cd3b471d6d178f13857e9173
[moodle.git] / question / type / questionbase.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * This file defines the class {@link question_definition} and its subclasses.
20  *
21  * @package    moodlecore
22  * @subpackage questiontypes
23  * @copyright  2009 The Open University
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
28 defined('MOODLE_INTERNAL') || die();
31 /**
32  * The definition of a question of a particular type.
33  *
34  * This class is a close match to the question table in the database.
35  * Definitions of question of a particular type normally subclass one of the
36  * more specific classes {@link question_with_responses},
37  * {@link question_graded_automatically} or {@link question_information_item}.
38  *
39  * @copyright  2009 The Open University
40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41  */
42 abstract class question_definition {
43     /** @var integer id of the question in the datase, or null if this question
44      * is not in the database. */
45     public $id;
47     /** @var integer question category id. */
48     public $category;
50     /** @var integer question category id. */
51     public $contextid;
53     /** @var integer parent question id. */
54     public $parent = 0;
56     /** @var question_type the question type this question is. */
57     public $qtype;
59     /** @var string question name. */
60     public $name;
62     /** @var string question text. */
63     public $questiontext;
65     /** @var integer question test format. */
66     public $questiontextformat;
68     /** @var string question general feedback. */
69     public $generalfeedback;
71     /** @var integer question test format. */
72     public $generalfeedbackformat;
74     /** @var number what this quetsion is marked out of, by default. */
75     public $defaultmark = 1;
77     /** @var integer How many question numbers this question consumes. */
78     public $length = 1;
80     /** @var number penalty factor of this question. */
81     public $penalty = 0;
83     /** @var string unique identifier of this question. */
84     public $stamp;
86     /** @var string unique identifier of this version of this question. */
87     public $version;
89     /** @var boolean whethre this question has been deleted/hidden in the question bank. */
90     public $hidden = 0;
92     /** @var integer timestamp when this question was created. */
93     public $timecreated;
95     /** @var integer timestamp when this question was modified. */
96     public $timemodified;
98     /** @var integer userid of the use who created this question. */
99     public $createdby;
101     /** @var integer userid of the use who modified this question. */
102     public $modifiedby;
104     /** @var array of question_hints. */
105     public $hints = array();
107     /**
108      * Constructor. Normally to get a question, you call
109      * {@link question_bank::load_question()}, but questions can be created
110      * directly, for example in unit test code.
111      * @return unknown_type
112      */
113     public function __construct() {
114     }
116     /**
117      * @return the name of the question type (for example multichoice) that this
118      * question is.
119      */
120     public function get_type_name() {
121         return $this->qtype->name();
122     }
124     /**
125      * Creat the appropriate behaviour for an attempt at this quetsion,
126      * given the desired (archetypal) behaviour.
127      *
128      * This default implementation will suit most normal graded questions.
129      *
130      * If your question is of a patricular type, then it may need to do something
131      * different. For example, if your question can only be graded manually, then
132      * it should probably return a manualgraded behaviour, irrespective of
133      * what is asked for.
134      *
135      * If your question wants to do somthing especially complicated is some situations,
136      * then you may wish to return a particular behaviour related to the
137      * one asked for. For example, you migth want to return a
138      * qbehaviour_interactive_adapted_for_myqtype.
139      *
140      * @param question_attempt $qa the attempt we are creating an behaviour for.
141      * @param string $preferredbehaviour the requested type of behaviour.
142      * @return question_behaviour the new behaviour object.
143      */
144     public function make_behaviour(question_attempt $qa, $preferredbehaviour) {
145         return question_engine::make_archetypal_behaviour($preferredbehaviour, $qa);
146     }
148     /**
149      * Start a new attempt at this question, storing any information that will
150      * be needed later in the step.
151      *
152      * This is where the question can do any initialisation required on a
153      * per-attempt basis. For example, this is where the multiple choice
154      * question type randomly shuffles the choices (if that option is set).
155      *
156      * Any information about how the question has been set up for this attempt
157      * should be stored in the $step, by calling $step->set_qt_var(...).
158      *
159      * @param question_attempt_step The first step of the {@link question_attempt}
160      *      being started. Can be used to store state.
161      */
162     public function start_attempt(question_attempt_step $step) {
163     }
165     /**
166      * When an in-progress {@link question_attempt} is re-loaded from the
167      * database, this method is called so that the question can re-initialise
168      * its internal state as needed by this attempt.
169      *
170      * For example, the multiple choice question type needs to set the order
171      * of the choices to the order that was set up when start_attempt was called
172      * originally. All the information required to do this should be in the
173      * $step object, which is the first step of the question_attempt being loaded.
174      *
175      * @param question_attempt_step The first step of the {@link question_attempt}
176      *      being loaded.
177      */
178     public function apply_attempt_state(question_attempt_step $step) {
179     }
181     /**
182      * Generate a brief, plain-text, summary of this question. This is used by
183      * various reports. This should show the particular variant of the question
184      * as presented to students. For example, the calculated quetsion type would
185      * fill in the particular numbers that were presented to the student.
186      * This method will return null if such a summary is not possible, or
187      * inappropriate.
188      * @return string|null a plain text summary of this question.
189      */
190     public function get_question_summary() {
191         return $this->html_to_text($this->questiontext, $this->questiontextformat);
192     }
194     /**
195      * Some questions can return a negative mark if the student gets it wrong.
196      *
197      * This method returns the lowest mark the question can return, on the
198      * fraction scale. that is, where the maximum possible mark is 1.0.
199      *
200      * @return number minimum fraction this question will ever return.
201      */
202     public function get_min_fraction() {
203         return 0;
204     }
206     /**
207      * Given a response, rest the parts that are wrong.
208      * @param array $response a response
209      * @return array a cleaned up response with the wrong bits reset.
210      */
211     public function clear_wrong_from_response(array $response) {
212         return array();
213     }
215     /**
216      * Return the number of subparts of this response that are right.
217      * @param array $response a response
218      * @return array with two elements, the number of correct subparts, and
219      * the total number of subparts.
220      */
221     public function get_num_parts_right(array $response) {
222         return array(null, null);
223     }
225     /**
226      * @return qtype_renderer the renderer to use for outputting this question.
227      */
228     public function get_renderer(moodle_page $page) {
229         return $page->get_renderer($this->qtype->plugin_name());
230     }
232     /**
233      * What data may be included in the form submission when a student submits
234      * this question in its current state?
235      *
236      * This information is used in calls to optional_param. The parameter name
237      * has {@link question_attempt::get_field_prefix()} automatically prepended.
238      *
239      * @return array|string variable name => PARAM_... constant, or, as a special case
240      *      that should only be used in unavoidable, the constant question_attempt::USE_RAW_DATA
241      *      meaning take all the raw submitted data belonging to this question.
242      */
243     public abstract function get_expected_data();
245     /**
246      * What data would need to be submitted to get this question correct.
247      * If there is more than one correct answer, this method should just
248      * return one possibility.
249      *
250      * @return array parameter name => value.
251      */
252     public abstract function get_correct_response();
254     /**
255      * Apply {@link format_text()} to some content with appropriate settings for
256      * this question.
257      *
258      * @param string $text some content that needs to be output.
259      * @param int $format the FORMAT_... constant.
260      * @param question_attempt $qa the question attempt.
261      * @param string $component used for rewriting file area URLs.
262      * @param string $filearea used for rewriting file area URLs.
263      * @param bool $clean Whether the HTML needs to be cleaned. Generally,
264      *      parts of the question do not need to be cleaned, and student input does.
265      * @return string the text formatted for output by format_text.
266      */
267     public function format_text($text, $format, $qa, $component, $filearea, $itemid, $clean = false) {
268         $formatoptions = new stdClass();
269         $formatoptions->noclean = !$clean;
270         $formatoptions->para = false;
271         $text = $qa->rewrite_pluginfile_urls($text, $component, $filearea, $itemid);
272         return format_text($text, $format, $formatoptions);
273     }
275     /**
276      * Convert some part of the question text to plain text. This might be used,
277      * for example, by get_response_summary().
278      * @param string $text The HTML to reduce to plain text.
279      * @param int $format the FORMAT_... constant.
280      * @return string the equivalent plain text.
281      */
282     public function html_to_text($text, $format) {
283         $formatoptions = new stdClass();
284         $formatoptions->noclean = true;
285         return html_to_text(format_text($text, $format, $formatoptions), 0, false);
286     }
288     /** @return the result of applying {@link format_text()} to the question text. */
289     public function format_questiontext($qa) {
290         return $this->format_text($this->questiontext, $this->questiontextformat,
291                 $qa, 'question', 'questiontext', $this->id);
292     }
294     /** @return the result of applying {@link format_text()} to the general feedback. */
295     public function format_generalfeedback($qa) {
296         return $this->format_text($this->generalfeedback, $this->generalfeedbackformat,
297                 $qa, 'question', 'generalfeedback', $this->id);
298     }
300     /**
301      * Checks whether the users is allow to be served a particular file.
302      * @param question_attempt $qa the question attempt being displayed.
303      * @param question_display_options $options the options that control display of the question.
304      * @param string $component the name of the component we are serving files for.
305      * @param string $filearea the name of the file area.
306      * @param array $args the remaining bits of the file path.
307      * @param bool $forcedownload whether the user must be forced to download the file.
308      * @return bool true if the user can access this file.
309      */
310     public function check_file_access($qa, $options, $component, $filearea, $args, $forcedownload) {
311         if ($component == 'question' && $filearea == 'questiontext') {
312             // Question text always visible.
313             return true;
315         } else if ($component == 'question' && $filearea == 'generalfeedback') {
316             return $options->generalfeedback;
318         } else {
319             // Unrecognised component or filearea.
320             return false;
321         }
322     }
326 /**
327  * This class represents a 'question' that actually does not allow the student
328  * to respond, like the description 'question' type.
329  *
330  * @copyright  2009 The Open University
331  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
332  */
333 class question_information_item extends question_definition {
334     public function __construct() {
335         parent::__construct();
336         $this->defaultmark = 0;
337         $this->penalty = 0;
338         $this->length = 0;
339     }
341     public function make_behaviour(question_attempt $qa, $preferredbehaviour) {
342         question_engine::load_behaviour_class('informationitem');
343         return new qbehaviour_informationitem($qa, $preferredbehaviour);
344     }
346     public function get_expected_data() {
347         return array();
348     }
350     public function get_correct_response() {
351         return array();
352     }
354     public function get_question_summary() {
355         return null;
356     }
360 /**
361  * Interface that a {@link question_definition} must implement to be usable by
362  * the manual graded behaviour.
363  *
364  * @copyright  2009 The Open University
365  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
366  */
367 interface question_manually_gradable {
368     /**
369      * Used by many of the behaviours, to work out whether the student's
370      * response to the question is complete. That is, whether the question attempt
371      * should move to the COMPLETE or INCOMPLETE state.
372      *
373      * @param array $response responses, as returned by {@link question_attempt_step::get_qt_data()}.
374      * @return bool whether this response is a complete answer to this question.
375      */
376     public function is_complete_response(array $response);
378     /**
379      * Use by many of the behaviours to determine whether the student's
380      * response has changed. This is normally used to determine that a new set
381      * of responses can safely be discarded.
382      *
383      * @param array $prevresponse the responses previously recorded for this question,
384      *      as returned by {@link question_attempt_step::get_qt_data()}
385      * @param array $newresponse the new responses, in the same format.
386      * @return bool whether the two sets of responses are the same - that is
387      *      whether the new set of responses can safely be discarded.
388      */
389     public function is_same_response(array $prevresponse, array $newresponse);
391     /**
392      * Produce a plain text summary of a response.
393      * @param $response a response, as might be passed to {@link grade_response()}.
394      * @return string a plain text summary of that response, that could be used in reports.
395      */
396     public function summarise_response(array $response);
398     /**
399      * Categorise the student's response according to the categories defined by
400      * get_possible_responses.
401      * @param $response a response, as might be passed to {@link grade_response()}.
402      * @return array subpartid => {@link question_classified_response} objects.
403      *      returns an empty array if no analysis is possible.
404      */
405     public function classify_response(array $response);
409 /**
410  * This class is used in the return value from
411  * {@link question_manually_gradable::classify_response()}.
412  *
413  * @copyright  2010 The Open University
414  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
415  */
416 class question_classified_response {
417     /**
418      * @var string the classification of this response the student gave to this
419      * part of the question. Must match one of the responseclasses returned by
420      * {@link question_type::get_possible_responses()}.
421      */
422     public $responseclassid;
423     /** @var string the actual response the student gave to this part. */
424     public $response;
425     /** @var number the fraction this part of the response earned. */
426     public $fraction;
427     /**
428      * Constructor, just an easy way to set the fields.
429      * @param string $responseclassid see the field descriptions above.
430      * @param string $response see the field descriptions above.
431      * @param number $fraction see the field descriptions above.
432      */
433     public function __construct($responseclassid, $response, $fraction) {
434         $this->responseclassid = $responseclassid;
435         $this->response = $response;
436         $this->fraction = $fraction;
437     }
439     public static function no_response() {
440         return new question_classified_response(null, null, null);
441     }
445 /**
446  * Interface that a {@link question_definition} must implement to be usable by
447  * the various automatic grading behaviours.
448  *
449  * @copyright  2009 The Open University
450  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
451  */
452 interface question_automatically_gradable extends question_manually_gradable {
453     /**
454      * Use by many of the behaviours to determine whether the student
455      * has provided enough of an answer for the question to be graded automatically,
456      * or whether it must be considered aborted.
457      *
458      * @param array $response responses, as returned by {@link question_attempt_step::get_qt_data()}.
459      * @return bool whether this response can be graded.
460      */
461     public function is_gradable_response(array $response);
463     /**
464      * In situations where is_gradable_response() returns false, this method
465      * should generate a description of what the problem is.
466      * @return string the message.
467      */
468     public function get_validation_error(array $response);
470     /**
471      * Grade a response to the question, returning a fraction between get_min_fraction() and 1.0,
472      * and the corresponding state CORRECT, PARTIALLY_CORRECT or INCORRECT.
473      * @param array $response responses, as returned by {@link question_attempt_step::get_qt_data()}.
474      * @return array (number, integer) the fraction, and the state.
475      */
476     public function grade_response(array $response);
478     /**
479      * Get one of the question hints. The question_attempt is passed in case
480      * the question type wants to do something complex. For example, the
481      * multiple choice with multiple responses question type will turn off most
482      * of the hint options if the student has selected too many opitions.
483      * @param int $hintnumber Which hint to display. Indexed starting from 0
484      * @param question_attempt $qa The question_attempt.
485      */
486     public function get_hint($hintnumber, question_attempt $qa);
488     /**
489      * Generate a brief, plain-text, summary of the correct answer to this question.
490      * This is used by various reports, and can also be useful when testing.
491      * This method will return null if such a summary is not possible, or
492      * inappropriate.
493      * @return string|null a plain text summary of the right answer to this question.
494      */
495     public function get_right_answer_summary();
499 /**
500  * Interface that a {@link question_definition} must implement to be usable by
501  * the interactivecountback behaviour.
502  *
503  * @copyright  2010 The Open University
504  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
505  */
506 interface question_automatically_gradable_with_countback extends question_automatically_gradable {
507     /**
508      * Work out a final grade for this attempt, taking into account all the
509      * tries the student made.
510      * @param array $responses the response for each try. Each element of this
511      * array is a response array, as would be passed to {@link grade_response()}.
512      * There may be between 1 and $totaltries responses.
513      * @param int $totaltries The maximum number of tries allowed.
514      * @return numeric the fraction that should be awarded for this
515      * sequence of response.
516      */
517     public function compute_final_grade($responses, $totaltries);
521 /**
522  * This class represents a real question. That is, one that is not a
523  * {@link question_information_item}.
524  *
525  * @copyright  2009 The Open University
526  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
527  */
528 abstract class question_with_responses extends question_definition
529         implements question_manually_gradable {
530     public function classify_response(array $response) {
531         return array();
532     }
536 /**
537  * This class represents a question that can be graded automatically.
538  *
539  * @copyright  2009 The Open University
540  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
541  */
542 abstract class question_graded_automatically extends question_with_responses
543         implements question_automatically_gradable {
544     /** @var Some question types have the option to show the number of sub-parts correct. */
545     public $shownumcorrect = false;
547     public function is_gradable_response(array $response) {
548         return $this->is_complete_response($response);
549     }
551     public function get_right_answer_summary() {
552         $correctresponse = $this->get_correct_response();
553         if (empty($correctresponse)) {
554             return null;
555         }
556         return $this->summarise_response($correctresponse);
557     }
559     /**
560      * Check a request for access to a file belonging to a combined feedback field.
561      * @param question_attempt $qa the question attempt being displayed.
562      * @param question_display_options $options the options that control display of the question.
563      * @param string $filearea the name of the file area.
564      * @return bool whether access to the file should be allowed.
565      */
566     protected function check_combined_feedback_file_access($qa, $options, $filearea) {
567         $state = $qa->get_state();
569         if (!$state->is_finished()) {
570             $response = $qa->get_last_qt_data();
571             if (!$this->is_gradable_response($response)) {
572                 return false;
573             }
574             list($notused, $state) = $this->grade_response($response);
575         }
577         return $options->feedback && $state->get_feedback_class() . 'feedback' == $filearea;
578     }
580     /**
581      * Check a request for access to a file belonging to a hint.
582      * @param question_attempt $qa the question attempt being displayed.
583      * @param question_display_options $options the options that control display of the question.
584      * @param array $args the remaining bits of the file path.
585      * @return bool whether access to the file should be allowed.
586      */
587     protected function check_hint_file_access($qa, $options, $args) {
588         if (!$options->feedback) {
589             return false;
590         }
591         $hint = $qa->get_applicable_hint();
592         $hintid = reset($args); // itemid is hint id.
593         return $hintid == $hint->id;
594     }
596     public function get_hint($hintnumber, question_attempt $qa) {
597         if (!isset($this->hints[$hintnumber])) {
598             return null;
599         }
600         return $this->hints[$hintnumber];
601     }
603     public function format_hint(question_hint $hint, question_attempt $qa) {
604         return $this->format_text($hint->hint, $hint->hintformat, $qa, 'question', 'hint', $hint->id);
605     }
609 /**
610  * This class represents a question that can be graded automatically with
611  * countback grading in interactive mode.
612  *
613  * @copyright  2010 The Open University
614  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
615  */
616 abstract class question_graded_automatically_with_countback
617         extends question_graded_automatically
618         implements question_automatically_gradable_with_countback {
620     public function make_behaviour(question_attempt $qa, $preferredbehaviour) {
621         if ($preferredbehaviour == 'interactive') {
622             return question_engine::make_behaviour('interactivecountback', $qa, $preferredbehaviour);
623         }
624         return question_engine::make_archetypal_behaviour($preferredbehaviour, $qa);
625     }
629 /**
630  * This class represents a question that can be graded automatically by using
631  * a {@link question_grading_strategy}.
632  *
633  * @copyright  2009 The Open University
634  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
635  */
636 abstract class question_graded_by_strategy extends question_graded_automatically {
637     /** @var question_grading_strategy the strategy to use for grading. */
638     protected $gradingstrategy;
640     /** @param question_grading_strategy  $strategy the strategy to use for grading. */
641     public function __construct(question_grading_strategy $strategy) {
642         parent::__construct();
643         $this->gradingstrategy = $strategy;
644     }
646     public function get_correct_response() {
647         $answer = $this->get_correct_answer();
648         if (!$answer) {
649             return array();
650         }
652         return array('answer' => $answer->answer);
653     }
655     /**
656      * Get an answer that contains the feedback and fraction that should be
657      * awarded for this resonse.
658      * @param array $response a response.
659      * @return question_answer the matching answer.
660      */
661     public function get_matching_answer(array $response) {
662         return $this->gradingstrategy->grade($response);
663     }
665     /**
666      * @return question_answer an answer that contains the a response that would
667      *      get full marks.
668      */
669     public function get_correct_answer() {
670         return $this->gradingstrategy->get_correct_answer();
671     }
673     public function grade_response(array $response) {
674         $answer = $this->get_matching_answer($response);
675         if ($answer) {
676             return array($answer->fraction, question_state::graded_state_for_fraction($answer->fraction));
677         } else {
678             return array(0, question_state::$gradedwrong);
679         }
680     }
682     public function classify_response(array $response) {
683         if (empty($response['answer'])) {
684             return array($this->id => question_classified_response::no_response());
685         }
687         $ans = $this->get_matching_answer($response);
688         if (!$ans) {
689             return array($this->id => question_classified_response::no_response());
690         }
691         return array($this->id => new question_classified_response(
692                 $ans->id, $response['answer'], $ans->fraction));
693     }
697 /**
698  * Class to represent a question answer, loaded from the question_answers table
699  * in the database.
700  *
701  * @copyright  2009 The Open University
702  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
703  */
704 class question_answer {
705     /** @var integer the answer id. */
706     public $id;
708     /** @var string the answer. */
709     public $answer;
711     /** @var integer one of the FORMAT_... constans. */
712     public $answerformat = FORMAT_PLAIN;
714     /** @var number the fraction this answer is worth. */
715     public $fraction;
717     /** @var string the feedback for this answer. */
718     public $feedback;
720     /** @var integer one of the FORMAT_... constans. */
721     public $feedbackformat;
723     /**
724      * Constructor.
725      * @param int $id the answer.
726      * @param string $answer the answer.
727      * @param int $answerformat the format of the answer.
728      * @param number $fraction the fraction this answer is worth.
729      * @param string $feedback the feedback for this answer.
730      * @param int $feedbackformat the format of the feedback.
731      */
732     public function __construct($id, $answer, $fraction, $feedback, $feedbackformat) {
733         $this->id = $id;
734         $this->answer = $answer;
735         $this->fraction = $fraction;
736         $this->feedback = $feedback;
737         $this->feedbackformat = $feedbackformat;
738     }
742 /**
743  * Class to represent a hint associated with a question.
744  * Used by iteractive mode, etc. A question has an array of these.
745  *
746  * @copyright  2010 The Open University
747  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
748  */
749 class question_hint {
750     /** @var integer The hint id. */
751     public $id;
752     /** @var string The feedback hint to be shown. */
753     public $hint;
754     /** @var integer The corresponding text FORMAT_... type. */
755     public $hintformat;
757     /**
758      * Constructor.
759      * @param int the hint id from the database.
760      * @param string $hint The hint text
761      * @param int the corresponding text FORMAT_... type.
762      */
763     public function __construct($id, $hint, $hintformat) {
764         $this->id = $id;
765         $this->hint = $hint;
766         $this->hintformat = $hintformat;
767     }
769     /**
770      * Create a basic hint from a row loaded from the question_hints table in the database.
771      * @param object $row with $row->hint set.
772      * @return question_hint
773      */
774     public static function load_from_record($row) {
775         return new question_hint($row->id, $row->hint, $row->hintformat);
776     }
778     /**
779      * Adjust this display options according to the hint settings.
780      * @param question_display_options $options
781      */
782     public function adjust_display_options(question_display_options $options) {
783         // Do nothing.
784     }
788 /**
789  * An extension of {@link question_hint} for questions like match and multiple
790  * choice with multile answers, where there are options for whether to show the
791  * number of parts right at each stage, and to reset the wrong parts.
792  *
793  * @copyright  2010 The Open University
794  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
795  */
796 class question_hint_with_parts extends question_hint {
797     /** @var boolean option to show the number of sub-parts of the question that were right. */
798     public $shownumcorrect;
800     /** @var boolean option to clear the parts of the question that were wrong on retry. */
801     public $clearwrong;
803     /**
804      * Constructor.
805      * @param int the hint id from the database.
806      * @param string $hint The hint text
807      * @param int the corresponding text FORMAT_... type.
808      * @param bool $shownumcorrect whether the number of right parts should be shown
809      * @param bool $clearwrong whether the wrong parts should be reset.
810      */
811     public function __construct($id, $hint, $hintformat, $shownumcorrect, $clearwrong) {
812         parent::__construct($id, $hint, $hintformat);
813         $this->shownumcorrect = $shownumcorrect;
814         $this->clearwrong = $clearwrong;
815     }
817     /**
818      * Create a basic hint from a row loaded from the question_hints table in the database.
819      * @param object $row with $row->hint, ->shownumcorrect and ->clearwrong set.
820      * @return question_hint_with_parts
821      */
822     public static function load_from_record($row) {
823         return new question_hint_with_parts($row->id, $row->hint, $row->hintformat,
824                 $row->shownumcorrect, $row->clearwrong);
825     }
827     public function adjust_display_options(question_display_options $options) {
828         parent::adjust_display_options($options);
829         if ($this->clearwrong) {
830             $options->clearwrong = true;
831         }
832         $options->numpartscorrect = $this->shownumcorrect;
833     }
837 /**
838  * This question_grading_strategy interface. Used to share grading code between
839  * questions that that subclass {@link question_graded_by_strategy}.
840  *
841  * @copyright  2009 The Open University
842  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
843  */
844 interface question_grading_strategy {
845     /**
846      * Return a question answer that describes the outcome (fraction and feeback)
847      * for a particular respons.
848      * @param array $response the response.
849      * @return question_answer the answer describing the outcome.
850      */
851     public function grade(array $response);
853     /**
854      * @return question_answer an answer that contains the a response that would
855      *      get full marks.
856      */
857     public function get_correct_answer();
861 /**
862  * This interface defines the methods that a {@link question_definition} must
863  * implement if it is to be graded by the
864  * {@link question_first_matching_answer_grading_strategy}.
865  *
866  * @copyright  2009 The Open University
867  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
868  */
869 interface question_response_answer_comparer {
870     /** @return array of {@link question_answers}. */
871     public function get_answers();
873     /**
874      * @param array $response the response.
875      * @param question_answer $answer an answer.
876      * @return bool whether the response matches the answer.
877      */
878     public function compare_response_with_answer(array $response, question_answer $answer);
882 /**
883  * This grading strategy is used by question types like shortanswer an numerical.
884  * It gets a list of possible answers from the question, and returns the first one
885  * that matches the given response. It returns the first answer with fraction 1.0
886  * when asked for the correct answer.
887  *
888  * @copyright  2009 The Open University
889  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
890  */
891 class question_first_matching_answer_grading_strategy implements question_grading_strategy {
892     /**
893      * @var question_response_answer_comparer (presumably also a
894      * {@link question_definition}) the question we are doing the grading for.
895      */
896     protected $question;
898     /**
899      * @param question_response_answer_comparer $question (presumably also a
900      * {@link question_definition}) the question we are doing the grading for.
901      */
902     public function __construct(question_response_answer_comparer $question) {
903         $this->question = $question;
904     }
906     public function grade(array $response) {
907         foreach ($this->question->get_answers() as $aid => $answer) {
908             if ($this->question->compare_response_with_answer($response, $answer)) {
909                 $answer->id = $aid;
910                 return $answer;
911             }
912         }
913         return null;
914     }
916     public function get_correct_answer() {
917         foreach ($this->question->get_answers() as $answer) {
918             $state = question_state::graded_state_for_fraction($answer->fraction);
919             if ($state == question_state::$gradedright) {
920                 return $answer;
921             }
922         }
923         return null;
924     }