[ Index ] |
PHP Cross Reference of moodle-2.8 |
[Summary view] [Print] [Text view]
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 * This file defines the question attempt step class, and a few related classes. 19 * 20 * @package moodlecore 21 * @subpackage questionengine 22 * @copyright 2009 The Open University 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 * Stores one step in a {@link question_attempt}. 32 * 33 * The most important attributes of a step are the state, which is one of the 34 * {@link question_state} constants, the fraction, which may be null, or a 35 * number bewteen the attempt's minfraction and maxfraction, and the array of submitted 36 * data, about which more later. 37 * 38 * A step also tracks the time it was created, and the user responsible for 39 * creating it. 40 * 41 * The submitted data is basically just an array of name => value pairs, with 42 * certain conventions about the to divide the variables into four = two times two 43 * categories. 44 * 45 * Variables may either belong to the behaviour, in which case the 46 * name starts with a '-', or they may belong to the question type in which case 47 * they name does not start with a '-'. 48 * 49 * Second, variables may either be ones that came form the original request, in 50 * which case the name does not start with an _, or they are cached values that 51 * were created during processing, in which case the name does start with an _. 52 * 53 * That is, each name will start with one of '', '_'. '-' or '-_'. The remainder 54 * of the name should match the regex [a-z][a-z0-9]*. 55 * 56 * These variables can be accessed with {@link get_behaviour_var()} and {@link get_qt_var()}, 57 * - to be clear, ->get_behaviour_var('x') gets the variable with name '-x' - 58 * and values whose names start with '_' can be set using {@link set_behaviour_var()} 59 * and {@link set_qt_var()}. There are some other methods like {@link has_behaviour_var()} 60 * to check wether a varaible with a particular name is set, and {@link get_behaviour_data()} 61 * to get all the behaviour data as an associative array. 62 * 63 * @copyright 2009 The Open University 64 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 65 */ 66 class question_attempt_step { 67 /** 68 * @var integer if this attempts is stored in the question_attempts table, 69 * the id of that row. 70 */ 71 private $id = null; 72 73 /** 74 * @var question_state one of the {@link question_state} constants. 75 * The state after this step. 76 */ 77 private $state; 78 79 /** 80 * @var null|number the fraction (grade on a scale of 81 * minfraction .. maxfraction, normally 0..1) or null. 82 */ 83 private $fraction = null; 84 85 /** @var integer the timestamp when this step was created. */ 86 private $timecreated; 87 88 /** @var integer the id of the user resonsible for creating this step. */ 89 private $userid; 90 91 /** @var array name => value pairs. The submitted data. */ 92 private $data; 93 94 /** @var array name => array of {@link stored_file}s. Caches the contents of file areas. */ 95 private $files = array(); 96 97 /** 98 * You should not need to call this constructor in your own code. Steps are 99 * normally created by {@link question_attempt} methods like 100 * {@link question_attempt::process_action()}. 101 * @param array $data the submitted data that defines this step. 102 * @param int $timestamp the time to record for the action. (If not given, use now.) 103 * @param int $userid the user to attribute the aciton to. (If not given, use the current user.) 104 * @param int $existingstepid if this step is going to replace an existing step 105 * (for example, during a regrade) this is the id of the previous step we are replacing. 106 */ 107 public function __construct($data = array(), $timecreated = null, $userid = null, 108 $existingstepid = null) { 109 global $USER; 110 111 if (!is_array($data)) { 112 throw new coding_exception('$data must be an array when constructing a question_attempt_step.'); 113 } 114 $this->state = question_state::$unprocessed; 115 $this->data = $data; 116 if (is_null($timecreated)) { 117 $this->timecreated = time(); 118 } else { 119 $this->timecreated = $timecreated; 120 } 121 if (is_null($userid)) { 122 $this->userid = $USER->id; 123 } else { 124 $this->userid = $userid; 125 } 126 127 if (!is_null($existingstepid)) { 128 $this->id = $existingstepid; 129 } 130 } 131 132 /** 133 * @return int|null The id of this step in the database. null if this step 134 * is not stored in the database. 135 */ 136 public function get_id() { 137 return $this->id; 138 } 139 140 /** @return question_state The state after this step. */ 141 public function get_state() { 142 return $this->state; 143 } 144 145 /** 146 * Set the state. Normally only called by behaviours. 147 * @param question_state $state one of the {@link question_state} constants. 148 */ 149 public function set_state($state) { 150 $this->state = $state; 151 } 152 153 /** 154 * @return null|number the fraction (grade on a scale of 155 * minfraction .. maxfraction, normally 0..1), 156 * or null if this step has not been marked. 157 */ 158 public function get_fraction() { 159 return $this->fraction; 160 } 161 162 /** 163 * Set the fraction. Normally only called by behaviours. 164 * @param null|number $fraction the fraction to set. 165 */ 166 public function set_fraction($fraction) { 167 $this->fraction = $fraction; 168 } 169 170 /** @return int the id of the user resonsible for creating this step. */ 171 public function get_user_id() { 172 return $this->userid; 173 } 174 175 /** @return int the timestamp when this step was created. */ 176 public function get_timecreated() { 177 return $this->timecreated; 178 } 179 180 /** 181 * @param string $name the name of a question type variable to look for in the submitted data. 182 * @return bool whether a variable with this name exists in the question type data. 183 */ 184 public function has_qt_var($name) { 185 return array_key_exists($name, $this->data); 186 } 187 188 /** 189 * @param string $name the name of a question type variable to look for in the submitted data. 190 * @return string the requested variable, or null if the variable is not set. 191 */ 192 public function get_qt_var($name) { 193 if (!$this->has_qt_var($name)) { 194 return null; 195 } 196 return $this->data[$name]; 197 } 198 199 /** 200 * Set a cached question type variable. 201 * @param string $name the name of the variable to set. Must match _[a-z][a-z0-9]*. 202 * @param string $value the value to set. 203 */ 204 public function set_qt_var($name, $value) { 205 if ($name[0] != '_') { 206 throw new coding_exception('Cannot set question type data ' . $name . 207 ' on an attempt step. You can only set variables with names begining with _.'); 208 } 209 $this->data[$name] = $value; 210 } 211 212 /** 213 * Get the latest set of files for a particular question type variable of 214 * type question_attempt::PARAM_FILES. 215 * 216 * @param string $name the name of the associated variable. 217 * @return array of {@link stored_files}. 218 */ 219 public function get_qt_files($name, $contextid) { 220 if (array_key_exists($name, $this->files)) { 221 return $this->files[$name]; 222 } 223 224 if (!$this->has_qt_var($name)) { 225 $this->files[$name] = array(); 226 return array(); 227 } 228 229 $fs = get_file_storage(); 230 $this->files[$name] = $fs->get_area_files($contextid, 'question', 231 'response_' . $name, $this->id, 'sortorder', false); 232 233 return $this->files[$name]; 234 } 235 236 /** 237 * Prepare a draft file are for the files belonging the a response variable 238 * of this step. 239 * 240 * @param string $name the variable name the files belong to. 241 * @param int $contextid the id of the context the quba belongs to. 242 * @return int the draft itemid. 243 */ 244 public function prepare_response_files_draft_itemid($name, $contextid) { 245 list($draftid, $notused) = $this->prepare_response_files_draft_itemid_with_text( 246 $name, $contextid, null); 247 return $draftid; 248 } 249 250 /** 251 * Prepare a draft file are for the files belonging the a response variable 252 * of this step, while rewriting the URLs in some text. 253 * 254 * @param string $name the variable name the files belong to. 255 * @param int $contextid the id of the context the quba belongs to. 256 * @param string $text the text to update the URLs in. 257 * @return array(int, string) the draft itemid and the text with URLs rewritten. 258 */ 259 public function prepare_response_files_draft_itemid_with_text($name, $contextid, $text) { 260 $draftid = 0; // Will be filled in by file_prepare_draft_area. 261 $newtext = file_prepare_draft_area($draftid, $contextid, 'question', 262 'response_' . $name, $this->id, null, $text); 263 return array($draftid, $newtext); 264 } 265 266 /** 267 * Rewrite the @@PLUGINFILE@@ tokens in a response variable from this step 268 * that contains links to file. Normally you should probably call 269 * {@link question_attempt::rewrite_response_pluginfile_urls()} instead of 270 * calling this method directly. 271 * 272 * @param string $text the text to update the URLs in. 273 * @param int $contextid the id of the context the quba belongs to. 274 * @param string $name the variable name the files belong to. 275 * @param array $extra extra file path components. 276 * @return string the rewritten text. 277 */ 278 public function rewrite_response_pluginfile_urls($text, $contextid, $name, $extras) { 279 return question_rewrite_question_urls($text, 'pluginfile.php', $contextid, 280 'question', 'response_' . $name, $extras, $this->id); 281 } 282 283 /** 284 * Get all the question type variables. 285 * @param array name => value pairs. 286 */ 287 public function get_qt_data() { 288 $result = array(); 289 foreach ($this->data as $name => $value) { 290 if ($name[0] != '-' && $name[0] != ':') { 291 $result[$name] = $value; 292 } 293 } 294 return $result; 295 } 296 297 /** 298 * @param string $name the name of a behaviour variable to look for in the submitted data. 299 * @return bool whether a variable with this name exists in the question type data. 300 */ 301 public function has_behaviour_var($name) { 302 return array_key_exists('-' . $name, $this->data); 303 } 304 305 /** 306 * @param string $name the name of a behaviour variable to look for in the submitted data. 307 * @return string the requested variable, or null if the variable is not set. 308 */ 309 public function get_behaviour_var($name) { 310 if (!$this->has_behaviour_var($name)) { 311 return null; 312 } 313 return $this->data['-' . $name]; 314 } 315 316 /** 317 * Set a cached behaviour variable. 318 * @param string $name the name of the variable to set. Must match _[a-z][a-z0-9]*. 319 * @param string $value the value to set. 320 */ 321 public function set_behaviour_var($name, $value) { 322 if ($name[0] != '_') { 323 throw new coding_exception('Cannot set question type data ' . $name . 324 ' on an attempt step. You can only set variables with names begining with _.'); 325 } 326 return $this->data['-' . $name] = $value; 327 } 328 329 /** 330 * Get all the behaviour variables. 331 * @param array name => value pairs. 332 */ 333 public function get_behaviour_data() { 334 $result = array(); 335 foreach ($this->data as $name => $value) { 336 if ($name[0] == '-') { 337 $result[substr($name, 1)] = $value; 338 } 339 } 340 return $result; 341 } 342 343 /** 344 * Get all the submitted data, but not the cached data. behaviour 345 * variables have the - at the start of their name. This is only really 346 * intended for use by {@link question_attempt::regrade()}, it should not 347 * be considered part of the public API. 348 * @param array name => value pairs. 349 */ 350 public function get_submitted_data() { 351 $result = array(); 352 foreach ($this->data as $name => $value) { 353 if ($name[0] == '_' || ($name[0] == '-' && $name[1] == '_')) { 354 continue; 355 } 356 $result[$name] = $value; 357 } 358 return $result; 359 } 360 361 /** 362 * Get all the data. behaviour variables have the - at the start of 363 * their name. This is only intended for internal use, for example by 364 * {@link question_engine_data_mapper::insert_question_attempt_step()}, 365 * however, it can occasionally be useful in test code. It should not be 366 * considered part of the public API of this class. 367 * @param array name => value pairs. 368 */ 369 public function get_all_data() { 370 return $this->data; 371 } 372 373 /** 374 * Create a question_attempt_step from records loaded from the database. 375 * @param Iterator $records Raw records loaded from the database. 376 * @param int $stepid The id of the records to extract. 377 * @param string $qtype The question type of which this is an attempt. 378 * If not given, each record must include a qtype field. 379 * @return question_attempt_step The newly constructed question_attempt_step. 380 */ 381 public static function load_from_records($records, $attemptstepid, $qtype = null) { 382 $currentrec = $records->current(); 383 while ($currentrec->attemptstepid != $attemptstepid) { 384 $records->next(); 385 if (!$records->valid()) { 386 throw new coding_exception('Question attempt step ' . $attemptstepid . 387 ' not found in the database.'); 388 } 389 $currentrec = $records->current(); 390 } 391 392 $record = $currentrec; 393 $contextid = null; 394 $data = array(); 395 while ($currentrec && $currentrec->attemptstepid == $attemptstepid) { 396 if (!is_null($currentrec->name)) { 397 $data[$currentrec->name] = $currentrec->value; 398 } 399 $records->next(); 400 if ($records->valid()) { 401 $currentrec = $records->current(); 402 } else { 403 $currentrec = false; 404 } 405 } 406 407 $step = new question_attempt_step_read_only($data, $record->timecreated, $record->userid); 408 $step->state = question_state::get($record->state); 409 $step->id = $record->attemptstepid; 410 if (!is_null($record->fraction)) { 411 $step->fraction = $record->fraction + 0; 412 } 413 414 // This next chunk of code requires getting $contextid and $qtype here. 415 // Somehow, we need to get that information to this point by modifying 416 // all the paths by which this method can be called. 417 // Can we only return files when it's possible? Should there be some kind of warning? 418 if (is_null($qtype)) { 419 $qtype = $record->qtype; 420 } 421 foreach (question_bank::get_qtype($qtype)->response_file_areas() as $area) { 422 if (empty($step->data[$area])) { 423 continue; 424 } 425 426 $step->data[$area] = new question_file_loader($step, $area, $step->data[$area], $record->contextid); 427 } 428 429 return $step; 430 } 431 } 432 433 434 /** 435 * A subclass of {@link question_attempt_step} used when processing a new submission. 436 * 437 * When we are processing some new submitted data, which may or may not lead to 438 * a new step being added to the {@link question_usage_by_activity} we create an 439 * instance of this class. which is then passed to the question behaviour and question 440 * type for processing. At the end of processing we then may, or may not, keep it. 441 * 442 * @copyright 2010 The Open University 443 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 444 */ 445 class question_attempt_pending_step extends question_attempt_step { 446 /** @var string the new response summary, if there is one. */ 447 protected $newresponsesummary = null; 448 449 /** @var int the new variant number, if there is one. */ 450 protected $newvariant = null; 451 452 /** 453 * If as a result of processing this step, the response summary for the 454 * question attempt should changed, you should call this method to set the 455 * new summary. 456 * @param string $responsesummary the new response summary. 457 */ 458 public function set_new_response_summary($responsesummary) { 459 $this->newresponsesummary = $responsesummary; 460 } 461 462 /** 463 * Get the new response summary, if there is one. 464 * @return string the new response summary, or null if it has not changed. 465 */ 466 public function get_new_response_summary() { 467 return $this->newresponsesummary; 468 } 469 470 /** 471 * Whether this processing this step has changed the response summary. 472 * @return bool true if there is a new response summary. 473 */ 474 public function response_summary_changed() { 475 return !is_null($this->newresponsesummary); 476 } 477 478 /** 479 * If as a result of processing this step, you identify that this variant of the 480 * question is acutally identical to the another one, you may change the 481 * variant number recorded, in order to give better statistics. For an example 482 * see qbehaviour_opaque. 483 * @param int $variant the new variant number. 484 */ 485 public function set_new_variant_number($variant) { 486 $this->newvariant = $variant; 487 } 488 489 /** 490 * Get the new variant number, if there is one. 491 * @return int the new variant number, or null if it has not changed. 492 */ 493 public function get_new_variant_number() { 494 return $this->newvariant; 495 } 496 497 /** 498 * Whether this processing this step has changed the variant number. 499 * @return bool true if there is a new variant number. 500 */ 501 public function variant_number_changed() { 502 return !is_null($this->newvariant); 503 } 504 } 505 506 507 /** 508 * A subclass of {@link question_attempt_step} that cannot be modified. 509 * 510 * @copyright 2009 The Open University 511 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 512 */ 513 class question_attempt_step_read_only extends question_attempt_step { 514 public function set_state($state) { 515 throw new coding_exception('Cannot modify a question_attempt_step_read_only.'); 516 } 517 public function set_fraction($fraction) { 518 throw new coding_exception('Cannot modify a question_attempt_step_read_only.'); 519 } 520 public function set_qt_var($name, $value) { 521 throw new coding_exception('Cannot modify a question_attempt_step_read_only.'); 522 } 523 public function set_behaviour_var($name, $value) { 524 throw new coding_exception('Cannot modify a question_attempt_step_read_only.'); 525 } 526 } 527 528 529 /** 530 * A null {@link question_attempt_step} returned from 531 * {@link question_attempt::get_last_step()} etc. when a an attempt has just been 532 * created and there is no acutal step. 533 * 534 * @copyright 2009 The Open University 535 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 536 */ 537 class question_null_step { 538 public function get_state() { 539 return question_state::$notstarted; 540 } 541 542 public function set_state($state) { 543 throw new coding_exception('This question has not been started.'); 544 } 545 546 public function get_fraction() { 547 return null; 548 } 549 } 550 551 552 /** 553 * This is an adapter class that wraps a {@link question_attempt_step} and 554 * modifies the get/set_*_data methods so that they operate only on the parts 555 * that belong to a particular subquestion, as indicated by an extra prefix. 556 * 557 * @copyright 2010 The Open University 558 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 559 */ 560 class question_attempt_step_subquestion_adapter extends question_attempt_step { 561 /** @var question_attempt_step the step we are wrapping. */ 562 protected $realstep; 563 /** @var string the exta prefix on fields we work with. */ 564 protected $extraprefix; 565 566 /** 567 * Constructor. 568 * @param question_attempt_step $realqas the step to wrap. (Can be null if you 569 * just want to call add/remove.prefix.) 570 * @param unknown_type $extraprefix the extra prefix that is used for date fields. 571 */ 572 public function __construct($realqas, $extraprefix) { 573 $this->realqas = $realqas; 574 $this->extraprefix = $extraprefix; 575 } 576 577 /** 578 * Add the extra prefix to a field name. 579 * @param string $field the plain field name. 580 * @return string the field name with the extra bit of prefix added. 581 */ 582 public function add_prefix($field) { 583 if (substr($field, 0, 2) === '!_') { 584 return '-_' . $this->extraprefix . substr($field, 2); 585 } else if (substr($field, 0, 1) === '-') { 586 return '-' . $this->extraprefix . substr($field, 1); 587 } else if (substr($field, 0, 1) === '_') { 588 return '_' . $this->extraprefix . substr($field, 1); 589 } else { 590 return $this->extraprefix . $field; 591 } 592 } 593 594 /** 595 * Remove the extra prefix from a field name if it is present. 596 * @param string $field the extended field name. 597 * @return string the field name with the extra bit of prefix removed, or 598 * null if the extre prefix was not present. 599 */ 600 public function remove_prefix($field) { 601 if (preg_match('~^(-?_?)' . preg_quote($this->extraprefix, '~') . '(.*)$~', $field, $matches)) { 602 return $matches[1] . $matches[2]; 603 } else { 604 return null; 605 } 606 } 607 608 /** 609 * Filter some data to keep only those entries where the key contains 610 * extraprefix, and remove the extra prefix from the reutrned arrary. 611 * @param array $data some of the data stored in this step. 612 * @return array the data with the keys ajusted using {@link remove_prefix()}. 613 */ 614 public function filter_array($data) { 615 $result = array(); 616 foreach ($data as $fullname => $value) { 617 if ($name = $this->remove_prefix($fullname)) { 618 $result[$name] = $value; 619 } 620 } 621 return $result; 622 } 623 624 public function get_state() { 625 return $this->realqas->get_state(); 626 } 627 628 public function set_state($state) { 629 throw new coding_exception('Cannot modify a question_attempt_step_subquestion_adapter.'); 630 } 631 632 public function get_fraction() { 633 return $this->realqas->get_fraction(); 634 } 635 636 public function set_fraction($fraction) { 637 throw new coding_exception('Cannot modify a question_attempt_step_subquestion_adapter.'); 638 } 639 640 public function get_user_id() { 641 return $this->realqas->get_user_id; 642 } 643 644 public function get_timecreated() { 645 return $this->realqas->get_timecreated(); 646 } 647 648 public function has_qt_var($name) { 649 return $this->realqas->has_qt_var($this->add_prefix($name)); 650 } 651 652 public function get_qt_var($name) { 653 return $this->realqas->get_qt_var($this->add_prefix($name)); 654 } 655 656 public function set_qt_var($name, $value) { 657 return $this->realqas->set_qt_var($this->add_prefix($name), $value); 658 } 659 660 public function get_qt_data() { 661 return $this->filter_array($this->realqas->get_qt_data()); 662 } 663 664 public function has_behaviour_var($name) { 665 return $this->realqas->has_im_var($this->add_prefix($name)); 666 } 667 668 public function get_behaviour_var($name) { 669 return $this->realqas->get_im_var($this->add_prefix($name)); 670 } 671 672 public function set_behaviour_var($name, $value) { 673 return $this->realqas->set_im_var($this->add_prefix($name), $value); 674 } 675 676 public function get_behaviour_data() { 677 return $this->filter_array($this->realqas->get_behaviour_data()); 678 } 679 680 public function get_submitted_data() { 681 return $this->filter_array($this->realqas->get_submitted_data()); 682 } 683 684 public function get_all_data() { 685 return $this->filter_array($this->realqas->get_all_data()); 686 } 687 688 public function get_qt_files($name, $contextid) { 689 throw new coding_exception('No attempt has yet been made to implement files support in ' . 690 'question_attempt_step_subquestion_adapter.'); 691 } 692 693 public function prepare_response_files_draft_itemid($name, $contextid) { 694 throw new coding_exception('No attempt has yet been made to implement files support in ' . 695 'question_attempt_step_subquestion_adapter.'); 696 } 697 698 public function prepare_response_files_draft_itemid_with_text($name, $contextid, $text) { 699 throw new coding_exception('No attempt has yet been made to implement files support in ' . 700 'question_attempt_step_subquestion_adapter.'); 701 } 702 703 public function rewrite_response_pluginfile_urls($text, $contextid, $name, $extras) { 704 throw new coding_exception('No attempt has yet been made to implement files support in ' . 705 'question_attempt_step_subquestion_adapter.'); 706 } 707 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Fri Nov 28 20:29:05 2014 | Cross-referenced by PHPXref 0.7.1 |