MDL-61837 core_question: replace tag fields on tag modal
[moodle.git] / question / type / questionbase.php
1 <?php
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/>.
17 /**
18  * This file defines the class {@link question_definition} and its subclasses.
19  *
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
27  *
28  * Other classes:
29  * - question_classified_response
30  * - question_answer
31  * - question_hint
32  *   - question_hint_with_parts
33  * - question_first_matching_answer_grading_strategy implements question_grading_strategy
34  *
35  * Other interfaces:
36  * - question_response_answer_comparer
37  *
38  * @package    moodlecore
39  * @subpackage questiontypes
40  * @copyright  2009 The Open University
41  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
42  */
45 defined('MOODLE_INTERNAL') || die();
48 /**
49  * The definition of a question of a particular type.
50  *
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}.
55  *
56  * @copyright  2009 The Open University
57  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
58  */
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. */
62     public $id;
64     /** @var integer question category id. */
65     public $category;
67     /** @var integer question context id. */
68     public $contextid;
70     /** @var integer parent question id. */
71     public $parent = 0;
73     /** @var question_type the question type this question is. */
74     public $qtype;
76     /** @var string question name. */
77     public $name;
79     /** @var string question text. */
80     public $questiontext;
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. */
95     public $length = 1;
97     /** @var number penalty factor of this question. */
98     public $penalty = 0;
100     /** @var string unique identifier of this question. */
101     public $stamp;
103     /** @var string unique identifier of this version of this question. */
104     public $version;
106     /** @var boolean whethre this question has been deleted/hidden in the question bank. */
107     public $hidden = 0;
109     /** @var integer timestamp when this question was created. */
110     public $timecreated;
112     /** @var integer timestamp when this question was modified. */
113     public $timemodified;
115     /** @var integer userid of the use who created this question. */
116     public $createdby;
118     /** @var integer userid of the use who modified this question. */
119     public $modifiedby;
121     /** @var array of question_hints. */
122     public $hints = array();
124     /**
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
129      */
130     public function __construct() {
131     }
133     /**
134      * @return the name of the question type (for example multichoice) that this
135      * question is.
136      */
137     public function get_type_name() {
138         return $this->qtype->name();
139     }
141     /**
142      * Creat the appropriate behaviour for an attempt at this quetsion,
143      * given the desired (archetypal) behaviour.
144      *
145      * This default implementation will suit most normal graded questions.
146      *
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
150      * what is asked for.
151      *
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.
156      *
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.
160      */
161     public function make_behaviour(question_attempt $qa, $preferredbehaviour) {
162         return question_engine::make_archetypal_behaviour($preferredbehaviour, $qa);
163     }
165     /**
166      * Start a new attempt at this question, storing any information that will
167      * be needed later in the step.
168      *
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).
172      *
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(...).
175      *
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.
180      */
181     public function start_attempt(question_attempt_step $step, $variant) {
182     }
184     /**
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.
188      *
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.
193      *
194      * @param question_attempt_step The first step of the {@link question_attempt}
195      *      being loaded.
196      */
197     public function apply_attempt_state(question_attempt_step $step) {
198     }
200     /**
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
206      * inappropriate.
207      * @return string|null a plain text summary of this question.
208      */
209     public function get_question_summary() {
210         return $this->html_to_text($this->questiontext, $this->questiontextformat);
211     }
213     /**
214      * @return int the number of vaiants that this question has.
215      */
216     public function get_num_variants() {
217         return 1;
218     }
220     /**
221      * @return string that can be used to seed the pseudo-random selection of a
222      *      variant.
223      */
224     public function get_variants_selection_seed() {
225         return $this->stamp;
226     }
228     /**
229      * Some questions can return a negative mark if the student gets it wrong.
230      *
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.
233      *
234      * @return float minimum fraction this question will ever return.
235      */
236     public function get_min_fraction() {
237         return 0;
238     }
240     /**
241      * Some questions can return a mark greater than the maximum.
242      *
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.
245      *
246      * @return float maximum fraction this question will ever return.
247      */
248     public function get_max_fraction() {
249         return 1;
250     }
252     /**
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.
256      */
257     public function clear_wrong_from_response(array $response) {
258         return array();
259     }
261     /**
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.
266      */
267     public function get_num_parts_right(array $response) {
268         return array(null, null);
269     }
271     /**
272      * @param moodle_page the page we are outputting to.
273      * @return qtype_renderer the renderer to use for outputting this question.
274      */
275     public function get_renderer(moodle_page $page) {
276         return $page->get_renderer($this->qtype->plugin_name());
277     }
279     /**
280      * What data may be included in the form submission when a student submits
281      * this question in its current state?
282      *
283      * This information is used in calls to optional_param. The parameter name
284      * has {@link question_attempt::get_field_prefix()} automatically prepended.
285      *
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.
289      */
290     public abstract function get_expected_data();
292     /**
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.
297      *
298      * @return array|null parameter name => value.
299      */
300     public abstract function get_correct_response();
303     /**
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.
308      *
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.
312      *
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
318      *
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.
321      *
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)
324      */
325     public function prepare_simulated_post_data($simulatedresponse) {
326         return $simulatedresponse;
327     }
329     /**
330      * Does the opposite of {@link prepare_simulated_post_data}.
331      *
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.
334      *
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.
337      *
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.
340      */
341     public function get_student_response_values_for_simulation($realresponse) {
342         return $realresponse;
343     }
345     /**
346      * Apply {@link format_text()} to some content with appropriate settings for
347      * this question.
348      *
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.
357      */
358     public function format_text($text, $format, $qa, $component, $filearea, $itemid,
359             $clean = false) {
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);
365     }
367     /**
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.
373      */
374     public function html_to_text($text, $format) {
375         return question_utils::to_plain_text($text, $format);
376     }
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);
382     }
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);
388     }
390     /**
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.
396      */
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);
401         return trim($html);
402     }
404     /**
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.
413      */
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;
422         } else {
423             // Unrecognised component or filearea.
424             return false;
425         }
426     }
430 /**
431  * This class represents a 'question' that actually does not allow the student
432  * to respond, like the description 'question' type.
433  *
434  * @copyright  2009 The Open University
435  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
436  */
437 class question_information_item extends question_definition {
438     public function __construct() {
439         parent::__construct();
440         $this->defaultmark = 0;
441         $this->penalty = 0;
442         $this->length = 0;
443     }
445     public function make_behaviour(question_attempt $qa, $preferredbehaviour) {
446         return question_engine::make_behaviour('informationitem', $qa, $preferredbehaviour);
447     }
449     public function get_expected_data() {
450         return array();
451     }
453     public function get_correct_response() {
454         return array();
455     }
457     public function get_question_summary() {
458         return null;
459     }
463 /**
464  * Interface that a {@link question_definition} must implement to be usable by
465  * the manual graded behaviour.
466  *
467  * @copyright  2009 The Open University
468  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
469  */
470 interface question_manually_gradable {
471     /**
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.
475      *
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.
479      */
480     public function is_gradable_response(array $response);
482     /**
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.
486      *
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.
490      */
491     public function is_complete_response(array $response);
493     /**
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.
497      *
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.
503      */
504     public function is_same_response(array $prevresponse, array $newresponse);
506     /**
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.
510      */
511     public function summarise_response(array $response);
513     /**
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.
519      */
520     public function classify_response(array $response);
524 /**
525  * This class is used in the return value from
526  * {@link question_manually_gradable::classify_response()}.
527  *
528  * @copyright  2010 The Open University
529  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
530  */
531 class question_classified_response {
532     /**
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()}.
536      */
537     public $responseclassid;
538     /** @var string the actual response the student gave to this part. */
539     public $response;
540     /** @var number the fraction this part of the response earned. */
541     public $fraction;
542     /**
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.
547      */
548     public function __construct($responseclassid, $response, $fraction) {
549         $this->responseclassid = $responseclassid;
550         $this->response = $response;
551         $this->fraction = $fraction;
552     }
554     public static function no_response() {
555         return new question_classified_response(null, get_string('noresponse', 'question'), null);
556     }
560 /**
561  * Interface that a {@link question_definition} must implement to be usable by
562  * the various automatic grading behaviours.
563  *
564  * @copyright  2009 The Open University
565  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
566  */
567 interface question_automatically_gradable extends question_manually_gradable {
568     /**
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.
572      */
573     public function get_validation_error(array $response);
575     /**
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.
582      */
583     public function grade_response(array $response);
585     /**
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.
592      */
593     public function get_hint($hintnumber, question_attempt $qa);
595     /**
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
599      * inappropriate.
600      * @return string|null a plain text summary of the right answer to this question.
601      */
602     public function get_right_answer_summary();
606 /**
607  * Interface that a {@link question_definition} must implement to be usable by
608  * the interactivecountback behaviour.
609  *
610  * @copyright  2010 The Open University
611  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
612  */
613 interface question_automatically_gradable_with_countback extends question_automatically_gradable {
614     /**
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.
623      */
624     public function compute_final_grade($responses, $totaltries);
628 /**
629  * This class represents a real question. That is, one that is not a
630  * {@link question_information_item}.
631  *
632  * @copyright  2009 The Open University
633  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
634  */
635 abstract class question_with_responses extends question_definition
636         implements question_manually_gradable {
637     public function classify_response(array $response) {
638         return array();
639     }
641     public function is_gradable_response(array $response) {
642         return $this->is_complete_response($response);
643     }
647 /**
648  * This class represents a question that can be graded automatically.
649  *
650  * @copyright  2009 The Open University
651  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
652  */
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)) {
661             return null;
662         }
663         return $this->summarise_response($correctresponse);
664     }
666     /**
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.
673      */
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.',
679                     DEBUG_DEVELOPER);
680             $args = array($this->id); // Fake it for now, so the rest of this method works.
681         }
683         if (!$state->is_finished()) {
684             $response = $qa->get_last_qt_data();
685             if (!$this->is_gradable_response($response)) {
686                 return false;
687             }
688             list($notused, $state) = $this->grade_response($response);
689         }
691         return $options->feedback && $state->get_feedback_class() . 'feedback' == $filearea &&
692                 $args[0] == $this->id;
693     }
695     /**
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.
701      */
702     protected function check_hint_file_access($qa, $options, $args) {
703         if (!$options->feedback) {
704             return false;
705         }
706         $hint = $qa->get_applicable_hint();
707         $hintid = reset($args); // Itemid is hint id.
708         return $hintid == $hint->id;
709     }
711     public function get_hint($hintnumber, question_attempt $qa) {
712         if (!isset($this->hints[$hintnumber])) {
713             return null;
714         }
715         return $this->hints[$hintnumber];
716     }
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);
721     }
725 /**
726  * This class represents a question that can be graded automatically with
727  * countback grading in interactive mode.
728  *
729  * @copyright  2010 The Open University
730  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
731  */
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);
740         }
741         return question_engine::make_archetypal_behaviour($preferredbehaviour, $qa);
742     }
746 /**
747  * This class represents a question that can be graded automatically by using
748  * a {@link question_grading_strategy}.
749  *
750  * @copyright  2009 The Open University
751  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
752  */
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;
761     }
763     public function get_correct_response() {
764         $answer = $this->get_correct_answer();
765         if (!$answer) {
766             return array();
767         }
769         return array('answer' => $answer->answer);
770     }
772     /**
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.
777      */
778     public function get_matching_answer(array $response) {
779         return $this->gradingstrategy->grade($response);
780     }
782     /**
783      * @return question_answer an answer that contains the a response that would
784      *      get full marks.
785      */
786     public function get_correct_answer() {
787         return $this->gradingstrategy->get_correct_answer();
788     }
790     public function grade_response(array $response) {
791         $answer = $this->get_matching_answer($response);
792         if ($answer) {
793             return array($answer->fraction,
794                     question_state::graded_state_for_fraction($answer->fraction));
795         } else {
796             return array(0, question_state::$gradedwrong);
797         }
798     }
800     public function classify_response(array $response) {
801         if (empty($response['answer'])) {
802             return array($this->id => question_classified_response::no_response());
803         }
805         $ans = $this->get_matching_answer($response);
806         if (!$ans) {
807             return array($this->id => new question_classified_response(
808                     0, $response['answer'], 0));
809         }
811         return array($this->id => new question_classified_response(
812                 $ans->id, $response['answer'], $ans->fraction));
813     }
817 /**
818  * Class to represent a question answer, loaded from the question_answers table
819  * in the database.
820  *
821  * @copyright  2009 The Open University
822  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
823  */
824 class question_answer {
825     /** @var integer the answer id. */
826     public $id;
828     /** @var string the answer. */
829     public $answer;
831     /** @var integer one of the FORMAT_... constans. */
832     public $answerformat = FORMAT_PLAIN;
834     /** @var number the fraction this answer is worth. */
835     public $fraction;
837     /** @var string the feedback for this answer. */
838     public $feedback;
840     /** @var integer one of the FORMAT_... constans. */
841     public $feedbackformat;
843     /**
844      * Constructor.
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.
850      */
851     public function __construct($id, $answer, $fraction, $feedback, $feedbackformat) {
852         $this->id = $id;
853         $this->answer = $answer;
854         $this->fraction = $fraction;
855         $this->feedback = $feedback;
856         $this->feedbackformat = $feedbackformat;
857     }
861 /**
862  * Class to represent a hint associated with a question.
863  * Used by iteractive mode, etc. A question has an array of these.
864  *
865  * @copyright  2010 The Open University
866  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
867  */
868 class question_hint {
869     /** @var integer The hint id. */
870     public $id;
871     /** @var string The feedback hint to be shown. */
872     public $hint;
873     /** @var integer The corresponding text FORMAT_... type. */
874     public $hintformat;
876     /**
877      * Constructor.
878      * @param int the hint id from the database.
879      * @param string $hint The hint text
880      * @param int the corresponding text FORMAT_... type.
881      */
882     public function __construct($id, $hint, $hintformat) {
883         $this->id = $id;
884         $this->hint = $hint;
885         $this->hintformat = $hintformat;
886     }
888     /**
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
892      */
893     public static function load_from_record($row) {
894         return new question_hint($row->id, $row->hint, $row->hintformat);
895     }
897     /**
898      * Adjust this display options according to the hint settings.
899      * @param question_display_options $options
900      */
901     public function adjust_display_options(question_display_options $options) {
902         // Do nothing.
903     }
907 /**
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.
911  *
912  * @copyright  2010 The Open University
913  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
914  */
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. */
920     public $clearwrong;
922     /**
923      * Constructor.
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.
929      */
930     public function __construct($id, $hint, $hintformat, $shownumcorrect, $clearwrong) {
931         parent::__construct($id, $hint, $hintformat);
932         $this->shownumcorrect = $shownumcorrect;
933         $this->clearwrong = $clearwrong;
934     }
936     /**
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
940      */
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);
944     }
946     public function adjust_display_options(question_display_options $options) {
947         parent::adjust_display_options($options);
948         if ($this->clearwrong) {
949             $options->clearwrong = true;
950         }
951         $options->numpartscorrect = $this->shownumcorrect;
952     }
956 /**
957  * This question_grading_strategy interface. Used to share grading code between
958  * questions that that subclass {@link question_graded_by_strategy}.
959  *
960  * @copyright  2009 The Open University
961  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
962  */
963 interface question_grading_strategy {
964     /**
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.
969      */
970     public function grade(array $response);
972     /**
973      * @return question_answer an answer that contains the a response that would
974      *      get full marks.
975      */
976     public function get_correct_answer();
980 /**
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}.
984  *
985  * @copyright  2009 The Open University
986  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
987  */
988 interface question_response_answer_comparer {
989     /** @return array of {@link question_answers}. */
990     public function get_answers();
992     /**
993      * @param array $response the response.
994      * @param question_answer $answer an answer.
995      * @return bool whether the response matches the answer.
996      */
997     public function compare_response_with_answer(array $response, question_answer $answer);
1001 /**
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.
1006  *
1007  * @copyright  2009 The Open University
1008  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1009  */
1010 class question_first_matching_answer_grading_strategy implements question_grading_strategy {
1011     /**
1012      * @var question_response_answer_comparer (presumably also a
1013      * {@link question_definition}) the question we are doing the grading for.
1014      */
1015     protected $question;
1017     /**
1018      * @param question_response_answer_comparer $question (presumably also a
1019      * {@link question_definition}) the question we are doing the grading for.
1020      */
1021     public function __construct(question_response_answer_comparer $question) {
1022         $this->question = $question;
1023     }
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)) {
1028                 $answer->id = $aid;
1029                 return $answer;
1030             }
1031         }
1032         return null;
1033     }
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) {
1039                 return $answer;
1040             }
1041         }
1042         return null;
1043     }