2 // This file is part of Moodle - http://moodle.org/
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
18 * A base class for question editing forms.
21 * @subpackage questiontypes
22 * @copyright 2006 The Open University
23 * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
27 defined('MOODLE_INTERNAL') || die();
30 require_once($CFG->libdir.'/formslib.php');
33 abstract class question_wizard_form extends moodleform {
35 * Add all the hidden form fields used by question/question.php.
37 protected function add_hidden_fields() {
38 $mform = $this->_form;
40 $mform->addElement('hidden', 'id');
41 $mform->setType('id', PARAM_INT);
43 $mform->addElement('hidden', 'inpopup');
44 $mform->setType('inpopup', PARAM_INT);
46 $mform->addElement('hidden', 'cmid');
47 $mform->setType('cmid', PARAM_INT);
49 $mform->addElement('hidden', 'courseid');
50 $mform->setType('courseid', PARAM_INT);
52 $mform->addElement('hidden', 'returnurl');
53 $mform->setType('returnurl', PARAM_LOCALURL);
55 $mform->addElement('hidden', 'scrollpos');
56 $mform->setType('scrollpos', PARAM_INT);
58 $mform->addElement('hidden', 'appendqnumstring');
59 $mform->setType('appendqnumstring', PARAM_ALPHA);
64 * Form definition base class. This defines the common fields that
65 * all question types need. Question types should define their own
66 * class that inherits from this one, and implements the definition_inner()
69 * @copyright 2006 The Open University
70 * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
72 abstract class question_edit_form extends question_wizard_form {
73 const DEFAULT_NUM_HINTS = 2;
76 * Question object with options and answers already loaded by get_question_options
77 * Be careful how you use this it is needed sometimes to set up the structure of the
78 * form in definition_inner but data is always loaded into the form with set_data.
85 protected $categorycontext;
87 /** @var object current context */
89 /** @var array html editor options */
90 public $editoroptions;
91 /** @var array options to preapre draft area */
93 /** @var object instance of question type */
96 public function __construct($submiturl, $question, $category, $contexts, $formeditable = true) {
99 $this->question = $question;
100 $this->contexts = $contexts;
102 $record = $DB->get_record('question_categories',
103 array('id' => $question->category), 'contextid');
104 $this->context = context::instance_by_id($record->contextid);
106 $this->editoroptions = array('subdirs' => 1, 'maxfiles' => EDITOR_UNLIMITED_FILES,
107 'context' => $this->context);
108 $this->fileoptions = array('subdirs' => 1, 'maxfiles' => -1, 'maxbytes' => -1);
110 $this->category = $category;
111 $this->categorycontext = context::instance_by_id($category->contextid);
113 parent::__construct($submiturl, null, 'post', '', null, $formeditable);
117 * Build the form definition.
119 * This adds all the form fields that the default question type supports.
120 * If your question type does not support all these fields, then you can
121 * override this method and remove the ones you don't want with $mform->removeElement().
123 protected function definition() {
124 global $COURSE, $CFG, $DB;
126 $qtype = $this->qtype();
127 $langfile = "qtype_$qtype";
129 $mform = $this->_form;
131 // Standard fields at the start of the form.
132 $mform->addElement('header', 'generalheader', get_string("general", 'form'));
134 if (!isset($this->question->id)) {
135 if (!empty($this->question->formoptions->mustbeusable)) {
136 $contexts = $this->contexts->having_add_and_use();
138 $contexts = $this->contexts->having_cap('moodle/question:add');
142 $mform->addElement('questioncategory', 'category', get_string('category', 'question'),
143 array('contexts' => $contexts));
144 } else if (!($this->question->formoptions->canmove ||
145 $this->question->formoptions->cansaveasnew)) {
146 // Editing question with no permission to move from category.
147 $mform->addElement('questioncategory', 'category', get_string('category', 'question'),
148 array('contexts' => array($this->categorycontext)));
149 } else if ($this->question->formoptions->movecontext) {
150 // Moving question to another context.
151 $mform->addElement('questioncategory', 'categorymoveto',
152 get_string('category', 'question'),
153 array('contexts' => $this->contexts->having_cap('moodle/question:add')));
156 // Editing question with permission to move from category or save as new q.
157 $currentgrp = array();
158 $currentgrp[0] = $mform->createElement('questioncategory', 'category',
159 get_string('categorycurrent', 'question'),
160 array('contexts' => array($this->categorycontext)));
161 if ($this->question->formoptions->canedit ||
162 $this->question->formoptions->cansaveasnew) {
163 // Not move only form.
164 $currentgrp[1] = $mform->createElement('checkbox', 'usecurrentcat', '',
165 get_string('categorycurrentuse', 'question'));
166 $mform->setDefault('usecurrentcat', 1);
168 $currentgrp[0]->freeze();
169 $currentgrp[0]->setPersistantFreeze(false);
170 $mform->addGroup($currentgrp, 'currentgrp',
171 get_string('categorycurrent', 'question'), null, false);
173 $mform->addElement('questioncategory', 'categorymoveto',
174 get_string('categorymoveto', 'question'),
175 array('contexts' => array($this->categorycontext)));
176 if ($this->question->formoptions->canedit ||
177 $this->question->formoptions->cansaveasnew) {
178 // Not move only form.
179 $mform->disabledIf('categorymoveto', 'usecurrentcat', 'checked');
183 $mform->addElement('text', 'name', get_string('questionname', 'question'),
184 array('size' => 50));
185 $mform->setType('name', PARAM_TEXT);
186 $mform->addRule('name', null, 'required', null, 'client');
188 $mform->addElement('editor', 'questiontext', get_string('questiontext', 'question'),
189 array('rows' => 15), $this->editoroptions);
190 $mform->setType('questiontext', PARAM_RAW);
191 $mform->addRule('questiontext', null, 'required', null, 'client');
193 $mform->addElement('text', 'defaultmark', get_string('defaultmark', 'question'),
195 $mform->setType('defaultmark', PARAM_FLOAT);
196 $mform->setDefault('defaultmark', 1);
197 $mform->addRule('defaultmark', null, 'required', null, 'client');
199 $mform->addElement('editor', 'generalfeedback', get_string('generalfeedback', 'question'),
200 array('rows' => 10), $this->editoroptions);
201 $mform->setType('generalfeedback', PARAM_RAW);
202 $mform->addHelpButton('generalfeedback', 'generalfeedback', 'question');
204 // Any questiontype specific fields.
205 $this->definition_inner($mform);
207 if (!empty($CFG->usetags)) {
208 $mform->addElement('header', 'tagsheader', get_string('tags'));
209 $mform->addElement('tags', 'tags', get_string('tags'));
212 if (!empty($this->question->id)) {
213 $mform->addElement('header', 'createdmodifiedheader',
214 get_string('createdmodifiedheader', 'question'));
216 if (!empty($this->question->createdby)) {
217 $a->time = userdate($this->question->timecreated);
218 $a->user = fullname($DB->get_record(
219 'user', array('id' => $this->question->createdby)));
221 $a->time = get_string('unknown', 'question');
222 $a->user = get_string('unknown', 'question');
224 $mform->addElement('static', 'created', get_string('created', 'question'),
225 get_string('byandon', 'question', $a));
226 if (!empty($this->question->modifiedby)) {
228 $a->time = userdate($this->question->timemodified);
229 $a->user = fullname($DB->get_record(
230 'user', array('id' => $this->question->modifiedby)));
231 $mform->addElement('static', 'modified', get_string('modified', 'question'),
232 get_string('byandon', 'question', $a));
236 $this->add_hidden_fields();
238 $mform->addElement('hidden', 'movecontext');
239 $mform->setType('movecontext', PARAM_BOOL);
241 $mform->addElement('hidden', 'qtype');
242 $mform->setType('qtype', PARAM_ALPHA);
244 $buttonarray = array();
245 if (!empty($this->question->id)) {
246 // Editing / moving question.
247 if ($this->question->formoptions->movecontext) {
248 $buttonarray[] = $mform->createElement('submit', 'submitbutton',
249 get_string('moveq', 'question'));
250 } else if ($this->question->formoptions->canedit) {
251 $buttonarray[] = $mform->createElement('submit', 'submitbutton',
252 get_string('savechanges'));
254 if ($this->question->formoptions->cansaveasnew) {
255 $buttonarray[] = $mform->createElement('submit', 'makecopy',
256 get_string('makecopy', 'question'));
258 $buttonarray[] = $mform->createElement('cancel');
260 // Adding new question.
261 $buttonarray[] = $mform->createElement('submit', 'submitbutton',
262 get_string('savechanges'));
263 $buttonarray[] = $mform->createElement('cancel');
265 $mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
266 $mform->closeHeaderBefore('buttonar');
268 if ($this->question->formoptions->movecontext) {
269 $mform->hardFreezeAllVisibleExcept(array('categorymoveto', 'buttonar'));
270 } else if ((!empty($this->question->id)) && (!($this->question->formoptions->canedit ||
271 $this->question->formoptions->cansaveasnew))) {
272 $mform->hardFreezeAllVisibleExcept(array('categorymoveto', 'buttonar', 'currentgrp'));
277 * Add any question-type specific form fields.
279 * @param object $mform the form being built.
281 protected function definition_inner($mform) {
282 // By default, do nothing.
286 * Get the list of form elements to repeat, one for each answer.
287 * @param object $mform the form being built.
288 * @param $label the label to use for each option.
289 * @param $gradeoptions the possible grades for each answer.
290 * @param $repeatedoptions reference to array of repeated options to fill
291 * @param $answersoption reference to return the name of $question->options
292 * field holding an array of answers
293 * @return array of form fields.
295 protected function get_per_answer_fields($mform, $label, $gradeoptions,
296 &$repeatedoptions, &$answersoption) {
298 $answeroptions = array();
299 $answeroptions[] = $mform->createElement('text', 'answer',
300 $label, array('size' => 40));
301 $answeroptions[] = $mform->createElement('select', 'fraction',
302 get_string('grade'), $gradeoptions);
303 $repeated[] = $mform->createElement('group', 'answeroptions',
304 $label, $answeroptions, null, false);
305 $repeated[] = $mform->createElement('editor', 'feedback',
306 get_string('feedback', 'question'), array('rows' => 5), $this->editoroptions);
307 $repeatedoptions['answer']['type'] = PARAM_RAW;
308 $repeatedoptions['fraction']['default'] = 0;
309 $answersoption = 'answers';
314 * Add a set of form fields, obtained from get_per_answer_fields, to the form,
315 * one for each existing answer, with some blanks for some new ones.
316 * @param object $mform the form being built.
317 * @param $label the label to use for each option.
318 * @param $gradeoptions the possible grades for each answer.
319 * @param $minoptions the minimum number of answer blanks to display.
320 * Default QUESTION_NUMANS_START.
321 * @param $addoptions the number of answer blanks to add. Default QUESTION_NUMANS_ADD.
323 protected function add_per_answer_fields(&$mform, $label, $gradeoptions,
324 $minoptions = QUESTION_NUMANS_START, $addoptions = QUESTION_NUMANS_ADD) {
325 $mform->addElement('header', 'answerhdr',
326 get_string('answers', 'question'), '');
327 $mform->setExpanded('answerhdr', 1);
329 $repeatedoptions = array();
330 $repeated = $this->get_per_answer_fields($mform, $label, $gradeoptions,
331 $repeatedoptions, $answersoption);
333 if (isset($this->question->options)) {
334 $repeatsatstart = count($this->question->options->$answersoption);
336 $repeatsatstart = $minoptions;
339 $this->repeat_elements($repeated, $repeatsatstart, $repeatedoptions,
340 'noanswers', 'addanswers', $addoptions,
341 $this->get_more_choices_string(), true);
345 * Language string to use for 'Add {no} more {whatever we call answers}'.
347 protected function get_more_choices_string() {
348 return get_string('addmorechoiceblanks', 'question');
351 protected function add_combined_feedback_fields($withshownumpartscorrect = false) {
352 $mform = $this->_form;
354 $mform->addElement('header', 'combinedfeedbackhdr',
355 get_string('combinedfeedback', 'question'));
357 $fields = array('correctfeedback', 'partiallycorrectfeedback', 'incorrectfeedback');
358 foreach ($fields as $feedbackname) {
359 $element = $mform->addElement('editor', $feedbackname,
360 get_string($feedbackname, 'question'),
361 array('rows' => 5), $this->editoroptions);
362 $mform->setType($feedbackname, PARAM_RAW);
363 // Using setValue() as setDefault() does not work for the editor class.
364 $element->setValue(array('text'=>get_string($feedbackname.'default', 'question')));
366 if ($withshownumpartscorrect && $feedbackname == 'partiallycorrectfeedback') {
367 $mform->addElement('advcheckbox', 'shownumcorrect',
368 get_string('options', 'question'),
369 get_string('shownumpartscorrectwhenfinished', 'question'));
370 $mform->setDefault('shownumcorrect', true);
376 * Create the form elements required by one hint.
377 * @param string $withclearwrong whether this quesiton type uses the 'Clear wrong' option on hints.
378 * @param string $withshownumpartscorrect whether this quesiton type uses the 'Show num parts correct' option on hints.
379 * @return array form field elements for one hint.
381 protected function get_hint_fields($withclearwrong = false, $withshownumpartscorrect = false) {
382 $mform = $this->_form;
384 $repeatedoptions = array();
386 $repeated[] = $mform->createElement('editor', 'hint', get_string('hintn', 'question'),
387 array('rows' => 5), $this->editoroptions);
388 $repeatedoptions['hint']['type'] = PARAM_RAW;
390 $optionelements = array();
391 if ($withclearwrong) {
392 $optionelements[] = $mform->createElement('advcheckbox', 'hintclearwrong',
393 get_string('options', 'question'), get_string('clearwrongparts', 'question'));
395 if ($withshownumpartscorrect) {
396 $optionelements[] = $mform->createElement('advcheckbox', 'hintshownumcorrect', '',
397 get_string('shownumpartscorrect', 'question'));
400 if (count($optionelements)) {
401 $repeated[] = $mform->createElement('group', 'hintoptions',
402 get_string('hintnoptions', 'question'), $optionelements, null, false);
405 return array($repeated, $repeatedoptions);
408 protected function add_interactive_settings($withclearwrong = false,
409 $withshownumpartscorrect = false) {
410 $mform = $this->_form;
412 $mform->addElement('header', 'multitriesheader',
413 get_string('settingsformultipletries', 'question'));
424 if (!empty($this->question->penalty) && !in_array($this->question->penalty, $penalties)) {
425 $penalties[] = $this->question->penalty;
428 $penaltyoptions = array();
429 foreach ($penalties as $penalty) {
430 $penaltyoptions["$penalty"] = (100 * $penalty) . '%';
432 $mform->addElement('select', 'penalty',
433 get_string('penaltyforeachincorrecttry', 'question'), $penaltyoptions);
434 $mform->addHelpButton('penalty', 'penaltyforeachincorrecttry', 'question');
435 $mform->setDefault('penalty', 0.3333333);
437 if (isset($this->question->hints)) {
438 $counthints = count($this->question->hints);
443 if ($this->question->formoptions->repeatelements) {
444 $repeatsatstart = max(self::DEFAULT_NUM_HINTS, $counthints);
446 $repeatsatstart = $counthints;
449 list($repeated, $repeatedoptions) = $this->get_hint_fields(
450 $withclearwrong, $withshownumpartscorrect);
451 $this->repeat_elements($repeated, $repeatsatstart, $repeatedoptions,
452 'numhints', 'addhint', 1, get_string('addanotherhint', 'question'), true);
455 public function set_data($question) {
456 question_bank::get_qtype($question->qtype)->set_default_options($question);
458 // Prepare question text.
459 $draftid = file_get_submitted_draft_itemid('questiontext');
461 if (!empty($question->questiontext)) {
462 $questiontext = $question->questiontext;
464 $questiontext = $this->_form->getElement('questiontext')->getValue();
465 $questiontext = $questiontext['text'];
467 $questiontext = file_prepare_draft_area($draftid, $this->context->id,
468 'question', 'questiontext', empty($question->id) ? null : (int) $question->id,
469 $this->fileoptions, $questiontext);
471 $question->questiontext = array();
472 $question->questiontext['text'] = $questiontext;
473 $question->questiontext['format'] = empty($question->questiontextformat) ?
474 editors_get_preferred_format() : $question->questiontextformat;
475 $question->questiontext['itemid'] = $draftid;
477 // Prepare general feedback.
478 $draftid = file_get_submitted_draft_itemid('generalfeedback');
480 if (empty($question->generalfeedback)) {
481 $generalfeedback = $this->_form->getElement('generalfeedback')->getValue();
482 $question->generalfeedback = $generalfeedback['text'];
485 $feedback = file_prepare_draft_area($draftid, $this->context->id,
486 'question', 'generalfeedback', empty($question->id) ? null : (int) $question->id,
487 $this->fileoptions, $question->generalfeedback);
488 $question->generalfeedback = array();
489 $question->generalfeedback['text'] = $feedback;
490 $question->generalfeedback['format'] = empty($question->generalfeedbackformat) ?
491 editors_get_preferred_format() : $question->generalfeedbackformat;
492 $question->generalfeedback['itemid'] = $draftid;
494 // Remove unnecessary trailing 0s form grade fields.
495 if (isset($question->defaultgrade)) {
496 $question->defaultgrade = 0 + $question->defaultgrade;
498 if (isset($question->penalty)) {
499 $question->penalty = 0 + $question->penalty;
503 $extraquestionfields = question_bank::get_qtype($question->qtype)->extra_question_fields();
504 if (is_array($extraquestionfields) && !empty($question->options)) {
505 array_shift($extraquestionfields);
506 foreach ($extraquestionfields as $field) {
507 if (property_exists($question->options, $field)) {
508 $question->$field = $question->options->$field;
513 // Subclass adds data_preprocessing code here.
514 $question = $this->data_preprocessing($question);
516 parent::set_data($question);
520 * Perform an preprocessing needed on the data passed to {@link set_data()}
521 * before it is used to initialise the form.
522 * @param object $question the data being passed to the form.
523 * @return object $question the modified data.
525 protected function data_preprocessing($question) {
530 * Perform the necessary preprocessing for the fields added by
531 * {@link add_per_answer_fields()}.
532 * @param object $question the data being passed to the form.
533 * @return object $question the modified data.
535 protected function data_preprocessing_answers($question, $withanswerfiles = false) {
536 if (empty($question->options->answers)) {
541 foreach ($question->options->answers as $answer) {
542 if ($withanswerfiles) {
543 // Prepare the feedback editor to display files in draft area.
544 $draftitemid = file_get_submitted_draft_itemid('answer['.$key.']');
545 $question->answer[$key]['text'] = file_prepare_draft_area(
546 $draftitemid, // Draftid
547 $this->context->id, // context
548 'question', // component
550 !empty($answer->id) ? (int) $answer->id : null, // itemid
551 $this->fileoptions, // options
552 $answer->answer // text.
554 $question->answer[$key]['itemid'] = $draftitemid;
555 $question->answer[$key]['format'] = $answer->answerformat;
557 $question->answer[$key] = $answer->answer;
560 $question->fraction[$key] = 0 + $answer->fraction;
561 $question->feedback[$key] = array();
563 // Evil hack alert. Formslib can store defaults in two ways for
565 // ->_defaultValues['fraction[0]'] and
566 // ->_defaultValues['fraction'][0].
567 // The $repeatedoptions['fraction']['default'] = 0 bit above means
568 // that ->_defaultValues['fraction[0]'] has already been set, but we
569 // are using object notation here, so we will be setting
570 // ->_defaultValues['fraction'][0]. That does not work, so we have
571 // to unset ->_defaultValues['fraction[0]'].
572 unset($this->_form->_defaultValues["fraction[$key]"]);
574 // Prepare the feedback editor to display files in draft area.
575 $draftitemid = file_get_submitted_draft_itemid('feedback['.$key.']');
576 $question->feedback[$key]['text'] = file_prepare_draft_area(
577 $draftitemid, // Draftid
578 $this->context->id, // context
579 'question', // component
580 'answerfeedback', // filarea
581 !empty($answer->id) ? (int) $answer->id : null, // itemid
582 $this->fileoptions, // options
583 $answer->feedback // text.
585 $question->feedback[$key]['itemid'] = $draftitemid;
586 $question->feedback[$key]['format'] = $answer->feedbackformat;
593 * Perform the necessary preprocessing for the fields added by
594 * {@link add_combined_feedback_fields()}.
595 * @param object $question the data being passed to the form.
596 * @return object $question the modified data.
598 protected function data_preprocessing_combined_feedback($question,
599 $withshownumcorrect = false) {
600 if (empty($question->options)) {
604 $fields = array('correctfeedback', 'partiallycorrectfeedback', 'incorrectfeedback');
605 foreach ($fields as $feedbackname) {
606 $draftid = file_get_submitted_draft_itemid($feedbackname);
608 $feedback['text'] = file_prepare_draft_area(
610 $this->context->id, // context
611 'question', // component
612 $feedbackname, // filarea
613 !empty($question->id) ? (int) $question->id : null, // itemid
614 $this->fileoptions, // options
615 $question->options->$feedbackname // text.
617 $feedbackformat = $feedbackname . 'format';
618 $feedback['format'] = $question->options->$feedbackformat;
619 $feedback['itemid'] = $draftid;
621 $question->$feedbackname = $feedback;
624 if ($withshownumcorrect) {
625 $question->shownumcorrect = $question->options->shownumcorrect;
632 * Perform the necessary preprocessing for the hint fields.
633 * @param object $question the data being passed to the form.
634 * @return object $question the modified data.
636 protected function data_preprocessing_hints($question, $withclearwrong = false,
637 $withshownumpartscorrect = false) {
638 if (empty($question->hints)) {
643 foreach ($question->hints as $hint) {
644 $question->hint[$key] = array();
646 // Prepare feedback editor to display files in draft area.
647 $draftitemid = file_get_submitted_draft_itemid('hint['.$key.']');
648 $question->hint[$key]['text'] = file_prepare_draft_area(
649 $draftitemid, // Draftid
650 $this->context->id, // context
651 'question', // component
653 !empty($hint->id) ? (int) $hint->id : null, // itemid
654 $this->fileoptions, // options
657 $question->hint[$key]['itemid'] = $draftitemid;
658 $question->hint[$key]['format'] = $hint->hintformat;
661 if ($withclearwrong) {
662 $question->hintclearwrong[] = $hint->clearwrong;
664 if ($withshownumpartscorrect) {
665 $question->hintshownumcorrect[] = $hint->shownumcorrect;
672 public function validation($fromform, $files) {
673 $errors = parent::validation($fromform, $files);
674 if (empty($fromform['makecopy']) && isset($this->question->id)
675 && ($this->question->formoptions->canedit ||
676 $this->question->formoptions->cansaveasnew)
677 && empty($fromform['usecurrentcat']) && !$this->question->formoptions->canmove) {
678 $errors['currentgrp'] = get_string('nopermissionmove', 'question');
682 if (array_key_exists('defaultmark', $fromform) && $fromform['defaultmark'] < 0) {
683 $errors['defaultmark'] = get_string('defaultmarkmustbepositive', 'question');
690 * Override this in the subclass to question type name.
691 * @return the question type name, should be the same as the name() method
692 * in the question type class.
694 public abstract function qtype();
697 * Returns an array of editor options with collapsed options turned off.
698 * @deprecated since 2.6
701 protected function get_non_collabsible_editor_options() {
702 debugging('get_non_collabsible_editor_options() is deprecated, use $this->editoroptions instead.', DEBUG_DEVELOPER);
703 return $this->editoroptions;