MDL-69823 qtype: Support core question types
[moodle.git] / question / type / questiontypebase.php
CommitLineData
f29aeb5a 1<?php
f29aeb5a
TH
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16
516cf3eb 17/**
4323d029 18 * The default questiontype class.
19 *
7764183a 20 * @package moodlecore
4323d029 21 * @subpackage questiontypes
7764183a
TH
22 * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
271e6dec 24 */
516cf3eb 25
f29aeb5a 26
a17b297d
TH
27defined('MOODLE_INTERNAL') || die();
28
d1b7e03d 29require_once($CFG->dirroot . '/question/engine/lib.php');
516cf3eb 30
f29aeb5a 31
32b0adfa 32/**
33 * This is the base class for Moodle question types.
271ffe3f 34 *
32b0adfa 35 * There are detailed comments on each method, explaining what the method is
36 * for, and the circumstances under which you might need to override it.
271ffe3f 37 *
32b0adfa 38 * Note: the questiontype API should NOT be considered stable yet. Very few
22cebed5 39 * question types have been produced yet, so we do not yet know all the places
271ffe3f 40 * where the current API is insufficient. I would rather learn from the
32b0adfa 41 * experiences of the first few question type implementors, and improve the
42 * interface to meet their needs, rather the freeze the API prematurely and
43 * condem everyone to working round a clunky interface for ever afterwards.
271e6dec 44 *
7764183a
TH
45 * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
46 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
32b0adfa 47 */
d1b7e03d 48class question_type {
f29aeb5a 49 protected $fileoptions = array(
f383a58a 50 'subdirs' => true,
f29aeb5a
TH
51 'maxfiles' => -1,
52 'maxbytes' => 0,
53 );
516cf3eb 54
d1b7e03d 55 public function __construct() {
869309b8 56 }
57
4995b9c1 58 /**
d1b7e03d 59 * @return string the name of this question type.
869309b8 60 */
d1b7e03d
TH
61 public function name() {
62 return substr(get_class($this), 6);
a2156789 63 }
271ffe3f 64
f29aeb5a
TH
65 /**
66 * @return string the full frankenstyle name for this plugin.
67 */
68 public function plugin_name() {
69 return get_class($this);
70 }
71
72 /**
73 * @return string the name of this question type in the user's language.
74 * You should not need to override this method, the default behaviour should be fine.
75 */
76 public function local_name() {
0b94d6bf 77 return get_string('pluginname', $this->plugin_name());
f29aeb5a
TH
78 }
79
869309b8 80 /**
81 * The name this question should appear as in the create new question
f29aeb5a
TH
82 * dropdown. Override this method to return false if you don't want your
83 * question type to be createable, for example if it is an abstract base type,
84 * otherwise, you should not need to override this method.
869309b8 85 *
86 * @return mixed the desired string, or false to hide this question type in the menu.
87 */
d1b7e03d 88 public function menu_name() {
f29aeb5a
TH
89 return $this->local_name();
90 }
91
f29aeb5a 92 /**
f7970e3c 93 * @return bool override this to return false if this is not really a
f29aeb5a
TH
94 * question type, for example the description question type is not
95 * really a question type.
96 */
97 public function is_real_question_type() {
98 return true;
b974f947 99 }
100
a2156789 101 /**
f7970e3c 102 * @return bool true if this question type sometimes requires manual grading.
a2156789 103 */
d1b7e03d 104 public function is_manual_graded() {
a2156789 105 return false;
106 }
107
f24493ec 108 /**
109 * @param object $question a question of this type.
110 * @param string $otherquestionsinuse comma-separate list of other question ids in this attempt.
f7970e3c 111 * @return bool true if a particular instance of this question requires manual grading.
f24493ec 112 */
d1b7e03d 113 public function is_question_manual_graded($question, $otherquestionsinuse) {
f24493ec 114 return $this->is_manual_graded();
115 }
116
869309b8 117 /**
f7970e3c 118 * @return bool true if this question type can be used by the random question type.
869309b8 119 */
d1b7e03d
TH
120 public function is_usable_by_random() {
121 return true;
869309b8 122 }
123
a2156789 124 /**
d1b7e03d
TH
125 * Whether this question type can perform a frequency analysis of student
126 * responses.
127 *
128 * If this method returns true, you must implement the get_possible_responses
129 * method, and the question_definition class must implement the
130 * classify_response method.
131 *
562684e3 132 * @return bool whether this report can analyse all the student responses
d1b7e03d 133 * for things like the quiz statistics report.
a2156789 134 */
d1b7e03d
TH
135 public function can_analyse_responses() {
136 // This works in most cases.
137 return !$this->is_manual_graded();
a2156789 138 }
139
869309b8 140 /**
d1b7e03d
TH
141 * @return whether the question_answers.answer field needs to have
142 * restore_decode_content_links_worker called on it.
869309b8 143 */
d1b7e03d 144 public function has_html_answers() {
869309b8 145 return false;
146 }
d001dac7 147
295043c2 148 /**
149 * If your question type has a table that extends the question table, and
150 * you want the base class to automatically save, backup and restore the extra fields,
151 * override this method to return an array wherer the first element is the table name,
152 * and the subsequent entries are the column names (apart from id and questionid).
153 *
154 * @return mixed array as above, or null to tell the base class to do nothing.
155 */
d1b7e03d 156 public function extra_question_fields() {
295043c2 157 return null;
158 }
159
d001dac7 160 /**
eaeb6b51
TH
161 * If you use extra_question_fields, overload this function to return question id field name
162 * in case you table use another name for this column
163 */
56565037 164 public function questionid_column_name() {
d001dac7 165 return 'questionid';
166 }
167
295043c2 168 /**
169 * If your question type has a table that extends the question_answers table,
170 * make this method return an array wherer the first element is the table name,
171 * and the subsequent entries are the column names (apart from id and answerid).
172 *
173 * @return mixed array as above, or null to tell the base class to do nothing.
174 */
56565037 175 public function extra_answer_fields() {
6b5f24d3
TH
176 return null;
177 }
178
179 /**
180 * If the quetsion type uses files in responses, then this method should
181 * return an array of all the response variables that might have corresponding
182 * files. For example, the essay qtype returns array('attachments', 'answers').
183 *
184 * @return array response variable names that may have associated files.
185 */
186 public function response_file_areas() {
187 return array();
188 }
295043c2 189
36703ed7 190 /**
191 * Return an instance of the question editing form definition. This looks for a
192 * class called edit_{$this->name()}_question_form in the file
f29aeb5a 193 * question/type/{$this->name()}/edit_{$this->name()}_question_form.php
36703ed7 194 * and if it exists returns an instance of it.
195 *
196 * @param string $submiturl passed on to the constructor call.
197 * @return object an instance of the form definition, or null if one could not be found.
198 */
eaeb6b51
TH
199 public function create_editing_form($submiturl, $question, $category,
200 $contexts, $formeditable) {
36703ed7 201 global $CFG;
1fa39364
TH
202 require_once($CFG->dirroot . '/question/type/edit_question_form.php');
203 $definitionfile = $CFG->dirroot . '/question/type/' . $this->name() .
eaeb6b51 204 '/edit_' . $this->name() . '_form.php';
1fa39364
TH
205 if (!is_readable($definitionfile) || !is_file($definitionfile)) {
206 throw new coding_exception($this->plugin_name() .
afe24f85
TH
207 ' is missing the definition of its editing formin file ' .
208 $definitionfile . '.');
36703ed7 209 }
1fa39364 210 require_once($definitionfile);
6e34cd29 211 $classname = $this->plugin_name() . '_edit_form';
36703ed7 212 if (!class_exists($classname)) {
1fa39364
TH
213 throw new coding_exception($this->plugin_name() .
214 ' does not define the class ' . $this->plugin_name() .
215 '_edit_form.');
36703ed7 216 }
271e6dec 217 return new $classname($submiturl, $question, $category, $contexts, $formeditable);
36703ed7 218 }
219
99ba746d 220 /**
221 * @return string the full path of the folder this plugin's files live in.
222 */
d1b7e03d 223 public function plugin_dir() {
99ba746d 224 global $CFG;
225 return $CFG->dirroot . '/question/type/' . $this->name();
226 }
227
228 /**
229 * @return string the URL of the folder this plugin's files live in.
230 */
d1b7e03d 231 public function plugin_baseurl() {
99ba746d 232 global $CFG;
233 return $CFG->wwwroot . '/question/type/' . $this->name();
234 }
235
c9491626
TH
236 /**
237 * Get extra actions for a question of this type to add to the question bank edit menu.
238 *
239 * This method is called if the {@link edit_menu_column} is being used in the
240 * question bank, which it is by default since Moodle 3.8. If applicable for
241 * your question type, you can return arn array of {@link action_menu_link}s.
242 * These will be added at the end of the Edit menu for this question.
243 *
244 * The $question object passed in will have a hard-to-predict set of fields,
245 * because the fields present depend on which columns are included in the
246 * question bank view. However, you can rely on 'id', 'createdby',
247 * 'contextid', 'hidden' and 'category' (id) being present, and so you
248 * can call question_has_capability_on without causing performance problems.
249 *
250 * @param stdClass $question the available information about the particular question the action is for.
251 * @return action_menu_link[] any actions you want to add to the Edit menu for this question.
252 */
253 public function get_extra_question_bank_actions(stdClass $question): array {
254 return [];
255 }
256
7b41a4a9 257 /**
258 * This method should be overriden if you want to include a special heading or some other
259 * html on a question editing page besides the question editing form.
260 *
261 * @param question_edit_form $mform a child of question_edit_form
262 * @param object $question
263 * @param string $wizardnow is '' for first page.
264 */
f29aeb5a
TH
265 public function display_question_editing_page($mform, $question, $wizardnow) {
266 global $OUTPUT;
267 $heading = $this->get_heading(empty($question->id));
0b94d6bf 268 echo $OUTPUT->heading_with_help($heading, 'pluginname', $this->plugin_name());
9ab75b2b 269 $mform->display();
270 }
271e6dec 271
9ab75b2b 272 /**
eaeb6b51
TH
273 * Method called by display_question_editing_page and by question.php to get
274 * heading for breadcrumbs.
271e6dec 275 *
d1b7e03d 276 * @return string the heading
9ab75b2b 277 */
eaeb6b51 278 public function get_heading($adding = false) {
f29aeb5a 279 if ($adding) {
226b3124 280 $string = 'pluginnameadding';
226b3124
TH
281 } else {
282 $string = 'pluginnameediting';
c2f8c4be 283 }
0b94d6bf 284 return get_string($string, $this->plugin_name());
d1b7e03d
TH
285 }
286
287 /**
288 * Set any missing settings for this question to the default values. This is
289 * called before displaying the question editing form.
290 *
291 * @param object $questiondata the question data, loaded from the databsae,
292 * or more likely a newly created question object that is only partially
293 * initialised.
294 */
295 public function set_default_options($questiondata) {
7b41a4a9 296 }
297
516cf3eb 298 /**
eaeb6b51
TH
299 * Saves (creates or updates) a question.
300 *
301 * Given some question info and some data about the answers
302 * this function parses, organises and saves the question
303 * It is used by {@link question.php} when saving new data from
304 * a form, and also by {@link import.php} when importing questions
305 * This function in turn calls {@link save_question_options}
306 * to save question-type specific data.
307 *
308 * Whether we are saving a new question or updating an existing one can be
309 * determined by testing !empty($question->id). If it is not empty, we are updating.
310 *
311 * The question will be saved in category $form->category.
312 *
313 * @param object $question the question object which should be updated. For a
314 * new question will be mostly empty.
315 * @param object $form the object containing the information to save, as if
316 * from the question editing form.
317 * @param object $course not really used any more.
318 * @return object On success, return the new question object. On failure,
319 * return an object as follows. If the error object has an errors field,
320 * display that as an error message. Otherwise, the editing form will be
321 * redisplayed with validation errors, from validation_errors field, which
322 * is itself an object, shown next to the form fields. (I don't think this
323 * is accurate any more.)
324 */
c7df5006 325 public function save_question($question, $form) {
2bfb8d4a 326 global $USER, $DB;
f29aeb5a 327
2bfb8d4a 328 // The actual update/insert done with multiple DB access, so we do it in a transaction.
3ab494b1
PEK
329 $transaction = $DB->start_delegated_transaction ();
330
f29aeb5a
TH
331 list($question->category) = explode(',', $form->category);
332 $context = $this->get_context_by_category_id($question->category);
fe6ce234 333
516cf3eb 334 // This default implementation is suitable for most
335 // question types.
271ffe3f 336
3d9645ae 337 // First, save the basic question itself.
24e8b9b6 338 $question->name = trim($form->name);
24e8b9b6 339 $question->parent = isset($form->parent) ? $form->parent : 0;
516cf3eb 340 $question->length = $this->actual_number_of_questions($question);
341 $question->penalty = isset($form->penalty) ? $form->penalty : 0;
342
ca4f7f61
DW
343 // The trim call below has the effect of casting any strange values received,
344 // like null or false, to an appropriate string, so we only need to test for
345 // missing values. Be careful not to break the value '0' here.
346 if (!isset($form->questiontext['text'])) {
f29aeb5a 347 $question->questiontext = '';
516cf3eb 348 } else {
0e35ba6f 349 $question->questiontext = trim($form->questiontext['text']);
516cf3eb 350 }
eaeb6b51
TH
351 $question->questiontextformat = !empty($form->questiontext['format']) ?
352 $form->questiontext['format'] : 0;
516cf3eb 353
f29aeb5a 354 if (empty($form->generalfeedback['text'])) {
a4514d91 355 $question->generalfeedback = '';
1b8a7434 356 } else {
f29aeb5a 357 $question->generalfeedback = trim($form->generalfeedback['text']);
1b8a7434 358 }
eaeb6b51
TH
359 $question->generalfeedbackformat = !empty($form->generalfeedback['format']) ?
360 $form->generalfeedback['format'] : 0;
1b8a7434 361
1f17e41e 362 if ($question->name === '') {
f29aeb5a 363 $question->name = shorten_text(strip_tags($form->questiontext['text']), 15);
1f17e41e 364 if ($question->name === '') {
516cf3eb 365 $question->name = '-';
366 }
367 }
368
369 if ($question->penalty > 1 or $question->penalty < 0) {
5e8a85aa 370 $question->errors['penalty'] = get_string('invalidpenalty', 'question');
516cf3eb 371 }
372
d1b7e03d
TH
373 if (isset($form->defaultmark)) {
374 $question->defaultmark = $form->defaultmark;
516cf3eb 375 }
376
2569fb5d
TH
377 if (isset($form->idnumber)) {
378 if ((string) $form->idnumber === '') {
379 $question->idnumber = null;
6189fda4 380 } else {
2569fb5d
TH
381 // While this check already exists in the form validation,
382 // this is a backstop preventing unnecessary errors.
383 // Only set the idnumber if it has changed and will not cause a unique index violation.
384 if (strpos($form->category, ',') !== false) {
385 list($category, $categorycontextid) = explode(',', $form->category);
386 } else {
387 $category = $form->category;
388 }
389 if (!$DB->record_exists('question',
390 ['idnumber' => $form->idnumber, 'category' => $category])) {
391 $question->idnumber = $form->idnumber;
392 }
6189fda4
JB
393 }
394 }
395
f29aeb5a 396 // If the question is new, create it.
93e435b9 397 $newquestion = false;
f29aeb5a 398 if (empty($question->id)) {
3d9645ae 399 // Set the unique code.
cbe20043 400 $question->stamp = make_unique_id_code();
271e6dec 401 $question->createdby = $USER->id;
402 $question->timecreated = time();
f29aeb5a 403 $question->id = $DB->insert_record('question', $question);
93e435b9 404 $newquestion = true;
516cf3eb 405 }
406
f29aeb5a
TH
407 // Now, whether we are updating a existing question, or creating a new
408 // one, we have to do the files processing and update the record.
3d9645ae 409 // Question already exists, update.
f29aeb5a
TH
410 $question->modifiedby = $USER->id;
411 $question->timemodified = time();
412
413 if (!empty($question->questiontext) && !empty($form->questiontext['itemid'])) {
eaeb6b51
TH
414 $question->questiontext = file_save_draft_area_files($form->questiontext['itemid'],
415 $context->id, 'question', 'questiontext', (int)$question->id,
416 $this->fileoptions, $question->questiontext);
f29aeb5a
TH
417 }
418 if (!empty($question->generalfeedback) && !empty($form->generalfeedback['itemid'])) {
eaeb6b51
TH
419 $question->generalfeedback = file_save_draft_area_files(
420 $form->generalfeedback['itemid'], $context->id,
421 'question', 'generalfeedback', (int)$question->id,
422 $this->fileoptions, $question->generalfeedback);
f29aeb5a
TH
423 }
424 $DB->update_record('question', $question);
425
3d9645ae 426 // Now to save all the answers and type-specific options.
6459b8fc 427 $form->id = $question->id;
428 $form->qtype = $question->qtype;
516cf3eb 429 $form->category = $question->category;
6459b8fc 430 $form->questiontext = $question->questiontext;
f29aeb5a 431 $form->questiontextformat = $question->questiontextformat;
3d9645ae 432 // Current context.
f29aeb5a 433 $form->context = $context;
516cf3eb 434
435 $result = $this->save_question_options($form);
436
437 if (!empty($result->error)) {
f29aeb5a 438 print_error($result->error);
516cf3eb 439 }
440
441 if (!empty($result->notice)) {
f4fe3968 442 notice($result->notice, "question.php?id={$question->id}");
516cf3eb 443 }
444
445 if (!empty($result->noticeyesno)) {
eaeb6b51
TH
446 throw new coding_exception(
447 '$result->noticeyesno no longer supported in save_question.');
516cf3eb 448 }
449
3d9645ae 450 // Give the question a unique version stamp determined by question_hash().
eaeb6b51
TH
451 $DB->set_field('question', 'version', question_hash($question),
452 array('id' => $question->id));
cbe20043 453
3ab494b1
PEK
454 if ($newquestion) {
455 // Log the creation of this question.
456 $event = \core\event\question_created::create_from_question_instance($question, $context);
457 $event->trigger();
458 } else {
459 // Log the update of this question.
460 $event = \core\event\question_updated::create_from_question_instance($question, $context);
461 $event->trigger();
462 }
463
c689726d 464 $transaction->allow_commit();
3ab494b1 465
516cf3eb 466 return $question;
467 }
271ffe3f 468
516cf3eb 469 /**
d1b7e03d
TH
470 * Saves question-type specific options
471 *
472 * This is called by {@link save_question()} to save the question-type specific data
f0c6c181 473 * @return object $result->error or $result->notice
d1b7e03d
TH
474 * @param object $question This holds the information from the editing form,
475 * it is not a standard question object.
476 */
477 public function save_question_options($question) {
f29aeb5a 478 global $DB;
eaeb6b51 479 $extraquestionfields = $this->extra_question_fields();
295043c2 480
eaeb6b51
TH
481 if (is_array($extraquestionfields)) {
482 $question_extension_table = array_shift($extraquestionfields);
271e6dec 483
295043c2 484 $function = 'update_record';
d001dac7 485 $questionidcolname = $this->questionid_column_name();
eaeb6b51
TH
486 $options = $DB->get_record($question_extension_table,
487 array($questionidcolname => $question->id));
295043c2 488 if (!$options) {
489 $function = 'insert_record';
0ff4bd08 490 $options = new stdClass();
d001dac7 491 $options->$questionidcolname = $question->id;
295043c2 492 }
eaeb6b51 493 foreach ($extraquestionfields as $field) {
a8e577de 494 if (property_exists($question, $field)) {
8d54191d 495 $options->$field = $question->$field;
295043c2 496 }
295043c2 497 }
271e6dec 498
8d54191d 499 $DB->{$function}($question_extension_table, $options);
295043c2 500 }
f0c6c181 501 }
295043c2 502
f0c6c181
OS
503 /**
504 * Save the answers, with any extra data.
505 *
506 * Questions that use answers will call it from {@link save_question_options()}.
507 * @param object $question This holds the information from the editing form,
508 * it is not a standard question object.
509 * @return object $result->error or $result->notice
510 */
511 public function save_question_answers($question) {
512 global $DB;
513
514 $context = $question->context;
515 $oldanswers = $DB->get_records('question_answers',
516 array('question' => $question->id), 'id ASC');
517
518 // We need separate arrays for answers and extra answer data, so no JOINS there.
eaeb6b51 519 $extraanswerfields = $this->extra_answer_fields();
f0c6c181
OS
520 $isextraanswerfields = is_array($extraanswerfields);
521 $extraanswertable = '';
522 $oldanswerextras = array();
523 if ($isextraanswerfields) {
524 $extraanswertable = array_shift($extraanswerfields);
525 if (!empty($oldanswers)) {
526 $oldanswerextras = $DB->get_records_sql("SELECT * FROM {{$extraanswertable}} WHERE " .
527 'answerid IN (SELECT id FROM {question_answers} WHERE question = ' . $question->id . ')' );
528 }
529 }
530
531 // Insert all the new answers.
532 foreach ($question->answer as $key => $answerdata) {
533 // Check for, and ignore, completely blank answer from the form.
534 if ($this->is_answer_empty($question, $key)) {
535 continue;
536 }
537
538 // Update an existing answer if possible.
539 $answer = array_shift($oldanswers);
540 if (!$answer) {
541 $answer = new stdClass();
542 $answer->question = $question->id;
543 $answer->answer = '';
544 $answer->feedback = '';
545 $answer->id = $DB->insert_record('question_answers', $answer);
546 }
547
548 $answer = $this->fill_answer_fields($answer, $question, $key, $context);
549 $DB->update_record('question_answers', $answer);
550
551 if ($isextraanswerfields) {
552 // Check, if this answer contains some extra field data.
553 if ($this->is_extra_answer_fields_empty($question, $key)) {
554 continue;
555 }
556
557 $answerextra = array_shift($oldanswerextras);
558 if (!$answerextra) {
559 $answerextra = new stdClass();
560 $answerextra->answerid = $answer->id;
561 // Avoid looking for correct default for any possible DB field type
562 // by setting real values.
563 $answerextra = $this->fill_extra_answer_fields($answerextra, $question, $key, $context, $extraanswerfields);
564 $answerextra->id = $DB->insert_record($extraanswertable, $answerextra);
565 } else {
566 // Update answerid, as record may be reused from another answer.
567 $answerextra->answerid = $answer->id;
568 $answerextra = $this->fill_extra_answer_fields($answerextra, $question, $key, $context, $extraanswerfields);
569 $DB->update_record($extraanswertable, $answerextra);
570 }
571 }
572 }
573
574 if ($isextraanswerfields) {
575 // Delete any left over extra answer fields records.
576 $oldanswerextraids = array();
577 foreach ($oldanswerextras as $oldextra) {
578 $oldanswerextraids[] = $oldextra->id;
579 }
580 $DB->delete_records_list($extraanswertable, 'id', $oldanswerextraids);
581 }
582
583 // Delete any left over old answer records.
584 $fs = get_file_storage();
585 foreach ($oldanswers as $oldanswer) {
586 $fs->delete_area_files($context->id, 'question', 'answerfeedback', $oldanswer->id);
587 $DB->delete_records('question_answers', array('id' => $oldanswer->id));
588 }
589 }
590
591 /**
592 * Returns true is answer with the $key is empty in the question data and should not be saved in DB.
593 *
594 * The questions using question_answers table may want to overload this. Default code will work
595 * for shortanswer and similar question types.
596 * @param object $questiondata This holds the information from the question editing form or import.
597 * @param int $key A key of the answer in question.
598 * @return bool True if answer shouldn't be saved in DB.
599 */
600 protected function is_answer_empty($questiondata, $key) {
601 return trim($questiondata->answer[$key]) == '' && $questiondata->fraction[$key] == 0 &&
602 html_is_blank($questiondata->feedback[$key]['text']);
603 }
604
605 /**
606 * Return $answer, filling necessary fields for the question_answers table.
607 *
608 * The questions using question_answers table may want to overload this. Default code will work
609 * for shortanswer and similar question types.
610 * @param stdClass $answer Object to save data.
611 * @param object $questiondata This holds the information from the question editing form or import.
612 * @param int $key A key of the answer in question.
613 * @param object $context needed for working with files.
614 * @return $answer answer with filled data.
615 */
616 protected function fill_answer_fields($answer, $questiondata, $key, $context) {
617 $answer->answer = $questiondata->answer[$key];
618 $answer->fraction = $questiondata->fraction[$key];
619 $answer->feedback = $this->import_or_save_files($questiondata->feedback[$key],
620 $context, 'question', 'answerfeedback', $answer->id);
621 $answer->feedbackformat = $questiondata->feedback[$key]['format'];
622 return $answer;
623 }
624
625 /**
96eead3f 626 * Returns true if extra answer fields for answer with the $key is empty
f0c6c181
OS
627 * in the question data and should not be saved in DB.
628 *
629 * Questions where extra answer fields are optional will want to overload this.
630 * @param object $questiondata This holds the information from the question editing form or import.
631 * @param int $key A key of the answer in question.
632 * @return bool True if extra answer data shouldn't be saved in DB.
633 */
634 protected function is_extra_answer_fields_empty($questiondata, $key) {
635 // No extra answer data in base class.
636 return true;
637 }
638
639 /**
640 * Return $answerextra, filling necessary fields for the extra answer fields table.
641 *
642 * The questions may want to overload it to save files or do other data processing.
643 * @param stdClass $answerextra Object to save data.
644 * @param object $questiondata This holds the information from the question editing form or import.
645 * @param int $key A key of the answer in question.
646 * @param object $context needed for working with files.
647 * @param array $extraanswerfields extra answer fields (without table name).
648 * @return $answer answerextra with filled data.
649 */
650 protected function fill_extra_answer_fields($answerextra, $questiondata, $key, $context, $extraanswerfields) {
651 foreach ($extraanswerfields as $field) {
652 // The $questiondata->$field[$key] won't work in PHP, break it down to two strings of code.
653 $fieldarray = $questiondata->$field;
654 $answerextra->$field = $fieldarray[$key];
655 }
656 return $answerextra;
516cf3eb 657 }
658
d1b7e03d 659 public function save_hints($formdata, $withparts = false) {
f29aeb5a 660 global $DB;
7a719748
TH
661 $context = $formdata->context;
662
e5060e22
JP
663 $oldhints = $DB->get_records('question_hints',
664 array('questionid' => $formdata->id), 'id ASC');
295043c2 665
295043c2 666
0b287dd2 667 $numhints = $this->count_hints_on_form($formdata, $withparts);
d1b7e03d
TH
668
669 for ($i = 0; $i < $numhints; $i += 1) {
7a719748
TH
670 if (html_is_blank($formdata->hint[$i]['text'])) {
671 $formdata->hint[$i]['text'] = '';
d1b7e03d
TH
672 }
673
674 if ($withparts) {
7a719748
TH
675 $clearwrong = !empty($formdata->hintclearwrong[$i]);
676 $shownumcorrect = !empty($formdata->hintshownumcorrect[$i]);
d1b7e03d
TH
677 }
678
0b287dd2 679 if ($this->is_hint_empty_in_form_data($formdata, $i, $withparts)) {
d1b7e03d
TH
680 continue;
681 }
682
f3ca24e4 683 // Update an existing hint if possible.
7a719748
TH
684 $hint = array_shift($oldhints);
685 if (!$hint) {
686 $hint = new stdClass();
687 $hint->questionid = $formdata->id;
688 $hint->hint = '';
689 $hint->id = $DB->insert_record('question_hints', $hint);
690 }
691
7a719748
TH
692 $hint->hint = $this->import_or_save_files($formdata->hint[$i],
693 $context, 'question', 'hint', $hint->id);
694 $hint->hintformat = $formdata->hint[$i]['format'];
695 if ($withparts) {
696 $hint->clearwrong = $clearwrong;
697 $hint->shownumcorrect = $shownumcorrect;
698 }
0b287dd2 699 $hint->options = $this->save_hint_options($formdata, $i, $withparts);
7a719748
TH
700 $DB->update_record('question_hints', $hint);
701 }
702
703 // Delete any remaining old hints.
704 $fs = get_file_storage();
c73c9836 705 foreach ($oldhints as $oldhint) {
7a719748
TH
706 $fs->delete_area_files($context->id, 'question', 'hint', $oldhint->id);
707 $DB->delete_records('question_hints', array('id' => $oldhint->id));
d1b7e03d
TH
708 }
709 }
710
0b287dd2
OS
711 /**
712 * Count number of hints on the form.
713 * Overload if you use custom hint controls.
714 * @param object $formdata the data from the form.
715 * @param bool $withparts whether to take into account clearwrong and shownumcorrect options.
716 * @return int count of hints on the form.
717 */
718 protected function count_hints_on_form($formdata, $withparts) {
719 if (!empty($formdata->hint)) {
720 $numhints = max(array_keys($formdata->hint)) + 1;
721 } else {
722 $numhints = 0;
723 }
724
725 if ($withparts) {
726 if (!empty($formdata->hintclearwrong)) {
727 $numclears = max(array_keys($formdata->hintclearwrong)) + 1;
728 } else {
729 $numclears = 0;
730 }
731 if (!empty($formdata->hintshownumcorrect)) {
732 $numshows = max(array_keys($formdata->hintshownumcorrect)) + 1;
733 } else {
734 $numshows = 0;
735 }
736 $numhints = max($numhints, $numclears, $numshows);
737 }
738 return $numhints;
739 }
740
741 /**
742 * Determine if the hint with specified number is not empty and should be saved.
743 * Overload if you use custom hint controls.
744 * @param object $formdata the data from the form.
745 * @param int $number number of hint under question.
746 * @param bool $withparts whether to take into account clearwrong and shownumcorrect options.
747 * @return bool is this particular hint data empty.
748 */
749 protected function is_hint_empty_in_form_data($formdata, $number, $withparts) {
750 if ($withparts) {
751 return empty($formdata->hint[$number]['text']) && empty($formdata->hintclearwrong[$number]) &&
752 empty($formdata->hintshownumcorrect[$number]);
753 } else {
754 return empty($formdata->hint[$number]['text']);
755 }
756 }
757
758 /**
759 * Save additional question type data into the hint optional field.
760 * Overload if you use custom hint information.
761 * @param object $formdata the data from the form.
762 * @param int $number number of hint to get options from.
763 * @param bool $withparts whether question have parts.
764 * @return string value to save into the options field of question_hints table.
765 */
766 protected function save_hint_options($formdata, $number, $withparts) {
767 return null; // By default, options field is unused.
768 }
769
1c2ed7c5
TH
770 /**
771 * Can be used to {@link save_question_options()} to transfer the combined
772 * feedback fields from $formdata to $options.
773 * @param object $options the $question->options object being built.
774 * @param object $formdata the data from the form.
775 * @param object $context the context the quetsion is being saved into.
f7970e3c 776 * @param bool $withparts whether $options->shownumcorrect should be set.
1c2ed7c5 777 */
eaeb6b51
TH
778 protected function save_combined_feedback_helper($options, $formdata,
779 $context, $withparts = false) {
1c2ed7c5
TH
780 $options->correctfeedback = $this->import_or_save_files($formdata->correctfeedback,
781 $context, 'question', 'correctfeedback', $formdata->id);
782 $options->correctfeedbackformat = $formdata->correctfeedback['format'];
eaeb6b51
TH
783
784 $options->partiallycorrectfeedback = $this->import_or_save_files(
785 $formdata->partiallycorrectfeedback,
1c2ed7c5
TH
786 $context, 'question', 'partiallycorrectfeedback', $formdata->id);
787 $options->partiallycorrectfeedbackformat = $formdata->partiallycorrectfeedback['format'];
eaeb6b51 788
1c2ed7c5
TH
789 $options->incorrectfeedback = $this->import_or_save_files($formdata->incorrectfeedback,
790 $context, 'question', 'incorrectfeedback', $formdata->id);
791 $options->incorrectfeedbackformat = $formdata->incorrectfeedback['format'];
792
793 if ($withparts) {
794 $options->shownumcorrect = !empty($formdata->shownumcorrect);
795 }
796
797 return $options;
798 }
799
d1b7e03d
TH
800 /**
801 * Loads the question type specific options for the question.
802 *
803 * This function loads any question type specific options for the
804 * question from the database into the question object. This information
805 * is placed in the $question->options field. A question type is
806 * free, however, to decide on a internal structure of the options field.
807 * @return bool Indicates success or failure.
808 * @param object $question The question object for the question. This object
809 * should be updated to include the question type
810 * specific information (it is passed by reference).
811 */
812 public function get_question_options($question) {
f29aeb5a
TH
813 global $CFG, $DB, $OUTPUT;
814
815 if (!isset($question->options)) {
816 $question->options = new stdClass();
817 }
d1b7e03d 818
eaeb6b51
TH
819 $extraquestionfields = $this->extra_question_fields();
820 if (is_array($extraquestionfields)) {
821 $question_extension_table = array_shift($extraquestionfields);
822 $extra_data = $DB->get_record($question_extension_table,
823 array($this->questionid_column_name() => $question->id),
824 implode(', ', $extraquestionfields));
295043c2 825 if ($extra_data) {
eaeb6b51 826 foreach ($extraquestionfields as $field) {
295043c2 827 $question->options->$field = $extra_data->$field;
828 }
829 } else {
eaeb6b51
TH
830 echo $OUTPUT->notification('Failed to load question options from the table ' .
831 $question_extension_table . ' for questionid ' . $question->id);
295043c2 832 return false;
833 }
834 }
835
eaeb6b51
TH
836 $extraanswerfields = $this->extra_answer_fields();
837 if (is_array($extraanswerfields)) {
62766728
OS
838 $answerextensiontable = array_shift($extraanswerfields);
839 // Use LEFT JOIN in case not every answer has extra data.
f29aeb5a 840 $question->options->answers = $DB->get_records_sql("
62766728
OS
841 SELECT qa.*, qax." . implode(', qax.', $extraanswerfields) . '
842 FROM {question_answers} qa ' . "
843 LEFT JOIN {{$answerextensiontable}} qax ON qa.id = qax.answerid
844 WHERE qa.question = ?
da8cd9f4 845 ORDER BY qa.id", array($question->id));
295043c2 846 if (!$question->options->answers) {
eaeb6b51 847 echo $OUTPUT->notification('Failed to load question answers from the table ' .
62766728 848 $answerextensiontable . 'for questionid ' . $question->id);
295043c2 849 return false;
850 }
851 } else {
eaeb6b51
TH
852 // Don't check for success or failure because some question types do
853 // not use the answers table.
854 $question->options->answers = $DB->get_records('question_answers',
855 array('question' => $question->id), 'id ASC');
295043c2 856 }
857
eaeb6b51
TH
858 $question->hints = $DB->get_records('question_hints',
859 array('questionid' => $question->id), 'id ASC');
d1b7e03d 860
516cf3eb 861 return true;
862 }
863
864 /**
d1b7e03d
TH
865 * Create an appropriate question_definition for the question of this type
866 * using data loaded from the database.
867 * @param object $questiondata the question data loaded from the database.
868 * @return question_definition the corresponding question_definition.
869 */
870 public function make_question($questiondata) {
871 $question = $this->make_question_instance($questiondata);
872 $this->initialise_question_instance($question, $questiondata);
873 return $question;
874 }
0429cd86 875
d1b7e03d
TH
876 /**
877 * Create an appropriate question_definition for the question of this type
878 * using data loaded from the database.
879 * @param object $questiondata the question data loaded from the database.
880 * @return question_definition an instance of the appropriate question_definition subclass.
881 * Still needs to be initialised.
882 */
883 protected function make_question_instance($questiondata) {
884 question_bank::load_question_definition_classes($this->name());
885 $class = 'qtype_' . $this->name() . '_question';
886 return new $class();
887 }
888
889 /**
890 * Initialise the common question_definition fields.
891 * @param question_definition $question the question_definition we are creating.
892 * @param object $questiondata the question data loaded from the database.
893 */
894 protected function initialise_question_instance(question_definition $question, $questiondata) {
895 $question->id = $questiondata->id;
896 $question->category = $questiondata->category;
56e82d99 897 $question->contextid = $questiondata->contextid;
d1b7e03d
TH
898 $question->parent = $questiondata->parent;
899 $question->qtype = $this;
900 $question->name = $questiondata->name;
901 $question->questiontext = $questiondata->questiontext;
902 $question->questiontextformat = $questiondata->questiontextformat;
903 $question->generalfeedback = $questiondata->generalfeedback;
1c2ed7c5 904 $question->generalfeedbackformat = $questiondata->generalfeedbackformat;
d1b7e03d
TH
905 $question->defaultmark = $questiondata->defaultmark + 0;
906 $question->length = $questiondata->length;
907 $question->penalty = $questiondata->penalty;
908 $question->stamp = $questiondata->stamp;
909 $question->version = $questiondata->version;
910 $question->hidden = $questiondata->hidden;
6189fda4 911 $question->idnumber = $questiondata->idnumber;
d1b7e03d
TH
912 $question->timecreated = $questiondata->timecreated;
913 $question->timemodified = $questiondata->timemodified;
914 $question->createdby = $questiondata->createdby;
915 $question->modifiedby = $questiondata->modifiedby;
916
3d9645ae 917 // Fill extra question fields values.
10677751
OS
918 $extraquestionfields = $this->extra_question_fields();
919 if (is_array($extraquestionfields)) {
3d9645ae 920 // Omit table name.
10677751 921 array_shift($extraquestionfields);
3d9645ae 922 foreach ($extraquestionfields as $field) {
10677751
OS
923 $question->$field = $questiondata->options->$field;
924 }
925 }
926
d1b7e03d
TH
927 $this->initialise_question_hints($question, $questiondata);
928 }
929
930 /**
931 * Initialise question_definition::hints field.
932 * @param question_definition $question the question_definition we are creating.
933 * @param object $questiondata the question data loaded from the database.
934 */
935 protected function initialise_question_hints(question_definition $question, $questiondata) {
936 if (empty($questiondata->hints)) {
937 return;
938 }
939 foreach ($questiondata->hints as $hint) {
940 $question->hints[] = $this->make_hint($hint);
941 }
0429cd86 942 }
943
944 /**
d1b7e03d
TH
945 * Create a question_hint, or an appropriate subclass for this question,
946 * from a row loaded from the database.
947 * @param object $hint the DB row from the question hints table.
948 * @return question_hint
9203b705 949 */
d1b7e03d
TH
950 protected function make_hint($hint) {
951 return question_hint::load_from_record($hint);
952 }
953
1c2ed7c5
TH
954 /**
955 * Initialise the combined feedback fields.
956 * @param question_definition $question the question_definition we are creating.
957 * @param object $questiondata the question data loaded from the database.
f7970e3c 958 * @param bool $withparts whether to set the shownumcorrect field.
1c2ed7c5 959 */
eaeb6b51
TH
960 protected function initialise_combined_feedback(question_definition $question,
961 $questiondata, $withparts = false) {
1c2ed7c5
TH
962 $question->correctfeedback = $questiondata->options->correctfeedback;
963 $question->correctfeedbackformat = $questiondata->options->correctfeedbackformat;
964 $question->partiallycorrectfeedback = $questiondata->options->partiallycorrectfeedback;
eaeb6b51
TH
965 $question->partiallycorrectfeedbackformat =
966 $questiondata->options->partiallycorrectfeedbackformat;
1c2ed7c5
TH
967 $question->incorrectfeedback = $questiondata->options->incorrectfeedback;
968 $question->incorrectfeedbackformat = $questiondata->options->incorrectfeedbackformat;
969 if ($withparts) {
970 $question->shownumcorrect = $questiondata->options->shownumcorrect;
971 }
972 }
973
d1b7e03d
TH
974 /**
975 * Initialise question_definition::answers field.
976 * @param question_definition $question the question_definition we are creating.
977 * @param object $questiondata the question data loaded from the database.
35c9b652
TH
978 * @param bool $forceplaintextanswers most qtypes assume that answers are
979 * FORMAT_PLAIN, and dont use the answerformat DB column (it contains
980 * the default 0 = FORMAT_MOODLE). Therefore, by default this method
981 * ingores answerformat. Pass false here to use answerformat. For example
982 * multichoice does this.
983 */
984 protected function initialise_question_answers(question_definition $question,
985 $questiondata, $forceplaintextanswers = true) {
d1b7e03d
TH
986 $question->answers = array();
987 if (empty($questiondata->options->answers)) {
988 return;
989 }
990 foreach ($questiondata->options->answers as $a) {
92e83e2d 991 $question->answers[$a->id] = $this->make_answer($a);
35c9b652
TH
992 if (!$forceplaintextanswers) {
993 $question->answers[$a->id]->answerformat = $a->answerformat;
994 }
d1b7e03d
TH
995 }
996 }
9203b705 997
92e83e2d
OS
998 /**
999 * Create a question_answer, or an appropriate subclass for this question,
1000 * from a row loaded from the database.
1001 * @param object $answer the DB row from the question_answers table plus extra answer fields.
1002 * @return question_answer
1003 */
1004 protected function make_answer($answer) {
1005 return new question_answer($answer->id, $answer->answer,
1006 $answer->fraction, $answer->feedback, $answer->feedbackformat);
1007 }
1008
d1b7e03d 1009 /**
f29aeb5a 1010 * Deletes the question-type specific data when a question is deleted.
f7970e3c
TH
1011 * @param int $question the question being deleted.
1012 * @param int $contextid the context this quesiotn belongs to.
f29aeb5a
TH
1013 */
1014 public function delete_question($questionid, $contextid) {
1015 global $DB;
1016
1017 $this->delete_files($questionid, $contextid);
516cf3eb 1018
eaeb6b51
TH
1019 $extraquestionfields = $this->extra_question_fields();
1020 if (is_array($extraquestionfields)) {
1021 $question_extension_table = array_shift($extraquestionfields);
f29aeb5a
TH
1022 $DB->delete_records($question_extension_table,
1023 array($this->questionid_column_name() => $questionid));
295043c2 1024 }
1025
eaeb6b51
TH
1026 $extraanswerfields = $this->extra_answer_fields();
1027 if (is_array($extraanswerfields)) {
1028 $answer_extension_table = array_shift($extraanswerfields);
f29aeb5a 1029 $DB->delete_records_select($answer_extension_table,
eaeb6b51
TH
1030 'answerid IN (SELECT qa.id FROM {question_answers} qa WHERE qa.question = ?)',
1031 array($questionid));
295043c2 1032 }
1033
f29aeb5a 1034 $DB->delete_records('question_answers', array('question' => $questionid));
d1b7e03d 1035
f29aeb5a 1036 $DB->delete_records('question_hints', array('questionid' => $questionid));
516cf3eb 1037 }
1038
1039 /**
eaeb6b51
TH
1040 * Returns the number of question numbers which are used by the question
1041 *
1042 * This function returns the number of question numbers to be assigned
1043 * to the question. Most question types will have length one; they will be
1044 * assigned one number. The 'description' type, however does not use up a
1045 * number and so has a length of zero. Other question types may wish to
1046 * handle a bundle of questions and hence return a number greater than one.
1047 * @return int The number of question numbers which should be
1048 * assigned to the question.
1049 * @param object $question The question whose length is to be determined.
1050 * Question type specific information is included.
1051 */
d1b7e03d 1052 public function actual_number_of_questions($question) {
3d9645ae 1053 // By default, each question is given one number.
516cf3eb 1054 return 1;
1055 }
1056
6f51ed72 1057 /**
a196cf5a
TH
1058 * Calculate the score a monkey would get on a question by clicking randomly.
1059 *
1060 * Some question types have significant non-zero average expected score
1061 * of the response is just selected randomly. For example 50% for a
1062 * true-false question. It is useful to know what this is. For example
1063 * it gets shown in the quiz statistics report.
1064 *
1065 * For almost any open-ended question type (E.g. shortanswer or numerical)
1066 * this should be 0.
1067 *
1068 * For selective response question types (e.g. multiple choice), you can probably compute this.
1069 *
1070 * For particularly complicated question types the may be impossible or very
1071 * difficult to compute. In this case return null. (Or, if the expected score
1072 * is very tiny even though the exact value is unknown, it may appropriate
1073 * to return 0.)
1074 *
1075 * @param stdClass $questiondata data defining a question, as returned by
1076 * question_bank::load_question_data().
d1b7e03d 1077 * @return number|null either a fraction estimating what the student would
a196cf5a 1078 * score by guessing, or null, if it is not possible to estimate.
6f51ed72 1079 */
c7df5006 1080 public function get_random_guess_score($questiondata) {
6f51ed72 1081 return 0;
1082 }
516cf3eb 1083
3d6f2466
JP
1084 /**
1085 * Whether or not to break down question stats and response analysis, for a question defined by $questiondata.
1086 *
1087 * @param object $questiondata The full question definition data.
1088 * @return bool
1089 */
1090 public function break_down_stats_and_response_analysis_by_variant($questiondata) {
1091 return true;
1092 }
1093
516cf3eb 1094 /**
d1b7e03d 1095 * This method should return all the possible types of response that are
f9b0500f 1096 * recognised for this question.
271e6dec 1097 *
d1b7e03d
TH
1098 * The question is modelled as comprising one or more subparts. For each
1099 * subpart, there are one or more classes that that students response
1100 * might fall into, each of those classes earning a certain score.
50da63eb 1101 *
d1b7e03d
TH
1102 * For example, in a shortanswer question, there is only one subpart, the
1103 * text entry field. The response the student gave will be classified according
1104 * to which of the possible $question->options->answers it matches.
271e6dec 1105 *
d1b7e03d
TH
1106 * For the matching question type, there will be one subpart for each
1107 * question stem, and for each stem, each of the possible choices is a class
1108 * of student's response.
1109 *
1110 * A response is an object with two fields, ->responseclass is a string
1111 * presentation of that response, and ->fraction, the credit for a response
1112 * in that class.
1113 *
1114 * Array keys have no specific meaning, but must be unique, and must be
1115 * the same if this function is called repeatedly.
1116 *
1117 * @param object $question the question definition data.
1118 * @return array keys are subquestionid, values are arrays of possible
1119 * responses to that subquestion.
99ba746d 1120 */
c7df5006 1121 public function get_possible_responses($questiondata) {
d1b7e03d 1122 return array();
50da63eb 1123 }
5fceb049 1124
50da63eb 1125 /**
46e40567
TH
1126 * Utility method used by {@link qtype_renderer::head_code()}. It looks
1127 * for any of the files script.js or script.php that exist in the plugin
1128 * folder and ensures they get included.
50da63eb 1129 */
c76145d3 1130 public function find_standard_scripts() {
f29aeb5a
TH
1131 global $PAGE;
1132
99ba746d 1133 $plugindir = $this->plugin_dir();
f29aeb5a 1134 $plugindirrel = 'question/type/' . $this->name();
50da63eb 1135
1136 if (file_exists($plugindir . '/script.js')) {
f29aeb5a 1137 $PAGE->requires->js('/' . $plugindirrel . '/script.js');
50da63eb 1138 }
1139 if (file_exists($plugindir . '/script.php')) {
f29aeb5a 1140 $PAGE->requires->js('/' . $plugindirrel . '/script.php');
516cf3eb 1141 }
fe9b5cfd 1142 }
1143
62e76c67 1144 /**
eaeb6b51
TH
1145 * Returns true if the editing wizard is finished, false otherwise.
1146 *
1147 * The default implementation returns true, which is suitable for all question-
1148 * types that only use one editing form. This function is used in
1149 * question.php to decide whether we can regrade any states of the edited
1150 * question and redirect to edit.php.
1151 *
1152 * The dataset dependent question-type, which is extended by the calculated
1153 * question-type, overwrites this method because it uses multiple pages (i.e.
1154 * a wizard) to set up the question and associated datasets.
1155 *
1156 * @param object $form The data submitted by the previous page.
1157 *
1158 * @return bool Whether the wizard's last page was submitted or not.
1159 */
f29aeb5a 1160 public function finished_edit_wizard($form) {
3d9645ae 1161 // In the default case there is only one edit page.
d1b7e03d 1162 return true;
62e76c67 1163 }
1164
3d9645ae 1165 // IMPORT/EXPORT FUNCTIONS --------------------------------- .
88bc20c3 1166
1167 /*
1168 * Imports question from the Moodle XML format
1169 *
1170 * Imports question using information from extra_question_fields function
1171 * If some of you fields contains id's you'll need to reimplement this
1172 */
a031b0f3 1173 public function import_from_xml($data, $question, qformat_xml $format, $extra=null) {
88bc20c3 1174 $question_type = $data['@']['type'];
1175 if ($question_type != $this->name()) {
1176 return false;
1177 }
1178
1179 $extraquestionfields = $this->extra_question_fields();
1180 if (!is_array($extraquestionfields)) {
1181 return false;
1182 }
1183
3d9645ae 1184 // Omit table name.
88bc20c3 1185 array_shift($extraquestionfields);
1186 $qo = $format->import_headers($data);
1187 $qo->qtype = $question_type;
1188
1189 foreach ($extraquestionfields as $field) {
05cef658 1190 $qo->$field = $format->getpath($data, array('#', $field, 0, '#'), '');
88bc20c3 1191 }
1192
3d9645ae 1193 // Run through the answers.
88bc20c3 1194 $answers = $data['#']['answer'];
1195 $a_count = 0;
05cef658
JP
1196 $extraanswersfields = $this->extra_answer_fields();
1197 if (is_array($extraanswersfields)) {
1198 array_shift($extraanswersfields);
1199 }
1200 foreach ($answers as $answer) {
1201 $ans = $format->import_answer($answer);
1202 if (!$this->has_html_answers()) {
1203 $qo->answer[$a_count] = $ans->answer['text'];
1204 } else {
88bc20c3 1205 $qo->answer[$a_count] = $ans->answer;
88bc20c3 1206 }
05cef658
JP
1207 $qo->fraction[$a_count] = $ans->fraction;
1208 $qo->feedback[$a_count] = $ans->feedback;
1209 if (is_array($extraanswersfields)) {
1210 foreach ($extraanswersfields as $field) {
1211 $qo->{$field}[$a_count] =
1212 $format->getpath($answer, array('#', $field, 0, '#'), '');
1213 }
1214 }
1215 ++$a_count;
88bc20c3 1216 }
1217 return $qo;
1218 }
1219
1220 /*
1221 * Export question to the Moodle XML format
1222 *
1223 * Export question using information from extra_question_fields function
1224 * If some of you fields contains id's you'll need to reimplement this
1225 */
a031b0f3 1226 public function export_to_xml($question, qformat_xml $format, $extra=null) {
88bc20c3 1227 $extraquestionfields = $this->extra_question_fields();
1228 if (!is_array($extraquestionfields)) {
1229 return false;
1230 }
1231
3d9645ae 1232 // Omit table name.
88bc20c3 1233 array_shift($extraquestionfields);
1234 $expout='';
1235 foreach ($extraquestionfields as $field) {
1b343d52 1236 $exportedvalue = $format->xml_escape($question->options->$field);
f4fe3968 1237 $expout .= " <{$field}>{$exportedvalue}</{$field}>\n";
88bc20c3 1238 }
1239
05cef658
JP
1240 $extraanswersfields = $this->extra_answer_fields();
1241 if (is_array($extraanswersfields)) {
1242 array_shift($extraanswersfields);
1243 }
1244 foreach ($question->options->answers as $answer) {
04fcd1f5 1245 $extra = '';
05cef658
JP
1246 if (is_array($extraanswersfields)) {
1247 foreach ($extraanswersfields as $field) {
1b343d52 1248 $exportedvalue = $format->xml_escape($answer->$field);
04fcd1f5 1249 $extra .= " <{$field}>{$exportedvalue}</{$field}>\n";
05cef658 1250 }
88bc20c3 1251 }
05cef658 1252
04fcd1f5 1253 $expout .= $format->write_answer($answer, $extra);
88bc20c3 1254 }
1255 return $expout;
1256 }
1257
b9bd6da4 1258 /**
1259 * Abstract function implemented by each question type. It runs all the code
1260 * required to set up and save a question of any type for testing purposes.
1261 * Alternate DB table prefix may be used to facilitate data deletion.
1262 */
d1b7e03d 1263 public function generate_test($name, $courseid=null) {
b9bd6da4 1264 $form = new stdClass();
1265 $form->name = $name;
1266 $form->questiontextformat = 1;
1267 $form->questiontext = 'test question, generated by script';
d1b7e03d
TH
1268 $form->defaultmark = 1;
1269 $form->penalty = 0.3333333;
b9bd6da4 1270 $form->generalfeedback = "Well done";
1271
21c08c63 1272 $context = context_course::instance($courseid);
b9bd6da4 1273 $newcategory = question_make_default_categories(array($context));
1274 $form->category = $newcategory->id . ',1';
1275
1276 $question = new stdClass();
1277 $question->courseid = $courseid;
1278 $question->qtype = $this->qtype;
1279 return array($form, $question);
1280 }
f29aeb5a
TH
1281
1282 /**
1283 * Get question context by category id
1284 * @param int $category
1285 * @return object $context
1286 */
c7df5006 1287 protected function get_context_by_category_id($category) {
f29aeb5a
TH
1288 global $DB;
1289 $contextid = $DB->get_field('question_categories', 'contextid', array('id'=>$category));
5fbe2118 1290 $context = context::instance_by_id($contextid, IGNORE_MISSING);
f29aeb5a
TH
1291 return $context;
1292 }
1293
1294 /**
1295 * Save the file belonging to one text field.
1296 *
1297 * @param array $field the data from the form (or from import). This will
1298 * normally have come from the formslib editor element, so it will be an
1299 * array with keys 'text', 'format' and 'itemid'. However, when we are
1300 * importing, it will be an array with keys 'text', 'format' and 'files'
1301 * @param object $context the context the question is in.
1302 * @param string $component indentifies the file area question.
eaeb6b51
TH
1303 * @param string $filearea indentifies the file area questiontext,
1304 * generalfeedback, answerfeedback, etc.
f7970e3c 1305 * @param int $itemid identifies the file area.
f29aeb5a
TH
1306 *
1307 * @return string the text for this field, after files have been processed.
1308 */
1309 protected function import_or_save_files($field, $context, $component, $filearea, $itemid) {
1310 if (!empty($field['itemid'])) {
1311 // This is the normal case. We are safing the questions editing form.
1312 return file_save_draft_area_files($field['itemid'], $context->id, $component,
1313 $filearea, $itemid, $this->fileoptions, trim($field['text']));
1314
1315 } else if (!empty($field['files'])) {
1316 // This is the case when we are doing an import.
1317 foreach ($field['files'] as $file) {
1318 $this->import_file($context, $component, $filearea, $itemid, $file);
1319 }
1320 }
1321 return trim($field['text']);
1322 }
1323
1324 /**
1325 * Move all the files belonging to this question from one context to another.
f7970e3c
TH
1326 * @param int $questionid the question being moved.
1327 * @param int $oldcontextid the context it is moving from.
1328 * @param int $newcontextid the context it is moving to.
f29aeb5a
TH
1329 */
1330 public function move_files($questionid, $oldcontextid, $newcontextid) {
1331 $fs = get_file_storage();
1332 $fs->move_area_files_to_new_context($oldcontextid,
1333 $newcontextid, 'question', 'questiontext', $questionid);
1334 $fs->move_area_files_to_new_context($oldcontextid,
1335 $newcontextid, 'question', 'generalfeedback', $questionid);
1336 }
1337
1338 /**
1339 * Move all the files belonging to this question's answers when the question
1340 * is moved from one context to another.
f7970e3c
TH
1341 * @param int $questionid the question being moved.
1342 * @param int $oldcontextid the context it is moving from.
1343 * @param int $newcontextid the context it is moving to.
1344 * @param bool $answerstoo whether there is an 'answer' question area,
f29aeb5a
TH
1345 * as well as an 'answerfeedback' one. Default false.
1346 */
eaeb6b51
TH
1347 protected function move_files_in_answers($questionid, $oldcontextid,
1348 $newcontextid, $answerstoo = false) {
f29aeb5a
TH
1349 global $DB;
1350 $fs = get_file_storage();
1351
1352 $answerids = $DB->get_records_menu('question_answers',
1353 array('question' => $questionid), 'id', 'id,1');
1354 foreach ($answerids as $answerid => $notused) {
1355 if ($answerstoo) {
1356 $fs->move_area_files_to_new_context($oldcontextid,
1357 $newcontextid, 'question', 'answer', $answerid);
1358 }
1359 $fs->move_area_files_to_new_context($oldcontextid,
1360 $newcontextid, 'question', 'answerfeedback', $answerid);
1361 }
1362 }
1363
d44480f6
TH
1364 /**
1365 * Move all the files belonging to this question's hints when the question
1366 * is moved from one context to another.
1367 * @param int $questionid the question being moved.
1368 * @param int $oldcontextid the context it is moving from.
1369 * @param int $newcontextid the context it is moving to.
1370 * @param bool $answerstoo whether there is an 'answer' question area,
1371 * as well as an 'answerfeedback' one. Default false.
1372 */
1373 protected function move_files_in_hints($questionid, $oldcontextid, $newcontextid) {
1374 global $DB;
1375 $fs = get_file_storage();
1376
1377 $hintids = $DB->get_records_menu('question_hints',
1378 array('questionid' => $questionid), 'id', 'id,1');
1379 foreach ($hintids as $hintid => $notused) {
1380 $fs->move_area_files_to_new_context($oldcontextid,
1381 $newcontextid, 'question', 'hint', $hintid);
1382 }
1383 }
1384
a23bda41
TH
1385 /**
1386 * Move all the files belonging to this question's answers when the question
1387 * is moved from one context to another.
1388 * @param int $questionid the question being moved.
1389 * @param int $oldcontextid the context it is moving from.
1390 * @param int $newcontextid the context it is moving to.
1391 * @param bool $answerstoo whether there is an 'answer' question area,
1392 * as well as an 'answerfeedback' one. Default false.
1393 */
1394 protected function move_files_in_combined_feedback($questionid, $oldcontextid,
1395 $newcontextid) {
1396 global $DB;
1397 $fs = get_file_storage();
1398
1399 $fs->move_area_files_to_new_context($oldcontextid,
1400 $newcontextid, 'question', 'correctfeedback', $questionid);
1401 $fs->move_area_files_to_new_context($oldcontextid,
1402 $newcontextid, 'question', 'partiallycorrectfeedback', $questionid);
1403 $fs->move_area_files_to_new_context($oldcontextid,
1404 $newcontextid, 'question', 'incorrectfeedback', $questionid);
1405 }
1406
f29aeb5a
TH
1407 /**
1408 * Delete all the files belonging to this question.
f7970e3c
TH
1409 * @param int $questionid the question being deleted.
1410 * @param int $contextid the context the question is in.
f29aeb5a
TH
1411 */
1412 protected function delete_files($questionid, $contextid) {
1413 $fs = get_file_storage();
1414 $fs->delete_area_files($contextid, 'question', 'questiontext', $questionid);
1415 $fs->delete_area_files($contextid, 'question', 'generalfeedback', $questionid);
1416 }
1417
1418 /**
1419 * Delete all the files belonging to this question's answers.
f7970e3c
TH
1420 * @param int $questionid the question being deleted.
1421 * @param int $contextid the context the question is in.
1422 * @param bool $answerstoo whether there is an 'answer' question area,
f29aeb5a
TH
1423 * as well as an 'answerfeedback' one. Default false.
1424 */
1425 protected function delete_files_in_answers($questionid, $contextid, $answerstoo = false) {
1426 global $DB;
1427 $fs = get_file_storage();
1428
1429 $answerids = $DB->get_records_menu('question_answers',
1430 array('question' => $questionid), 'id', 'id,1');
1431 foreach ($answerids as $answerid => $notused) {
1432 if ($answerstoo) {
1433 $fs->delete_area_files($contextid, 'question', 'answer', $answerid);
1434 }
1435 $fs->delete_area_files($contextid, 'question', 'answerfeedback', $answerid);
1436 }
1437 }
1438
d44480f6
TH
1439 /**
1440 * Delete all the files belonging to this question's hints.
1441 * @param int $questionid the question being deleted.
1442 * @param int $contextid the context the question is in.
1443 */
1444 protected function delete_files_in_hints($questionid, $contextid) {
1445 global $DB;
1446 $fs = get_file_storage();
1447
1448 $hintids = $DB->get_records_menu('question_hints',
1449 array('questionid' => $questionid), 'id', 'id,1');
1450 foreach ($hintids as $hintid => $notused) {
1451 $fs->delete_area_files($contextid, 'question', 'hint', $hintid);
1452 }
1453 }
1454
a23bda41
TH
1455 /**
1456 * Delete all the files belonging to this question's answers.
1457 * @param int $questionid the question being deleted.
1458 * @param int $contextid the context the question is in.
1459 * @param bool $answerstoo whether there is an 'answer' question area,
1460 * as well as an 'answerfeedback' one. Default false.
1461 */
1462 protected function delete_files_in_combined_feedback($questionid, $contextid) {
1463 global $DB;
1464 $fs = get_file_storage();
1465
1466 $fs->delete_area_files($contextid,
1467 'question', 'correctfeedback', $questionid);
1468 $fs->delete_area_files($contextid,
1469 'question', 'partiallycorrectfeedback', $questionid);
1470 $fs->delete_area_files($contextid,
1471 'question', 'incorrectfeedback', $questionid);
1472 }
1473
f902a54e 1474 public function import_file($context, $component, $filearea, $itemid, $file) {
f29aeb5a 1475 $fs = get_file_storage();
0ff4bd08 1476 $record = new stdClass();
f29aeb5a
TH
1477 if (is_object($context)) {
1478 $record->contextid = $context->id;
1479 } else {
1480 $record->contextid = $context;
1481 }
1482 $record->component = $component;
1483 $record->filearea = $filearea;
1484 $record->itemid = $itemid;
1485 $record->filename = $file->name;
1486 $record->filepath = '/';
1487 return $fs->create_file_from_string($record, $this->decode_file($file));
1488 }
1489
c7df5006 1490 protected function decode_file($file) {
f29aeb5a 1491 switch ($file->encoding) {
eaeb6b51
TH
1492 case 'base64':
1493 default:
1494 return base64_decode($file->content);
f29aeb5a
TH
1495 }
1496 }
d1b7e03d 1497}
aeb15530 1498
cde2709a 1499
d1b7e03d
TH
1500/**
1501 * This class is used in the return value from
1502 * {@link question_type::get_possible_responses()}.
1503 *
7764183a
TH
1504 * @copyright 2010 The Open University
1505 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
d1b7e03d
TH
1506 */
1507class question_possible_response {
9203b705 1508 /**
d1b7e03d
TH
1509 * @var string the classification of this response the student gave to this
1510 * part of the question. Must match one of the responseclasses returned by
1511 * {@link question_type::get_possible_responses()}.
9203b705 1512 */
d1b7e03d 1513 public $responseclass;
ba6425ab
TH
1514
1515 /** @var string the (partial) credit awarded for this responses. */
d1b7e03d 1516 public $fraction;
ba6425ab 1517
9203b705 1518 /**
d1b7e03d
TH
1519 * Constructor, just an easy way to set the fields.
1520 * @param string $responseclassid see the field descriptions above.
1521 * @param string $response see the field descriptions above.
1522 * @param number $fraction see the field descriptions above.
9203b705 1523 */
d1b7e03d
TH
1524 public function __construct($responseclass, $fraction) {
1525 $this->responseclass = $responseclass;
1526 $this->fraction = $fraction;
cde2709a
DC
1527 }
1528
d1b7e03d
TH
1529 public static function no_response() {
1530 return new question_possible_response(get_string('noresponse', 'question'), 0);
cde2709a 1531 }
fe6ce234 1532}