[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  // This file is part of Moodle - http://moodle.org/
   4  //
   5  // Moodle is free software: you can redistribute it and/or modify
   6  // it under the terms of the GNU General Public License as published by
   7  // the Free Software Foundation, either version 3 of the License, or
   8  // (at your option) any later version.
   9  //
  10  // Moodle is distributed in the hope that it will be useful,
  11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  // GNU General Public License for more details.
  14  //
  15  // You should have received a copy of the GNU General Public License
  16  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17  
  18  require_once($CFG->dirroot.'/lib/gradelib.php');
  19  require_once($CFG->dirroot.'/grade/lib.php');
  20  require_once($CFG->dirroot.'/grade/export/grade_export_form.php');
  21  
  22  /**
  23   * Base export class
  24   */
  25  abstract class grade_export {
  26  
  27      public $plugin; // plgin name - must be filled in subclasses!
  28  
  29      public $grade_items; // list of all course grade items
  30      public $groupid;     // groupid, 0 means all groups
  31      public $course;      // course object
  32      public $columns;     // array of grade_items selected for export
  33  
  34      public $export_letters;  // export letters
  35      public $export_feedback; // export feedback
  36      public $userkey;         // export using private user key
  37  
  38      public $updatedgradesonly; // only export updated grades
  39  
  40      /**
  41       *  Grade display type (real, percentages or letter).
  42       *
  43       *  This attribute is an integer for XML file export. Otherwise is an array for all other formats (ODS, XLS and TXT).
  44       *
  45       *  @var $displaytype Grade display type constant (1, 2 or 3) or an array of display types where the key is the name
  46       *                    and the value is the grade display type constant or 0 for unchecked display types.
  47       * @access public.
  48       */
  49      public $displaytype;
  50      public $decimalpoints; // number of decimal points for exports
  51      public $onlyactive; // only include users with an active enrolment
  52      public $usercustomfields; // include users custom fields
  53  
  54      /**
  55       * @deprecated since Moodle 2.8
  56       * @var $previewrows Number of rows in preview.
  57       */
  58      public $previewrows;
  59  
  60      /**
  61       * Constructor should set up all the private variables ready to be pulled.
  62       *
  63       * This constructor used to accept the individual parameters as separate arguments, in
  64       * 2.8 this was simplified to just accept the data from the moodle form.
  65       *
  66       * @access public
  67       * @param object $course
  68       * @param int $groupid
  69       * @param stdClass|null $formdata
  70       * @note Exporting as letters will lead to data loss if that exported set it re-imported.
  71       */
  72      public function __construct($course, $groupid, $formdata) {
  73          if (func_num_args() != 3 || ($formdata != null && get_class($formdata) != "stdClass")) {
  74              $args = func_get_args();
  75              return call_user_func_array(array($this, "deprecated_constructor"), $args);
  76          }
  77          $this->course = $course;
  78          $this->groupid = $groupid;
  79  
  80          $this->grade_items = grade_item::fetch_all(array('courseid'=>$this->course->id));
  81  
  82          $this->process_form($formdata);
  83      }
  84  
  85      /**
  86       * Old deprecated constructor.
  87       *
  88       * This deprecated constructor accepts the individual parameters as separate arguments, in
  89       * 2.8 this was simplified to just accept the data from the moodle form.
  90       *
  91       * @deprecated since 2.8 MDL-46548. Instead call the shortened constructor which accepts the data
  92       * directly from the grade_export_form.
  93       */
  94      protected function deprecated_constructor($course,
  95                                                $groupid=0,
  96                                                $itemlist='',
  97                                                $export_feedback=false,
  98                                                $updatedgradesonly = false,
  99                                                $displaytype = GRADE_DISPLAY_TYPE_REAL,
 100                                                $decimalpoints = 2,
 101                                                $onlyactive = false,
 102                                                $usercustomfields = false) {
 103  
 104          debugging('Many argument constructor for class "grade_export" is deprecated. Call the 3 argument version instead.', DEBUG_DEVELOPER);
 105  
 106          $this->course = $course;
 107          $this->groupid = $groupid;
 108  
 109          $this->grade_items = grade_item::fetch_all(array('courseid'=>$this->course->id));
 110          //Populating the columns here is required by /grade/export/(whatever)/export.php
 111          //however index.php, when the form is submitted, will construct the collection here
 112          //with an empty $itemlist then reconstruct it in process_form() using $formdata
 113          $this->columns = array();
 114          if (!empty($itemlist)) {
 115              if ($itemlist=='-1') {
 116                  //user deselected all items
 117              } else {
 118                  $itemids = explode(',', $itemlist);
 119                  // remove items that are not requested
 120                  foreach ($itemids as $itemid) {
 121                      if (array_key_exists($itemid, $this->grade_items)) {
 122                          $this->columns[$itemid] =& $this->grade_items[$itemid];
 123                      }
 124                  }
 125              }
 126          } else {
 127              foreach ($this->grade_items as $itemid=>$unused) {
 128                  $this->columns[$itemid] =& $this->grade_items[$itemid];
 129              }
 130          }
 131  
 132          $this->export_feedback = $export_feedback;
 133          $this->userkey         = '';
 134          $this->previewrows     = false;
 135          $this->updatedgradesonly = $updatedgradesonly;
 136  
 137          $this->displaytype = $displaytype;
 138          $this->decimalpoints = $decimalpoints;
 139          $this->onlyactive = $onlyactive;
 140          $this->usercustomfields = $usercustomfields;
 141      }
 142  
 143      /**
 144       * Init object based using data from form
 145       * @param object $formdata
 146       */
 147      function process_form($formdata) {
 148          global $USER;
 149  
 150          $this->columns = array();
 151          if (!empty($formdata->itemids)) {
 152              if ($formdata->itemids=='-1') {
 153                  //user deselected all items
 154              } else {
 155                  foreach ($formdata->itemids as $itemid=>$selected) {
 156                      if ($selected and array_key_exists($itemid, $this->grade_items)) {
 157                          $this->columns[$itemid] =& $this->grade_items[$itemid];
 158                      }
 159                  }
 160              }
 161          } else {
 162              foreach ($this->grade_items as $itemid=>$unused) {
 163                  $this->columns[$itemid] =& $this->grade_items[$itemid];
 164              }
 165          }
 166  
 167          if (isset($formdata->key)) {
 168              if ($formdata->key == 1 && isset($formdata->iprestriction) && isset($formdata->validuntil)) {
 169                  // Create a new key
 170                  $formdata->key = create_user_key('grade/export', $USER->id, $this->course->id, $formdata->iprestriction, $formdata->validuntil);
 171              }
 172              $this->userkey = $formdata->key;
 173          }
 174  
 175          if (isset($formdata->decimals)) {
 176              $this->decimalpoints = $formdata->decimals;
 177          }
 178  
 179          if (isset($formdata->export_letters)) {
 180              $this->export_letters = $formdata->export_letters;
 181          }
 182  
 183          if (isset($formdata->export_feedback)) {
 184              $this->export_feedback = $formdata->export_feedback;
 185          }
 186  
 187          if (isset($formdata->export_onlyactive)) {
 188              $this->onlyactive = $formdata->export_onlyactive;
 189          }
 190  
 191          if (isset($formdata->previewrows)) {
 192              $this->previewrows = $formdata->previewrows;
 193          }
 194  
 195          if (isset($formdata->display)) {
 196              $this->displaytype = $formdata->display;
 197  
 198              // Used by grade exports which accept multiple display types.
 199              // If the checkbox value is 0 (unchecked) then remove it.
 200              if (is_array($formdata->display)) {
 201                  $this->displaytype = array_filter($formdata->display);
 202              }
 203          }
 204  
 205          if (isset($formdata->updatedgradesonly)) {
 206              $this->updatedgradesonly = $formdata->updatedgradesonly;
 207          }
 208      }
 209  
 210      /**
 211       * Update exported field in grade_grades table
 212       * @return boolean
 213       */
 214      public function track_exports() {
 215          global $CFG;
 216  
 217          /// Whether this plugin is entitled to update export time
 218          if ($expplugins = explode(",", $CFG->gradeexport)) {
 219              if (in_array($this->plugin, $expplugins)) {
 220                  return true;
 221              } else {
 222                  return false;
 223            }
 224          } else {
 225              return false;
 226          }
 227      }
 228  
 229      /**
 230       * Returns string representation of final grade
 231       * @param object $grade instance of grade_grade class
 232       * @param integer $gradedisplayconst grade display type constant.
 233       * @return string
 234       */
 235      public function format_grade($grade, $gradedisplayconst = null) {
 236          $displaytype = $this->displaytype;
 237          if (is_array($this->displaytype) && !is_null($gradedisplayconst)) {
 238              $displaytype = $gradedisplayconst;
 239          }
 240          return grade_format_gradevalue($grade->finalgrade, $this->grade_items[$grade->itemid], false, $displaytype, $this->decimalpoints);
 241      }
 242  
 243      /**
 244       * Returns the name of column in export
 245       * @param object $grade_item
 246       * @param boolean $feedback feedback colum
 247       * @param string $gradedisplayname grade display name.
 248       * @return string
 249       */
 250      public function format_column_name($grade_item, $feedback=false, $gradedisplayname = null) {
 251          $column = new stdClass();
 252  
 253          if ($grade_item->itemtype == 'mod') {
 254              $column->name = get_string('modulename', $grade_item->itemmodule).get_string('labelsep', 'langconfig').$grade_item->get_name();
 255          } else {
 256              $column->name = $grade_item->get_name();
 257          }
 258  
 259          // We can't have feedback and display type at the same time.
 260          $column->extra = ($feedback) ? get_string('feedback') : get_string($gradedisplayname, 'grades');
 261  
 262          return html_to_text(get_string('gradeexportcolumntype', 'grades', $column), 0, false);
 263      }
 264  
 265      /**
 266       * Returns formatted grade feedback
 267       * @param object $feedback object with properties feedback and feedbackformat
 268       * @return string
 269       */
 270      public function format_feedback($feedback) {
 271          return strip_tags(format_text($feedback->feedback, $feedback->feedbackformat));
 272      }
 273  
 274      /**
 275       * Implemented by child class
 276       */
 277      public abstract function print_grades();
 278  
 279      /**
 280       * Prints preview of exported grades on screen as a feedback mechanism
 281       * @param bool $require_user_idnumber true means skip users without idnumber
 282       * @deprecated since 2.8 MDL-46548. Previews are not useful on export.
 283       */
 284      public function display_preview($require_user_idnumber=false) {
 285          global $OUTPUT;
 286  
 287          debugging('function grade_export::display_preview is deprecated.', DEBUG_DEVELOPER);
 288  
 289          $userprofilefields = grade_helper::get_user_profile_fields($this->course->id, $this->usercustomfields);
 290          $formatoptions = new stdClass();
 291          $formatoptions->para = false;
 292  
 293          echo $OUTPUT->heading(get_string('previewrows', 'grades'));
 294  
 295          echo '<table>';
 296          echo '<tr>';
 297          foreach ($userprofilefields as $field) {
 298              echo '<th>' . $field->fullname . '</th>';
 299          }
 300          if (!$this->onlyactive) {
 301              echo '<th>'.get_string("suspended")."</th>";
 302          }
 303          foreach ($this->columns as $grade_item) {
 304              echo '<th>'.$this->format_column_name($grade_item).'</th>';
 305  
 306              /// add a column_feedback column
 307              if ($this->export_feedback) {
 308                  echo '<th>'.$this->format_column_name($grade_item, true).'</th>';
 309              }
 310          }
 311          echo '</tr>';
 312          /// Print all the lines of data.
 313          $i = 0;
 314          $gui = new graded_users_iterator($this->course, $this->columns, $this->groupid);
 315          $gui->require_active_enrolment($this->onlyactive);
 316          $gui->allow_user_custom_fields($this->usercustomfields);
 317          $gui->init();
 318          while ($userdata = $gui->next_user()) {
 319              // number of preview rows
 320              if ($this->previewrows and $this->previewrows <= $i) {
 321                  break;
 322              }
 323              $user = $userdata->user;
 324              if ($require_user_idnumber and empty($user->idnumber)) {
 325                  // some exports require user idnumber so we can match up students when importing the data
 326                  continue;
 327              }
 328  
 329              $gradeupdated = false; // if no grade is update at all for this user, do not display this row
 330              $rowstr = '';
 331              foreach ($this->columns as $itemid=>$unused) {
 332                  $gradetxt = $this->format_grade($userdata->grades[$itemid]);
 333  
 334                  // get the status of this grade, and put it through track to get the status
 335                  $g = new grade_export_update_buffer();
 336                  $grade_grade = new grade_grade(array('itemid'=>$itemid, 'userid'=>$user->id));
 337                  $status = $g->track($grade_grade);
 338  
 339                  if ($this->updatedgradesonly && ($status == 'nochange' || $status == 'unknown')) {
 340                      $rowstr .= '<td>'.get_string('unchangedgrade', 'grades').'</td>';
 341                  } else {
 342                      $rowstr .= "<td>$gradetxt</td>";
 343                      $gradeupdated = true;
 344                  }
 345  
 346                  if ($this->export_feedback) {
 347                      $rowstr .=  '<td>'.$this->format_feedback($userdata->feedbacks[$itemid]).'</td>';
 348                  }
 349              }
 350  
 351              // if we are requesting updated grades only, we are not interested in this user at all
 352              if (!$gradeupdated && $this->updatedgradesonly) {
 353                  continue;
 354              }
 355  
 356              echo '<tr>';
 357              foreach ($userprofilefields as $field) {
 358                  $fieldvalue = grade_helper::get_user_field_value($user, $field);
 359                  // @see profile_field_base::display_data().
 360                  echo '<td>' . format_text($fieldvalue, FORMAT_MOODLE, $formatoptions) . '</td>';
 361              }
 362              if (!$this->onlyactive) {
 363                  $issuspended = ($user->suspendedenrolment) ? get_string('yes') : '';
 364                  echo "<td>$issuspended</td>";
 365              }
 366              echo $rowstr;
 367              echo "</tr>";
 368  
 369              $i++; // increment the counter
 370          }
 371          echo '</table>';
 372          $gui->close();
 373      }
 374  
 375      /**
 376       * Returns array of parameters used by dump.php and export.php.
 377       * @return array
 378       */
 379      public function get_export_params() {
 380          $itemids = array_keys($this->columns);
 381          $itemidsparam = implode(',', $itemids);
 382          if (empty($itemidsparam)) {
 383              $itemidsparam = '-1';
 384          }
 385  
 386          $params = array('id'                =>$this->course->id,
 387                          'groupid'           =>$this->groupid,
 388                          'itemids'           =>$itemidsparam,
 389                          'export_letters'    =>$this->export_letters,
 390                          'export_feedback'   =>$this->export_feedback,
 391                          'updatedgradesonly' =>$this->updatedgradesonly,
 392                          'displaytype'       =>$this->displaytype,
 393                          'decimalpoints'     =>$this->decimalpoints,
 394                          'export_onlyactive' =>$this->onlyactive,
 395                          'usercustomfields'  =>$this->usercustomfields);
 396  
 397          return $params;
 398      }
 399  
 400      /**
 401       * Either prints a "Export" box, which will redirect the user to the download page,
 402       * or prints the URL for the published data.
 403       *
 404       * @deprecated since 2.8 MDL-46548. Call get_export_url and set the
 405       *             action of the grade_export_form instead.
 406       * @return void
 407       */
 408      public function print_continue() {
 409          global $CFG, $OUTPUT;
 410  
 411          debugging('function grade_export::print_continue is deprecated.', DEBUG_DEVELOPER);
 412          $params = $this->get_export_params();
 413  
 414          echo $OUTPUT->heading(get_string('export', 'grades'));
 415  
 416          echo $OUTPUT->container_start('gradeexportlink');
 417  
 418          if (!$this->userkey) {
 419              // This button should trigger a download prompt.
 420              $url = new moodle_url('/grade/export/'.$this->plugin.'/export.php', $params);
 421              echo $OUTPUT->single_button($url, get_string('download', 'admin'));
 422  
 423          } else {
 424              $paramstr = '';
 425              $sep = '?';
 426              foreach($params as $name=>$value) {
 427                  $paramstr .= $sep.$name.'='.$value;
 428                  $sep = '&';
 429              }
 430  
 431              $link = $CFG->wwwroot.'/grade/export/'.$this->plugin.'/dump.php'.$paramstr.'&key='.$this->userkey;
 432  
 433              echo get_string('download', 'admin').': ' . html_writer::link($link, $link);
 434          }
 435          echo $OUTPUT->container_end();
 436  
 437          return;
 438      }
 439  }
 440  
 441  /**
 442   * This class is used to update the exported field in grade_grades.
 443   * It does internal buffering to speedup the db operations.
 444   */
 445  class grade_export_update_buffer {
 446      public $update_list;
 447      public $export_time;
 448  
 449      /**
 450       * Constructor - creates the buffer and initialises the time stamp
 451       */
 452      public function grade_export_update_buffer() {
 453          $this->update_list = array();
 454          $this->export_time = time();
 455      }
 456  
 457      public function flush($buffersize) {
 458          global $CFG, $DB;
 459  
 460          if (count($this->update_list) > $buffersize) {
 461              list($usql, $params) = $DB->get_in_or_equal($this->update_list);
 462              $params = array_merge(array($this->export_time), $params);
 463  
 464              $sql = "UPDATE {grade_grades} SET exported = ? WHERE id $usql";
 465              $DB->execute($sql, $params);
 466              $this->update_list = array();
 467          }
 468      }
 469  
 470      /**
 471       * Track grade export status
 472       * @param object $grade_grade
 473       * @return string $status (unknow, new, regrade, nochange)
 474       */
 475      public function track($grade_grade) {
 476  
 477          if (empty($grade_grade->exported) or empty($grade_grade->timemodified)) {
 478              if (is_null($grade_grade->finalgrade)) {
 479                  // grade does not exist yet
 480                  $status = 'unknown';
 481              } else {
 482                  $status = 'new';
 483                  $this->update_list[] = $grade_grade->id;
 484              }
 485  
 486          } else if ($grade_grade->exported < $grade_grade->timemodified) {
 487              $status = 'regrade';
 488              $this->update_list[] = $grade_grade->id;
 489  
 490          } else if ($grade_grade->exported >= $grade_grade->timemodified) {
 491              $status = 'nochange';
 492  
 493          } else {
 494              // something is wrong?
 495              $status = 'unknown';
 496          }
 497  
 498          $this->flush(100);
 499  
 500          return $status;
 501      }
 502  
 503      /**
 504       * Flush and close the buffer.
 505       */
 506      public function close() {
 507          $this->flush(0);
 508      }
 509  }
 510  
 511  /**
 512   * Verify that there is a valid set of grades to export.
 513   * @param $courseid int The course being exported
 514   */
 515  function export_verify_grades($courseid) {
 516      $regraderesult = grade_regrade_final_grades($courseid);
 517      if (is_array($regraderesult)) {
 518          throw new moodle_exception('gradecantregrade', 'error', '', implode(', ', array_unique($regraderesult)));
 519      }
 520  }