Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
- Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
- PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
/question/ -> format.php (source)
Differences Between: [Versions 310 and 311] [Versions 311 and 400] [Versions 311 and 401] [Versions 311 and 402] [Versions 311 and 403] [Versions 39 and 311]
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/>. 16 17 /** 18 * Defines the base class for question import and export formats. 19 * 20 * @package moodlecore 21 * @subpackage questionbank 22 * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} 23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 24 */ 25 26 27 defined('MOODLE_INTERNAL') || die(); 28 29 30 /** 31 * Base class for question import and export formats. 32 * 33 * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} 34 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 35 */ 36 class qformat_default { 37 38 public $displayerrors = true; 39 public $category = null; 40 public $questions = array(); 41 public $course = null; 42 public $filename = ''; 43 public $realfilename = ''; 44 public $matchgrades = 'error'; 45 public $catfromfile = 0; 46 public $contextfromfile = 0; 47 public $cattofile = 0; 48 public $contexttofile = 0; 49 public $questionids = array(); 50 public $importerrors = 0; 51 public $stoponerror = true; 52 public $translator = null; 53 public $canaccessbackupdata = true; 54 protected $importcontext = null; 55 /** @var bool $displayprogress Whether to display progress. */ 56 public $displayprogress = true; 57 58 // functions to indicate import/export functionality 59 // override to return true if implemented 60 61 /** @return bool whether this plugin provides import functionality. */ 62 public function provide_import() { 63 return false; 64 } 65 66 /** @return bool whether this plugin provides export functionality. */ 67 public function provide_export() { 68 return false; 69 } 70 71 /** The string mime-type of the files that this plugin reads or writes. */ 72 public function mime_type() { 73 return mimeinfo('type', $this->export_file_extension()); 74 } 75 76 /** 77 * @return string the file extension (including .) that is normally used for 78 * files handled by this plugin. 79 */ 80 public function export_file_extension() { 81 return '.txt'; 82 } 83 84 /** 85 * Check if the given file is capable of being imported by this plugin. 86 * 87 * Note that expensive or detailed integrity checks on the file should 88 * not be performed by this method. Simple file type or magic-number tests 89 * would be suitable. 90 * 91 * @param stored_file $file the file to check 92 * @return bool whether this plugin can import the file 93 */ 94 public function can_import_file($file) { 95 return ($file->get_mimetype() == $this->mime_type()); 96 } 97 98 /** 99 * Validate the given file. 100 * 101 * For more expensive or detailed integrity checks. 102 * 103 * @param stored_file $file the file to check 104 * @return string the error message that occurred while validating the given file 105 */ 106 public function validate_file(stored_file $file): string { 107 return ''; 108 } 109 110 /** 111 * Check if the given file has the required utf8 encoding. 112 * 113 * @param stored_file $file the file to check 114 * @return string the error message if the file encoding is not UTF-8 115 */ 116 protected function validate_is_utf8_file(stored_file $file): string { 117 if (!mb_check_encoding($file->get_content(), "UTF-8")) { 118 return get_string('importwrongfileencoding', 'question', $this->get_name()); 119 } 120 return ''; 121 } 122 123 /** 124 * Return the localized pluginname string for the question format. 125 * 126 * @return string the pluginname string for the question format 127 */ 128 protected function get_name(): string { 129 return get_string('pluginname', get_class($this)); 130 } 131 132 // Accessor methods 133 134 /** 135 * set the category 136 * @param object category the category object 137 */ 138 public function setCategory($category) { 139 if (count($this->questions)) { 140 debugging('You shouldn\'t call setCategory after setQuestions'); 141 } 142 $this->category = $category; 143 $this->importcontext = context::instance_by_id($this->category->contextid); 144 } 145 146 /** 147 * Set the specific questions to export. Should not include questions with 148 * parents (sub questions of cloze question type). 149 * Only used for question export. 150 * @param array of question objects 151 */ 152 public function setQuestions($questions) { 153 if ($this->category !== null) { 154 debugging('You shouldn\'t call setQuestions after setCategory'); 155 } 156 $this->questions = $questions; 157 } 158 159 /** 160 * set the course class variable 161 * @param course object Moodle course variable 162 */ 163 public function setCourse($course) { 164 $this->course = $course; 165 } 166 167 /** 168 * set an array of contexts. 169 * @param array $contexts Moodle course variable 170 */ 171 public function setContexts($contexts) { 172 $this->contexts = $contexts; 173 $this->translator = new context_to_string_translator($this->contexts); 174 } 175 176 /** 177 * set the filename 178 * @param string filename name of file to import/export 179 */ 180 public function setFilename($filename) { 181 $this->filename = $filename; 182 } 183 184 /** 185 * set the "real" filename 186 * (this is what the user typed, regardless of wha happened next) 187 * @param string realfilename name of file as typed by user 188 */ 189 public function setRealfilename($realfilename) { 190 $this->realfilename = $realfilename; 191 } 192 193 /** 194 * set matchgrades 195 * @param string matchgrades error or nearest for grades 196 */ 197 public function setMatchgrades($matchgrades) { 198 $this->matchgrades = $matchgrades; 199 } 200 201 /** 202 * set catfromfile 203 * @param bool catfromfile allow categories embedded in import file 204 */ 205 public function setCatfromfile($catfromfile) { 206 $this->catfromfile = $catfromfile; 207 } 208 209 /** 210 * set contextfromfile 211 * @param bool $contextfromfile allow contexts embedded in import file 212 */ 213 public function setContextfromfile($contextfromfile) { 214 $this->contextfromfile = $contextfromfile; 215 } 216 217 /** 218 * set cattofile 219 * @param bool cattofile exports categories within export file 220 */ 221 public function setCattofile($cattofile) { 222 $this->cattofile = $cattofile; 223 } 224 225 /** 226 * set contexttofile 227 * @param bool cattofile exports categories within export file 228 */ 229 public function setContexttofile($contexttofile) { 230 $this->contexttofile = $contexttofile; 231 } 232 233 /** 234 * set stoponerror 235 * @param bool stoponerror stops database write if any errors reported 236 */ 237 public function setStoponerror($stoponerror) { 238 $this->stoponerror = $stoponerror; 239 } 240 241 /** 242 * @param bool $canaccess Whether the current use can access the backup data folder. Determines 243 * where export files are saved. 244 */ 245 public function set_can_access_backupdata($canaccess) { 246 $this->canaccessbackupdata = $canaccess; 247 } 248 249 /** 250 * Change whether to display progress messages. 251 * There is normally no need to use this function as the 252 * default for $displayprogress is true. 253 * Set to false for unit tests. 254 * @param bool $displayprogress 255 */ 256 public function set_display_progress($displayprogress) { 257 $this->displayprogress = $displayprogress; 258 } 259 260 /*********************** 261 * IMPORTING FUNCTIONS 262 ***********************/ 263 264 /** 265 * Handle parsing error 266 */ 267 protected function error($message, $text='', $questionname='') { 268 $importerrorquestion = get_string('importerrorquestion', 'question'); 269 270 echo "<div class=\"importerror\">\n"; 271 echo "<strong>{$importerrorquestion} {$questionname}</strong>"; 272 if (!empty($text)) { 273 $text = s($text); 274 echo "<blockquote>{$text}</blockquote>\n"; 275 } 276 echo "<strong>{$message}</strong>\n"; 277 echo "</div>"; 278 279 $this->importerrors++; 280 } 281 282 /** 283 * Import for questiontype plugins 284 * Do not override. 285 * @param data mixed The segment of data containing the question 286 * @param question object processed (so far) by standard import code if appropriate 287 * @param extra mixed any additional format specific data that may be passed by the format 288 * @param qtypehint hint about a question type from format 289 * @return object question object suitable for save_options() or false if cannot handle 290 */ 291 public function try_importing_using_qtypes($data, $question = null, $extra = null, 292 $qtypehint = '') { 293 294 // work out what format we are using 295 $formatname = substr(get_class($this), strlen('qformat_')); 296 $methodname = "import_from_{$formatname}"; 297 298 //first try importing using a hint from format 299 if (!empty($qtypehint)) { 300 $qtype = question_bank::get_qtype($qtypehint, false); 301 if (is_object($qtype) && method_exists($qtype, $methodname)) { 302 $question = $qtype->$methodname($data, $question, $this, $extra); 303 if ($question) { 304 return $question; 305 } 306 } 307 } 308 309 // loop through installed questiontypes checking for 310 // function to handle this question 311 foreach (question_bank::get_all_qtypes() as $qtype) { 312 if (method_exists($qtype, $methodname)) { 313 if ($question = $qtype->$methodname($data, $question, $this, $extra)) { 314 return $question; 315 } 316 } 317 } 318 return false; 319 } 320 321 /** 322 * Perform any required pre-processing 323 * @return bool success 324 */ 325 public function importpreprocess() { 326 return true; 327 } 328 329 /** 330 * Process the file 331 * This method should not normally be overidden 332 * @return bool success 333 */ 334 public function importprocess() { 335 global $USER, $DB, $OUTPUT; 336 337 // Raise time and memory, as importing can be quite intensive. 338 core_php_time_limit::raise(); 339 raise_memory_limit(MEMORY_EXTRA); 340 341 // STAGE 1: Parse the file 342 if ($this->displayprogress) { 343 echo $OUTPUT->notification(get_string('parsingquestions', 'question'), 'notifysuccess'); 344 } 345 346 if (! $lines = $this->readdata($this->filename)) { 347 echo $OUTPUT->notification(get_string('cannotread', 'question')); 348 return false; 349 } 350 351 if (!$questions = $this->readquestions($lines)) { // Extract all the questions 352 echo $OUTPUT->notification(get_string('noquestionsinfile', 'question')); 353 return false; 354 } 355 356 // STAGE 2: Write data to database 357 if ($this->displayprogress) { 358 echo $OUTPUT->notification(get_string('importingquestions', 'question', 359 $this->count_questions($questions)), 'notifysuccess'); 360 } 361 362 // check for errors before we continue 363 if ($this->stoponerror and ($this->importerrors>0)) { 364 echo $OUTPUT->notification(get_string('importparseerror', 'question')); 365 return true; 366 } 367 368 // get list of valid answer grades 369 $gradeoptionsfull = question_bank::fraction_options_full(); 370 371 // check answer grades are valid 372 // (now need to do this here because of 'stop on error': MDL-10689) 373 $gradeerrors = 0; 374 $goodquestions = array(); 375 foreach ($questions as $question) { 376 if (!empty($question->fraction) and (is_array($question->fraction))) { 377 $fractions = $question->fraction; 378 $invalidfractions = array(); 379 foreach ($fractions as $key => $fraction) { 380 $newfraction = match_grade_options($gradeoptionsfull, $fraction, 381 $this->matchgrades); 382 if ($newfraction === false) { 383 $invalidfractions[] = $fraction; 384 } else { 385 $fractions[$key] = $newfraction; 386 } 387 } 388 if ($invalidfractions) { 389 echo $OUTPUT->notification(get_string('invalidgrade', 'question', 390 implode(', ', $invalidfractions))); 391 ++$gradeerrors; 392 continue; 393 } else { 394 $question->fraction = $fractions; 395 } 396 } 397 $goodquestions[] = $question; 398 } 399 $questions = $goodquestions; 400 401 // check for errors before we continue 402 if ($this->stoponerror && $gradeerrors > 0) { 403 return false; 404 } 405 406 // count number of questions processed 407 $count = 0; 408 409 foreach ($questions as $question) { // Process and store each question 410 $transaction = $DB->start_delegated_transaction(); 411 412 // reset the php timeout 413 core_php_time_limit::raise(); 414 415 // check for category modifiers 416 if ($question->qtype == 'category') { 417 if ($this->catfromfile) { 418 // find/create category object 419 $catpath = $question->category; 420 $newcategory = $this->create_category_path($catpath, $question); 421 if (!empty($newcategory)) { 422 $this->category = $newcategory; 423 } 424 } 425 $transaction->allow_commit(); 426 continue; 427 } 428 $question->context = $this->importcontext; 429 430 $count++; 431 432 if ($this->displayprogress) { 433 echo "<hr /><p><b>{$count}</b>. " . $this->format_question_text($question) . "</p>"; 434 } 435 436 $question->category = $this->category->id; 437 $question->stamp = make_unique_id_code(); // Set the unique code (not to be changed) 438 439 $question->createdby = $USER->id; 440 $question->timecreated = time(); 441 $question->modifiedby = $USER->id; 442 $question->timemodified = time(); 443 if (isset($question->idnumber)) { 444 if ((string) $question->idnumber === '') { 445 // Id number not really set. Get rid of it. 446 unset($question->idnumber); 447 } else { 448 if ($DB->record_exists('question', 449 ['idnumber' => $question->idnumber, 'category' => $question->category])) { 450 // We cannot have duplicate idnumbers in a category. Just remove it. 451 unset($question->idnumber); 452 } 453 } 454 } 455 456 $fileoptions = array( 457 'subdirs' => true, 458 'maxfiles' => -1, 459 'maxbytes' => 0, 460 ); 461 462 $question->id = $DB->insert_record('question', $question); 463 $event = \core\event\question_created::create_from_question_instance($question, $this->importcontext); 464 $event->trigger(); 465 466 if (isset($question->questiontextitemid)) { 467 $question->questiontext = file_save_draft_area_files($question->questiontextitemid, 468 $this->importcontext->id, 'question', 'questiontext', $question->id, 469 $fileoptions, $question->questiontext); 470 } else if (isset($question->questiontextfiles)) { 471 foreach ($question->questiontextfiles as $file) { 472 question_bank::get_qtype($question->qtype)->import_file( 473 $this->importcontext, 'question', 'questiontext', $question->id, $file); 474 } 475 } 476 if (isset($question->generalfeedbackitemid)) { 477 $question->generalfeedback = file_save_draft_area_files($question->generalfeedbackitemid, 478 $this->importcontext->id, 'question', 'generalfeedback', $question->id, 479 $fileoptions, $question->generalfeedback); 480 } else if (isset($question->generalfeedbackfiles)) { 481 foreach ($question->generalfeedbackfiles as $file) { 482 question_bank::get_qtype($question->qtype)->import_file( 483 $this->importcontext, 'question', 'generalfeedback', $question->id, $file); 484 } 485 } 486 $DB->update_record('question', $question); 487 488 $this->questionids[] = $question->id; 489 490 // Now to save all the answers and type-specific options 491 492 $result = question_bank::get_qtype($question->qtype)->save_question_options($question); 493 494 if (core_tag_tag::is_enabled('core_question', 'question')) { 495 // Is the current context we're importing in a course context? 496 $importingcontext = $this->importcontext; 497 $importingcoursecontext = $importingcontext->get_course_context(false); 498 $isimportingcontextcourseoractivity = !empty($importingcoursecontext); 499 500 if (!empty($question->coursetags)) { 501 if ($isimportingcontextcourseoractivity) { 502 $mergedtags = array_merge($question->coursetags, $question->tags); 503 504 core_tag_tag::set_item_tags('core_question', 'question', $question->id, 505 $question->context, $mergedtags); 506 } else { 507 core_tag_tag::set_item_tags('core_question', 'question', $question->id, 508 context_course::instance($this->course->id), $question->coursetags); 509 510 if (!empty($question->tags)) { 511 core_tag_tag::set_item_tags('core_question', 'question', $question->id, 512 $importingcontext, $question->tags); 513 } 514 } 515 } else if (!empty($question->tags)) { 516 core_tag_tag::set_item_tags('core_question', 'question', $question->id, 517 $question->context, $question->tags); 518 } 519 } 520 521 if (!empty($result->error)) { 522 echo $OUTPUT->notification($result->error); 523 // Can't use $transaction->rollback(); since it requires an exception, 524 // and I don't want to rewrite this code to change the error handling now. 525 $DB->force_transaction_rollback(); 526 return false; 527 } 528 529 $transaction->allow_commit(); 530 531 if (!empty($result->notice)) { 532 echo $OUTPUT->notification($result->notice); 533 return true; 534 } 535 536 // Give the question a unique version stamp determined by question_hash() 537 $DB->set_field('question', 'version', question_hash($question), 538 array('id' => $question->id)); 539 } 540 return true; 541 } 542 543 /** 544 * Count all non-category questions in the questions array. 545 * 546 * @param array questions An array of question objects. 547 * @return int The count. 548 * 549 */ 550 protected function count_questions($questions) { 551 $count = 0; 552 if (!is_array($questions)) { 553 return $count; 554 } 555 foreach ($questions as $question) { 556 if (!is_object($question) || !isset($question->qtype) || 557 ($question->qtype == 'category')) { 558 continue; 559 } 560 $count++; 561 } 562 return $count; 563 } 564 565 /** 566 * find and/or create the category described by a delimited list 567 * e.g. $course$/tom/dick/harry or tom/dick/harry 568 * 569 * removes any context string no matter whether $getcontext is set 570 * but if $getcontext is set then ignore the context and use selected category context. 571 * 572 * @param string catpath delimited category path 573 * @param object $lastcategoryinfo Contains category information 574 * @return mixed category object or null if fails 575 */ 576 protected function create_category_path($catpath, $lastcategoryinfo = null) { 577 global $DB; 578 $catnames = $this->split_category_path($catpath); 579 $parent = 0; 580 $category = null; 581 582 // check for context id in path, it might not be there in pre 1.9 exports 583 $matchcount = preg_match('/^\$([a-z]+)\$$/', $catnames[0], $matches); 584 if ($matchcount == 1) { 585 $contextid = $this->translator->string_to_context($matches[1]); 586 array_shift($catnames); 587 } else { 588 $contextid = false; 589 } 590 591 // Before 3.5, question categories could be created at top level. 592 // From 3.5 onwards, all question categories should be a child of a special category called the "top" category. 593 if (isset($catnames[0]) && (($catnames[0] != 'top') || (count($catnames) < 3))) { 594 array_unshift($catnames, 'top'); 595 } 596 597 if ($this->contextfromfile && $contextid !== false) { 598 $context = context::instance_by_id($contextid); 599 require_capability('moodle/question:add', $context); 600 } else { 601 $context = context::instance_by_id($this->category->contextid); 602 } 603 $this->importcontext = $context; 604 605 // Now create any categories that need to be created. 606 foreach ($catnames as $key => $catname) { 607 if ($parent == 0) { 608 $category = question_get_top_category($context->id, true); 609 $parent = $category->id; 610 } else if ($category = $DB->get_record('question_categories', 611 array('name' => $catname, 'contextid' => $context->id, 'parent' => $parent))) { 612 // If this category is now the last one in the path we are processing ... 613 if ($key == (count($catnames) - 1) && $lastcategoryinfo) { 614 // Do nothing unless the child category appears before the parent category 615 // in the imported xml file. Because the parent was created without info being available 616 // at that time, this allows the info to be added from the xml data. 617 if (isset($lastcategoryinfo->info) && $lastcategoryinfo->info !== '' 618 && $category->info === '') { 619 $category->info = $lastcategoryinfo->info; 620 if (isset($lastcategoryinfo->infoformat) && $lastcategoryinfo->infoformat !== '') { 621 $category->infoformat = $lastcategoryinfo->infoformat; 622 } 623 } 624 // Same for idnumber. 625 if (isset($lastcategoryinfo->idnumber) && $lastcategoryinfo->idnumber !== '' 626 && $category->idnumber === '') { 627 $category->idnumber = $lastcategoryinfo->idnumber; 628 } 629 $DB->update_record('question_categories', $category); 630 } 631 $parent = $category->id; 632 } else { 633 if ($catname == 'top') { 634 // Should not happen, but if it does just move on. 635 // Occurs when there has been some import/export that has created 636 // multiple nested 'top' categories (due to old bug solved by MDL-63165). 637 // This basically silently cleans up old errors. Not throwing an exception here. 638 continue; 639 } 640 require_capability('moodle/question:managecategory', $context); 641 // Create the new category. This will create all the categories in the catpath, 642 // though only the final category will have any info added if available. 643 $category = new stdClass(); 644 $category->contextid = $context->id; 645 $category->name = $catname; 646 $category->info = ''; 647 // Only add info (category description) for the final category in the catpath. 648 if ($key == (count($catnames) - 1) && $lastcategoryinfo) { 649 if (isset($lastcategoryinfo->info) && $lastcategoryinfo->info !== '') { 650 $category->info = $lastcategoryinfo->info; 651 if (isset($lastcategoryinfo->infoformat) && $lastcategoryinfo->infoformat !== '') { 652 $category->infoformat = $lastcategoryinfo->infoformat; 653 } 654 } 655 // Same for idnumber. 656 if (isset($lastcategoryinfo->idnumber) && $lastcategoryinfo->idnumber !== '') { 657 $category->idnumber = $lastcategoryinfo->idnumber; 658 } 659 } 660 $category->parent = $parent; 661 $category->sortorder = 999; 662 $category->stamp = make_unique_id_code(); 663 $category->id = $DB->insert_record('question_categories', $category); 664 $parent = $category->id; 665 $event = \core\event\question_category_created::create_from_question_category_instance($category, $context); 666 $event->trigger(); 667 } 668 } 669 return $category; 670 } 671 672 /** 673 * Return complete file within an array, one item per line 674 * @param string filename name of file 675 * @return mixed contents array or false on failure 676 */ 677 protected function readdata($filename) { 678 if (is_readable($filename)) { 679 $filearray = file($filename); 680 681 // If the first line of the file starts with a UTF-8 BOM, remove it. 682 $filearray[0] = core_text::trim_utf8_bom($filearray[0]); 683 684 // Check for Macintosh OS line returns (ie file on one line), and fix. 685 if (preg_match("~\r~", $filearray[0]) AND !preg_match("~\n~", $filearray[0])) { 686 return explode("\r", $filearray[0]); 687 } else { 688 return $filearray; 689 } 690 } 691 return false; 692 } 693 694 /** 695 * Parses an array of lines into an array of questions, 696 * where each item is a question object as defined by 697 * readquestion(). Questions are defined as anything 698 * between blank lines. 699 * 700 * NOTE this method used to take $context as a second argument. However, at 701 * the point where this method was called, it was impossible to know what 702 * context the quetsions were going to be saved into, so the value could be 703 * wrong. Also, none of the standard question formats were using this argument, 704 * so it was removed. See MDL-32220. 705 * 706 * If your format does not use blank lines as a delimiter 707 * then you will need to override this method. Even then 708 * try to use readquestion for each question 709 * @param array lines array of lines from readdata 710 * @return array array of question objects 711 */ 712 protected function readquestions($lines) { 713 714 $questions = array(); 715 $currentquestion = array(); 716 717 foreach ($lines as $line) { 718 $line = trim($line); 719 if (empty($line)) { 720 if (!empty($currentquestion)) { 721 if ($question = $this->readquestion($currentquestion)) { 722 $questions[] = $question; 723 } 724 $currentquestion = array(); 725 } 726 } else { 727 $currentquestion[] = $line; 728 } 729 } 730 731 if (!empty($currentquestion)) { // There may be a final question 732 if ($question = $this->readquestion($currentquestion)) { 733 $questions[] = $question; 734 } 735 } 736 737 return $questions; 738 } 739 740 /** 741 * return an "empty" question 742 * Somewhere to specify question parameters that are not handled 743 * by import but are required db fields. 744 * This should not be overridden. 745 * @return object default question 746 */ 747 protected function defaultquestion() { 748 global $CFG; 749 static $defaultshuffleanswers = null; 750 if (is_null($defaultshuffleanswers)) { 751 $defaultshuffleanswers = get_config('quiz', 'shuffleanswers'); 752 } 753 754 $question = new stdClass(); 755 $question->shuffleanswers = $defaultshuffleanswers; 756 $question->defaultmark = 1; 757 $question->image = ''; 758 $question->usecase = 0; 759 $question->multiplier = array(); 760 $question->questiontextformat = FORMAT_MOODLE; 761 $question->generalfeedback = ''; 762 $question->generalfeedbackformat = FORMAT_MOODLE; 763 $question->answernumbering = 'abc'; 764 $question->penalty = 0.3333333; 765 $question->length = 1; 766 767 // this option in case the questiontypes class wants 768 // to know where the data came from 769 $question->export_process = true; 770 $question->import_process = true; 771 772 $this->add_blank_combined_feedback($question); 773 774 return $question; 775 } 776 777 /** 778 * Construct a reasonable default question name, based on the start of the question text. 779 * @param string $questiontext the question text. 780 * @param string $default default question name to use if the constructed one comes out blank. 781 * @return string a reasonable question name. 782 */ 783 public function create_default_question_name($questiontext, $default) { 784 $name = $this->clean_question_name(shorten_text($questiontext, 80)); 785 if ($name) { 786 return $name; 787 } else { 788 return $default; 789 } 790 } 791 792 /** 793 * Ensure that a question name does not contain anything nasty, and will fit in the DB field. 794 * @param string $name the raw question name. 795 * @return string a safe question name. 796 */ 797 public function clean_question_name($name) { 798 $name = clean_param($name, PARAM_TEXT); // Matches what the question editing form does. 799 $name = trim($name); 800 $trimlength = 251; 801 while (core_text::strlen($name) > 255 && $trimlength > 0) { 802 $name = shorten_text($name, $trimlength); 803 $trimlength -= 10; 804 } 805 return $name; 806 } 807 808 /** 809 * Add a blank combined feedback to a question object. 810 * @param object question 811 * @return object question 812 */ 813 protected function add_blank_combined_feedback($question) { 814 $question->correctfeedback = [ 815 'text' => '', 816 'format' => $question->questiontextformat, 817 'files' => [] 818 ]; 819 $question->partiallycorrectfeedback = [ 820 'text' => '', 821 'format' => $question->questiontextformat, 822 'files' => [] 823 ]; 824 $question->incorrectfeedback = [ 825 'text' => '', 826 'format' => $question->questiontextformat, 827 'files' => [] 828 ]; 829 return $question; 830 } 831 832 /** 833 * Given the data known to define a question in 834 * this format, this function converts it into a question 835 * object suitable for processing and insertion into Moodle. 836 * 837 * If your format does not use blank lines to delimit questions 838 * (e.g. an XML format) you must override 'readquestions' too 839 * @param $lines mixed data that represents question 840 * @return object question object 841 */ 842 protected function readquestion($lines) { 843 // We should never get there unless the qformat plugin is broken. 844 throw new coding_exception('Question format plugin is missing important code: readquestion.'); 845 846 return null; 847 } 848 849 /** 850 * Override if any post-processing is required 851 * @return bool success 852 */ 853 public function importpostprocess() { 854 return true; 855 } 856 857 /******************* 858 * EXPORT FUNCTIONS 859 *******************/ 860 861 /** 862 * Provide export functionality for plugin questiontypes 863 * Do not override 864 * @param name questiontype name 865 * @param question object data to export 866 * @param extra mixed any addition format specific data needed 867 * @return string the data to append to export or false if error (or unhandled) 868 */ 869 protected function try_exporting_using_qtypes($name, $question, $extra=null) { 870 // work out the name of format in use 871 $formatname = substr(get_class($this), strlen('qformat_')); 872 $methodname = "export_to_{$formatname}"; 873 874 $qtype = question_bank::get_qtype($name, false); 875 if (method_exists($qtype, $methodname)) { 876 return $qtype->$methodname($question, $this, $extra); 877 } 878 return false; 879 } 880 881 /** 882 * Do any pre-processing that may be required 883 * @param bool success 884 */ 885 public function exportpreprocess() { 886 return true; 887 } 888 889 /** 890 * Enable any processing to be done on the content 891 * just prior to the file being saved 892 * default is to do nothing 893 * @param string output text 894 * @param string processed output text 895 */ 896 protected function presave_process($content) { 897 return $content; 898 } 899 900 /** 901 * Perform the export. 902 * For most types this should not need to be overrided. 903 * 904 * @param bool $checkcapabilities Whether to check capabilities when exporting the questions. 905 * @return string The content of the export. 906 */ 907 public function exportprocess($checkcapabilities = true) { 908 global $CFG, $DB; 909 910 // Raise time and memory, as exporting can be quite intensive. 911 core_php_time_limit::raise(); 912 raise_memory_limit(MEMORY_EXTRA); 913 914 // Get the parents (from database) for this category. 915 $parents = []; 916 if ($this->category) { 917 $parents = question_categorylist_parents($this->category->id); 918 } 919 920 // get the questions (from database) in this category 921 // only get q's with no parents (no cloze subquestions specifically) 922 if ($this->category) { 923 $questions = get_questions_category($this->category, true); 924 } else { 925 $questions = $this->questions; 926 } 927 928 $count = 0; 929 930 // results are first written into string (and then to a file) 931 // so create/initialize the string here 932 $expout = ''; 933 934 // track which category questions are in 935 // if it changes we will record the category change in the output 936 // file if selected. 0 means that it will get printed before the 1st question 937 $trackcategory = 0; 938 939 // Array of categories written to file. 940 $writtencategories = []; 941 942 foreach ($questions as $question) { 943 // used by file api 944 $contextid = $DB->get_field('question_categories', 'contextid', 945 array('id' => $question->category)); 946 $question->contextid = $contextid; 947 948 // do not export hidden questions 949 if (!empty($question->hidden)) { 950 continue; 951 } 952 953 // do not export random questions 954 if ($question->qtype == 'random') { 955 continue; 956 } 957 958 // check if we need to record category change 959 if ($this->cattofile) { 960 $addnewcat = false; 961 if ($question->category != $trackcategory) { 962 $addnewcat = true; 963 $trackcategory = $question->category; 964 } 965 $trackcategoryparents = question_categorylist_parents($trackcategory); 966 // Check if we need to record empty parents categories. 967 foreach ($trackcategoryparents as $trackcategoryparent) { 968 // If parent wasn't written. 969 if (!in_array($trackcategoryparent, $writtencategories)) { 970 // If parent is empty. 971 if (!count($DB->get_records('question', array('category' => $trackcategoryparent)))) { 972 $categoryname = $this->get_category_path($trackcategoryparent, $this->contexttofile); 973 $categoryinfo = $DB->get_record('question_categories', array('id' => $trackcategoryparent), 974 'name, info, infoformat, idnumber', MUST_EXIST); 975 if ($categoryinfo->name != 'top') { 976 // Create 'dummy' question for parent category. 977 $dummyquestion = $this->create_dummy_question_representing_category($categoryname, $categoryinfo); 978 $expout .= $this->writequestion($dummyquestion) . "\n"; 979 $writtencategories[] = $trackcategoryparent; 980 } 981 } 982 } 983 } 984 if ($addnewcat && !in_array($trackcategory, $writtencategories)) { 985 $categoryname = $this->get_category_path($trackcategory, $this->contexttofile); 986 $categoryinfo = $DB->get_record('question_categories', array('id' => $trackcategory), 987 'info, infoformat, idnumber', MUST_EXIST); 988 // Create 'dummy' question for category. 989 $dummyquestion = $this->create_dummy_question_representing_category($categoryname, $categoryinfo); 990 $expout .= $this->writequestion($dummyquestion) . "\n"; 991 $writtencategories[] = $trackcategory; 992 } 993 } 994 995 // Add the question to result. 996 if (!$checkcapabilities || question_has_capability_on($question, 'view')) { 997 $expquestion = $this->writequestion($question, $contextid); 998 // Don't add anything if witequestion returned nothing. 999 // This will permit qformat plugins to exclude some questions. 1000 if ($expquestion !== null) { 1001 $expout .= $expquestion . "\n"; 1002 $count++; 1003 } 1004 } 1005 } 1006 1007 // continue path for following error checks 1008 $course = $this->course; 1009 $continuepath = "{$CFG->wwwroot}/question/export.php?courseid={$course->id}"; 1010 1011 // did we actually process anything 1012 if ($count==0) { 1013 print_error('noquestions', 'question', $continuepath); 1014 } 1015 1016 // final pre-process on exported data 1017 $expout = $this->presave_process($expout); 1018 return $expout; 1019 } 1020 1021 /** 1022 * Create 'dummy' question for category export. 1023 * @param string $categoryname the name of the category 1024 * @param object $categoryinfo description of the category 1025 * @return stdClass 'dummy' question for category 1026 */ 1027 protected function create_dummy_question_representing_category(string $categoryname, $categoryinfo) { 1028 $dummyquestion = new stdClass(); 1029 $dummyquestion->qtype = 'category'; 1030 $dummyquestion->category = $categoryname; 1031 $dummyquestion->id = 0; 1032 $dummyquestion->questiontextformat = ''; 1033 $dummyquestion->contextid = 0; 1034 $dummyquestion->info = $categoryinfo->info; 1035 $dummyquestion->infoformat = $categoryinfo->infoformat; 1036 $dummyquestion->idnumber = $categoryinfo->idnumber; 1037 $dummyquestion->name = 'Switch category to ' . $categoryname; 1038 return $dummyquestion; 1039 } 1040 1041 /** 1042 * get the category as a path (e.g., tom/dick/harry) 1043 * @param int id the id of the most nested catgory 1044 * @return string the path 1045 */ 1046 protected function get_category_path($id, $includecontext = true) { 1047 global $DB; 1048 1049 if (!$category = $DB->get_record('question_categories', array('id' => $id))) { 1050 print_error('cannotfindcategory', 'error', '', $id); 1051 } 1052 $contextstring = $this->translator->context_to_string($category->contextid); 1053 1054 $pathsections = array(); 1055 do { 1056 $pathsections[] = $category->name; 1057 $id = $category->parent; 1058 } while ($category = $DB->get_record('question_categories', array('id' => $id))); 1059 1060 if ($includecontext) { 1061 $pathsections[] = '$' . $contextstring . '$'; 1062 } 1063 1064 $path = $this->assemble_category_path(array_reverse($pathsections)); 1065 1066 return $path; 1067 } 1068 1069 /** 1070 * Convert a list of category names, possibly preceeded by one of the 1071 * context tokens like $course$, into a string representation of the 1072 * category path. 1073 * 1074 * Names are separated by / delimiters. And /s in the name are replaced by //. 1075 * 1076 * To reverse the process and split the paths into names, use 1077 * {@link split_category_path()}. 1078 * 1079 * @param array $names 1080 * @return string 1081 */ 1082 protected function assemble_category_path($names) { 1083 $escapednames = array(); 1084 foreach ($names as $name) { 1085 $escapedname = str_replace('/', '//', $name); 1086 if (substr($escapedname, 0, 1) == '/') { 1087 $escapedname = ' ' . $escapedname; 1088 } 1089 if (substr($escapedname, -1) == '/') { 1090 $escapedname = $escapedname . ' '; 1091 } 1092 $escapednames[] = $escapedname; 1093 } 1094 return implode('/', $escapednames); 1095 } 1096 1097 /** 1098 * Convert a string, as returned by {@link assemble_category_path()}, 1099 * back into an array of category names. 1100 * 1101 * Each category name is cleaned by a call to clean_param(, PARAM_TEXT), 1102 * which matches the cleaning in question/category_form.php. 1103 * 1104 * @param string $path 1105 * @return array of category names. 1106 */ 1107 protected function split_category_path($path) { 1108 $rawnames = preg_split('~(?<!/)/(?!/)~', $path); 1109 $names = array(); 1110 foreach ($rawnames as $rawname) { 1111 $names[] = clean_param(trim(str_replace('//', '/', $rawname)), PARAM_TEXT); 1112 } 1113 return $names; 1114 } 1115 1116 /** 1117 * Do an post-processing that may be required 1118 * @return bool success 1119 */ 1120 protected function exportpostprocess() { 1121 return true; 1122 } 1123 1124 /** 1125 * convert a single question object into text output in the given 1126 * format. 1127 * This must be overriden 1128 * @param object question question object 1129 * @return mixed question export text or null if not implemented 1130 */ 1131 protected function writequestion($question) { 1132 // if not overidden, then this is an error. 1133 throw new coding_exception('Question format plugin is missing important code: writequestion.'); 1134 return null; 1135 } 1136 1137 /** 1138 * Convert the question text to plain text, so it can safely be displayed 1139 * during import to let the user see roughly what is going on. 1140 */ 1141 protected function format_question_text($question) { 1142 return s(question_utils::to_plain_text($question->questiontext, 1143 $question->questiontextformat)); 1144 } 1145 } 1146 1147 class qformat_based_on_xml extends qformat_default { 1148 1149 /** 1150 * A lot of imported files contain unwanted entities. 1151 * This method tries to clean up all known problems. 1152 * @param string str string to correct 1153 * @return string the corrected string 1154 */ 1155 public function cleaninput($str) { 1156 1157 $html_code_list = array( 1158 "'" => "'", 1159 "’" => "'", 1160 "“" => "\"", 1161 "”" => "\"", 1162 "–" => "-", 1163 "—" => "-", 1164 ); 1165 $str = strtr($str, $html_code_list); 1166 // Use core_text entities_to_utf8 function to convert only numerical entities. 1167 $str = core_text::entities_to_utf8($str, false); 1168 return $str; 1169 } 1170 1171 /** 1172 * Return the array moodle is expecting 1173 * for an HTML text. No processing is done on $text. 1174 * qformat classes that want to process $text 1175 * for instance to import external images files 1176 * and recode urls in $text must overwrite this method. 1177 * @param array $text some HTML text string 1178 * @return array with keys text, format and files. 1179 */ 1180 public function text_field($text) { 1181 return array( 1182 'text' => trim($text), 1183 'format' => FORMAT_HTML, 1184 'files' => array(), 1185 ); 1186 } 1187 1188 /** 1189 * Return the value of a node, given a path to the node 1190 * if it doesn't exist return the default value. 1191 * @param array xml data to read 1192 * @param array path path to node expressed as array 1193 * @param mixed default 1194 * @param bool istext process as text 1195 * @param string error if set value must exist, return false and issue message if not 1196 * @return mixed value 1197 */ 1198 public function getpath($xml, $path, $default, $istext=false, $error='') { 1199 foreach ($path as $index) { 1200 if (!isset($xml[$index])) { 1201 if (!empty($error)) { 1202 $this->error($error); 1203 return false; 1204 } else { 1205 return $default; 1206 } 1207 } 1208 1209 $xml = $xml[$index]; 1210 } 1211 1212 if ($istext) { 1213 if (!is_string($xml)) { 1214 $this->error(get_string('invalidxml', 'qformat_xml')); 1215 } 1216 $xml = trim($xml); 1217 } 1218 1219 return $xml; 1220 } 1221 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
