[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 contains the definition for the library class for comment feedback plugin
  19   *
  20   * @package   assignfeedback_comments
  21   * @copyright 2012 NetSpot {@link http://www.netspot.com.au}
  22   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  defined('MOODLE_INTERNAL') || die();
  26  
  27  /**
  28   * Library class for comment feedback plugin extending feedback plugin base class.
  29   *
  30   * @package   assignfeedback_comments
  31   * @copyright 2012 NetSpot {@link http://www.netspot.com.au}
  32   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  33   */
  34  class assign_feedback_comments extends assign_feedback_plugin {
  35  
  36      /**
  37       * Get the name of the online comment feedback plugin.
  38       * @return string
  39       */
  40      public function get_name() {
  41          return get_string('pluginname', 'assignfeedback_comments');
  42      }
  43  
  44      /**
  45       * Get the feedback comment from the database.
  46       *
  47       * @param int $gradeid
  48       * @return stdClass|false The feedback comments for the given grade if it exists.
  49       *                        False if it doesn't.
  50       */
  51      public function get_feedback_comments($gradeid) {
  52          global $DB;
  53          return $DB->get_record('assignfeedback_comments', array('grade'=>$gradeid));
  54      }
  55  
  56      /**
  57       * Get quickgrading form elements as html.
  58       *
  59       * @param int $userid The user id in the table this quickgrading element relates to
  60       * @param mixed $grade - The grade data - may be null if there are no grades for this user (yet)
  61       * @return mixed - A html string containing the html form elements required for quickgrading
  62       */
  63      public function get_quickgrading_html($userid, $grade) {
  64          $commenttext = '';
  65          if ($grade) {
  66              $feedbackcomments = $this->get_feedback_comments($grade->id);
  67              if ($feedbackcomments) {
  68                  $commenttext = $feedbackcomments->commenttext;
  69              }
  70          }
  71  
  72          $pluginname = get_string('pluginname', 'assignfeedback_comments');
  73          $labeloptions = array('for'=>'quickgrade_comments_' . $userid,
  74                                'class'=>'accesshide');
  75          $textareaoptions = array('name'=>'quickgrade_comments_' . $userid,
  76                                   'id'=>'quickgrade_comments_' . $userid,
  77                                   'class'=>'quickgrade');
  78          return html_writer::tag('label', $pluginname, $labeloptions) .
  79                 html_writer::tag('textarea', $commenttext, $textareaoptions);
  80      }
  81  
  82      /**
  83       * Has the plugin quickgrading form element been modified in the current form submission?
  84       *
  85       * @param int $userid The user id in the table this quickgrading element relates to
  86       * @param stdClass $grade The grade
  87       * @return boolean - true if the quickgrading form element has been modified
  88       */
  89      public function is_quickgrading_modified($userid, $grade) {
  90          $commenttext = '';
  91          if ($grade) {
  92              $feedbackcomments = $this->get_feedback_comments($grade->id);
  93              if ($feedbackcomments) {
  94                  $commenttext = $feedbackcomments->commenttext;
  95              }
  96          }
  97          // Note that this handles the difference between empty and not in the quickgrading
  98          // form at all (hidden column).
  99          $newvalue = optional_param('quickgrade_comments_' . $userid, false, PARAM_TEXT);
 100          return ($newvalue !== false) && ($newvalue != $commenttext);
 101      }
 102  
 103  
 104      /**
 105       * Override to indicate a plugin supports quickgrading.
 106       *
 107       * @return boolean - True if the plugin supports quickgrading
 108       */
 109      public function supports_quickgrading() {
 110          return true;
 111      }
 112  
 113      /**
 114       * Return a list of the text fields that can be imported/exported by this plugin.
 115       *
 116       * @return array An array of field names and descriptions. (name=>description, ...)
 117       */
 118      public function get_editor_fields() {
 119          return array('comments' => get_string('pluginname', 'assignfeedback_comments'));
 120      }
 121  
 122      /**
 123       * Get the saved text content from the editor.
 124       *
 125       * @param string $name
 126       * @param int $gradeid
 127       * @return string
 128       */
 129      public function get_editor_text($name, $gradeid) {
 130          if ($name == 'comments') {
 131              $feedbackcomments = $this->get_feedback_comments($gradeid);
 132              if ($feedbackcomments) {
 133                  return $feedbackcomments->commenttext;
 134              }
 135          }
 136  
 137          return '';
 138      }
 139  
 140      /**
 141       * Get the saved text content from the editor.
 142       *
 143       * @param string $name
 144       * @param string $value
 145       * @param int $gradeid
 146       * @return string
 147       */
 148      public function set_editor_text($name, $value, $gradeid) {
 149          global $DB;
 150  
 151          if ($name == 'comments') {
 152              $feedbackcomment = $this->get_feedback_comments($gradeid);
 153              if ($feedbackcomment) {
 154                  $feedbackcomment->commenttext = $value;
 155                  return $DB->update_record('assignfeedback_comments', $feedbackcomment);
 156              } else {
 157                  $feedbackcomment = new stdClass();
 158                  $feedbackcomment->commenttext = $value;
 159                  $feedbackcomment->commentformat = FORMAT_HTML;
 160                  $feedbackcomment->grade = $gradeid;
 161                  $feedbackcomment->assignment = $this->assignment->get_instance()->id;
 162                  return $DB->insert_record('assignfeedback_comments', $feedbackcomment) > 0;
 163              }
 164          }
 165  
 166          return false;
 167      }
 168  
 169      /**
 170       * Save quickgrading changes.
 171       *
 172       * @param int $userid The user id in the table this quickgrading element relates to
 173       * @param stdClass $grade The grade
 174       * @return boolean - true if the grade changes were saved correctly
 175       */
 176      public function save_quickgrading_changes($userid, $grade) {
 177          global $DB;
 178          $feedbackcomment = $this->get_feedback_comments($grade->id);
 179          $feedbackpresent = optional_param('quickgrade_comments_' . $userid, false, PARAM_TEXT) !== false;
 180          if (!$feedbackpresent) {
 181              // Nothing to save (e.g. hidden column).
 182              return true;
 183          }
 184          if ($feedbackcomment) {
 185              $feedbackcomment->commenttext = optional_param('quickgrade_comments_' . $userid, '', PARAM_TEXT);
 186              return $DB->update_record('assignfeedback_comments', $feedbackcomment);
 187          } else {
 188              $feedbackcomment = new stdClass();
 189              $feedbackcomment->commenttext = optional_param('quickgrade_comments_' . $userid, '', PARAM_TEXT);
 190              $feedbackcomment->commentformat = FORMAT_HTML;
 191              $feedbackcomment->grade = $grade->id;
 192              $feedbackcomment->assignment = $this->assignment->get_instance()->id;
 193              return $DB->insert_record('assignfeedback_comments', $feedbackcomment) > 0;
 194          }
 195      }
 196  
 197      /**
 198       * Save the settings for feedback comments plugin
 199       *
 200       * @param stdClass $data
 201       * @return bool
 202       */
 203      public function save_settings(stdClass $data) {
 204          $this->set_config('commentinline', !empty($data->assignfeedback_comments_commentinline));
 205          return true;
 206      }
 207  
 208      /**
 209       * Get the default setting for feedback comments plugin
 210       *
 211       * @param MoodleQuickForm $mform The form to add elements to
 212       * @return void
 213       */
 214      public function get_settings(MoodleQuickForm $mform) {
 215          $default = $this->get_config('commentinline');
 216          $mform->addElement('selectyesno',
 217                             'assignfeedback_comments_commentinline',
 218                             get_string('commentinline', 'assignfeedback_comments'));
 219          $mform->addHelpButton('assignfeedback_comments_commentinline', 'commentinline', 'assignfeedback_comments');
 220          $mform->setDefault('assignfeedback_comments_commentinline', $default);
 221          // Disable comment online if comment feedback plugin is disabled.
 222          $mform->disabledIf('assignfeedback_comments_commentinline', 'assignfeedback_comments_enabled', 'notchecked');
 223     }
 224  
 225      /**
 226       * Convert the text from any submission plugin that has an editor field to
 227       * a format suitable for inserting in the feedback text field.
 228       *
 229       * @param stdClass $submission
 230       * @param stdClass $data - Form data to be filled with the converted submission text and format.
 231       * @return boolean - True if feedback text was set.
 232       */
 233      protected function convert_submission_text_to_feedback($submission, $data) {
 234          $format = false;
 235          $text = '';
 236  
 237          foreach ($this->assignment->get_submission_plugins() as $plugin) {
 238              $fields = $plugin->get_editor_fields();
 239              if ($plugin->is_enabled() && $plugin->is_visible() && !$plugin->is_empty($submission) && !empty($fields)) {
 240                  foreach ($fields as $key => $description) {
 241                      $rawtext = strip_pluginfile_content($plugin->get_editor_text($key, $submission->id));
 242  
 243                      $newformat = $plugin->get_editor_format($key, $submission->id);
 244  
 245                      if ($format !== false && $newformat != $format) {
 246                          // There are 2 or more editor fields using different formats, set to plain as a fallback.
 247                          $format = FORMAT_PLAIN;
 248                      } else {
 249                          $format = $newformat;
 250                      }
 251                      $text .= $rawtext;
 252                  }
 253              }
 254          }
 255  
 256          if ($format === false) {
 257              $format = FORMAT_HTML;
 258          }
 259          $data->assignfeedbackcomments_editor['text'] = $text;
 260          $data->assignfeedbackcomments_editor['format'] = $format;
 261  
 262          return true;
 263      }
 264  
 265      /**
 266       * Get form elements for the grading page
 267       *
 268       * @param stdClass|null $grade
 269       * @param MoodleQuickForm $mform
 270       * @param stdClass $data
 271       * @return bool true if elements were added to the form
 272       */
 273      public function get_form_elements_for_user($grade, MoodleQuickForm $mform, stdClass $data, $userid) {
 274          $commentinlinenabled = $this->get_config('commentinline');
 275          $submission = $this->assignment->get_user_submission($userid, false);
 276          $feedbackcomments = false;
 277  
 278          if ($grade) {
 279              $feedbackcomments = $this->get_feedback_comments($grade->id);
 280          }
 281  
 282          if ($feedbackcomments && !empty($feedbackcomments->commenttext)) {
 283              $data->assignfeedbackcomments_editor['text'] = $feedbackcomments->commenttext;
 284              $data->assignfeedbackcomments_editor['format'] = $feedbackcomments->commentformat;
 285          } else {
 286              // No feedback given yet - maybe we need to copy the text from the submission?
 287              if (!empty($commentinlinenabled) && $submission) {
 288                  $this->convert_submission_text_to_feedback($submission, $data);
 289              }
 290          }
 291  
 292          $mform->addElement('editor', 'assignfeedbackcomments_editor', $this->get_name(), null, null);
 293  
 294          return true;
 295      }
 296  
 297      /**
 298       * Saving the comment content into database.
 299       *
 300       * @param stdClass $grade
 301       * @param stdClass $data
 302       * @return bool
 303       */
 304      public function save(stdClass $grade, stdClass $data) {
 305          global $DB;
 306          $feedbackcomment = $this->get_feedback_comments($grade->id);
 307          if ($feedbackcomment) {
 308              $feedbackcomment->commenttext = $data->assignfeedbackcomments_editor['text'];
 309              $feedbackcomment->commentformat = $data->assignfeedbackcomments_editor['format'];
 310              return $DB->update_record('assignfeedback_comments', $feedbackcomment);
 311          } else {
 312              $feedbackcomment = new stdClass();
 313              $feedbackcomment->commenttext = $data->assignfeedbackcomments_editor['text'];
 314              $feedbackcomment->commentformat = $data->assignfeedbackcomments_editor['format'];
 315              $feedbackcomment->grade = $grade->id;
 316              $feedbackcomment->assignment = $this->assignment->get_instance()->id;
 317              return $DB->insert_record('assignfeedback_comments', $feedbackcomment) > 0;
 318          }
 319      }
 320  
 321      /**
 322       * Display the comment in the feedback table.
 323       *
 324       * @param stdClass $grade
 325       * @param bool $showviewlink Set to true to show a link to view the full feedback
 326       * @return string
 327       */
 328      public function view_summary(stdClass $grade, & $showviewlink) {
 329          $feedbackcomments = $this->get_feedback_comments($grade->id);
 330          if ($feedbackcomments) {
 331              $text = format_text($feedbackcomments->commenttext,
 332                                  $feedbackcomments->commentformat,
 333                                  array('context' => $this->assignment->get_context()));
 334              $short = shorten_text($text, 140);
 335  
 336              // Show the view all link if the text has been shortened.
 337              $showviewlink = $short != $text;
 338              return $short;
 339          }
 340          return '';
 341      }
 342  
 343      /**
 344       * Display the comment in the feedback table.
 345       *
 346       * @param stdClass $grade
 347       * @return string
 348       */
 349      public function view(stdClass $grade) {
 350          $feedbackcomments = $this->get_feedback_comments($grade->id);
 351          if ($feedbackcomments) {
 352              return format_text($feedbackcomments->commenttext,
 353                                 $feedbackcomments->commentformat,
 354                                 array('context' => $this->assignment->get_context()));
 355          }
 356          return '';
 357      }
 358  
 359      /**
 360       * Return true if this plugin can upgrade an old Moodle 2.2 assignment of this type
 361       * and version.
 362       *
 363       * @param string $type old assignment subtype
 364       * @param int $version old assignment version
 365       * @return bool True if upgrade is possible
 366       */
 367      public function can_upgrade($type, $version) {
 368  
 369          if (($type == 'upload' || $type == 'uploadsingle' ||
 370               $type == 'online' || $type == 'offline') && $version >= 2011112900) {
 371              return true;
 372          }
 373          return false;
 374      }
 375  
 376      /**
 377       * Upgrade the settings from the old assignment to the new plugin based one
 378       *
 379       * @param context $oldcontext - the context for the old assignment
 380       * @param stdClass $oldassignment - the data for the old assignment
 381       * @param string $log - can be appended to by the upgrade
 382       * @return bool was it a success? (false will trigger a rollback)
 383       */
 384      public function upgrade_settings(context $oldcontext, stdClass $oldassignment, & $log) {
 385          if ($oldassignment->assignmenttype == 'online') {
 386              $this->set_config('commentinline', $oldassignment->var1);
 387              return true;
 388          }
 389          return true;
 390      }
 391  
 392      /**
 393       * Upgrade the feedback from the old assignment to the new one
 394       *
 395       * @param context $oldcontext - the database for the old assignment context
 396       * @param stdClass $oldassignment The data record for the old assignment
 397       * @param stdClass $oldsubmission The data record for the old submission
 398       * @param stdClass $grade The data record for the new grade
 399       * @param string $log Record upgrade messages in the log
 400       * @return bool true or false - false will trigger a rollback
 401       */
 402      public function upgrade(context $oldcontext,
 403                              stdClass $oldassignment,
 404                              stdClass $oldsubmission,
 405                              stdClass $grade,
 406                              & $log) {
 407          global $DB;
 408  
 409          $feedbackcomments = new stdClass();
 410          $feedbackcomments->commenttext = $oldsubmission->submissioncomment;
 411          $feedbackcomments->commentformat = FORMAT_HTML;
 412  
 413          $feedbackcomments->grade = $grade->id;
 414          $feedbackcomments->assignment = $this->assignment->get_instance()->id;
 415          if (!$DB->insert_record('assignfeedback_comments', $feedbackcomments) > 0) {
 416              $log .= get_string('couldnotconvertgrade', 'mod_assign', $grade->userid);
 417              return false;
 418          }
 419  
 420          return true;
 421      }
 422  
 423      /**
 424       * If this plugin adds to the gradebook comments field, it must specify the format of the text
 425       * of the comment
 426       *
 427       * Only one feedback plugin can push comments to the gradebook and that is chosen by the assignment
 428       * settings page.
 429       *
 430       * @param stdClass $grade The grade
 431       * @return int
 432       */
 433      public function format_for_gradebook(stdClass $grade) {
 434          $feedbackcomments = $this->get_feedback_comments($grade->id);
 435          if ($feedbackcomments) {
 436              return $feedbackcomments->commentformat;
 437          }
 438          return FORMAT_MOODLE;
 439      }
 440  
 441      /**
 442       * If this plugin adds to the gradebook comments field, it must format the text
 443       * of the comment
 444       *
 445       * Only one feedback plugin can push comments to the gradebook and that is chosen by the assignment
 446       * settings page.
 447       *
 448       * @param stdClass $grade The grade
 449       * @return string
 450       */
 451      public function text_for_gradebook(stdClass $grade) {
 452          $feedbackcomments = $this->get_feedback_comments($grade->id);
 453          if ($feedbackcomments) {
 454              return $feedbackcomments->commenttext;
 455          }
 456          return '';
 457      }
 458  
 459      /**
 460       * The assignment has been deleted - cleanup
 461       *
 462       * @return bool
 463       */
 464      public function delete_instance() {
 465          global $DB;
 466          // Will throw exception on failure.
 467          $DB->delete_records('assignfeedback_comments',
 468                              array('assignment'=>$this->assignment->get_instance()->id));
 469          return true;
 470      }
 471  
 472      /**
 473       * Returns true if there are no feedback comments for the given grade.
 474       *
 475       * @param stdClass $grade
 476       * @return bool
 477       */
 478      public function is_empty(stdClass $grade) {
 479          return $this->view($grade) == '';
 480      }
 481  
 482      /**
 483       * Return a description of external params suitable for uploading an feedback comment from a webservice.
 484       *
 485       * @return external_description|null
 486       */
 487      public function get_external_parameters() {
 488          $editorparams = array('text' => new external_value(PARAM_TEXT, 'The text for this feedback.'),
 489                                'format' => new external_value(PARAM_INT, 'The format for this feedback'));
 490          $editorstructure = new external_single_structure($editorparams);
 491          return array('assignfeedbackcomments_editor' => $editorstructure);
 492      }
 493  
 494  }