grade/export/lib.php

   1 <?php
   2
   3 ///////////////////////////////////////////////////////////////////////////
   4 //                                                                       //
   5 // NOTICE OF COPYRIGHT                                                   //
   6 //                                                                       //
   7 // Moodle - Modular Object-Oriented Dynamic Learning Environment         //
   8 //          http://moodle.com                                            //
   9 //                                                                       //
  10 // Copyright (C) 1999 onwards  Martin Dougiamas  http://moodle.com       //
  11 //                                                                       //
  12 // This program is free software; you can redistribute it and/or modify  //
  13 // it under the terms of the GNU General Public License as published by  //
  14 // the Free Software Foundation; either version 2 of the License, or     //
  15 // (at your option) any later version.                                   //
  16 //                                                                       //
  17 // This program is distributed in the hope that it will be useful,       //
  18 // but WITHOUT ANY WARRANTY; without even the implied warranty of        //
  19 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
  20 // GNU General Public License for more details:                          //
  21 //                                                                       //
  22 //          http://www.gnu.org/copyleft/gpl.html                         //
  23 //                                                                       //
  24 ///////////////////////////////////////////////////////////////////////////
  25
  26 require_once($CFG->dirroot.'/lib/gradelib.php');
  27 require_once($CFG->dirroot.'/grade/lib.php');
  28 require_once($CFG->dirroot.'/grade/export/grade_export_form.php');
  29
  30 /**
  31  * Base export class
  32  */
  33 class grade_export {
  34
  35     var $plugin; // plgin name - must be filled in subclasses!
  36
  37     var $grade_items; // list of all course grade items
  38     var $groupid;     // groupid, 0 means all groups
  39     var $course;      // course object
  40     var $columns;     // array of grade_items selected for export
  41
  42     var $previewrows;     // number of rows in preview
  43     var $export_letters;  // export letters
  44     var $export_feedback; // export feedback
  45     var $userkey;         // export using private user key
  46
  47     var $updatedgradesonly; // only export updated grades
  48     /**
  49      * Constructor should set up all the private variables ready to be pulled
  50      * @param object $course
  51      * @param int $groupid id of selected group, 0 means all
  52      * @param string $itemlist comma separated list of item ids, empty means all
  53      * @param boolean $export_feedback
  54      * @param boolean $export_letters
  55      * @note Exporting as letters will lead to data loss if that exported set it re-imported.
  56      */
  57     function grade_export($course, $groupid=0, $itemlist='', $export_feedback=false, $export_letters=false, $updatedgradesonly = false) {
  58         $this->course = $course;
  59         $this->groupid = $groupid;
  60         $this->grade_items = grade_item::fetch_all(array('courseid'=>$this->course->id));
  61
  62         $this->columns = array();
  63         if (!empty($itemlist)) {
  64             $itemids = explode(',', $itemlist);
  65             // remove items that are not requested
  66             foreach ($itemids as $itemid) {
  67                 if (array_key_exists($itemid, $this->grade_items)) {
  68                     $this->columns[$itemid] =& $this->grade_items[$itemid];
  69                 }
  70             }
  71         } else {
  72             foreach ($this->grade_items as $itemid=>$unused) {
  73                 $this->columns[$itemid] =& $this->grade_items[$itemid];
  74             }
  75         }
  76
  77         $this->export_letters  = $export_letters;
  78         $this->export_feedback = $export_feedback;
  79         $this->userkey         = '';
  80         $this->previewrows     = false;
  81         $this->updatedgradesonly = $updatedgradesonly;
  82     }
  83
  84     /**
  85      * Init object based using data from form
  86      * @param object $formdata
  87      */
  88     function process_form($formdata) {
  89         global $USER;
  90
  91         $this->columns = array();
  92         if (!empty($formdata->itemids)) {
  93             foreach ($formdata->itemids as $itemid=>$selected) {
  94                 if ($selected and array_key_exists($itemid, $this->grade_items)) {
  95                     $this->columns[$itemid] =& $this->grade_items[$itemid];
  96                 }
  97             }
  98         } else {
  99             foreach ($this->grade_items as $itemid=>$unused) {
 100                 $this->columns[$itemid] =& $this->grade_items[$itemid];
 101             }
 102         }
 103
 104         if (isset($formdata->key)) {
 105             if ($formdata->key == 1 && isset($formdata->iprestriction) && isset($formdata->validuntil)) {
 106                 // Create a new key
 107                 $formdata->key = create_user_key('grade/export', $USER->id, $this->course->id, $formdata->iprestriction, $formdata->validuntil);
 108             }
 109             $this->userkey = $formdata->key;
 110         }
 111
 112         if (isset($formdata->export_letters)) {
 113             $this->export_letters = $formdata->export_letters;
 114         }
 115
 116         if (isset($formdata->export_feedback)) {
 117             $this->export_feedback = $formdata->export_feedback;
 118         }
 119
 120         if (isset($formdata->previewrows)) {
 121             $this->previewrows = $formdata->previewrows;
 122         }
 123
 124     }
 125
 126     /**
 127      * Update exported field in grade_grades table
 128      * @return boolean
 129      */
 130     function track_exports() {
 131         global $CFG;
 132
 133         /// Whether this plugin is entitled to update export time
 134         if ($expplugins = explode(",", $CFG->gradeexport)) {
 135             if (in_array($this->plugin, $expplugins)) {
 136                 return true;
 137             } else {
 138                 return false;
 139           }
 140         } else {
 141             return false;
 142         }
 143     }
 144
 145     /**
 146      * Returns string representation of final grade
 147      * @param $object $grade instance of grade_grade class
 148      * @return string
 149      */
 150     function format_grade($grade) {
 151         $displaytype = null;
 152         if ($this->export_letters) {
 153             $displaytype = GRADE_DISPLAY_TYPE_LETTER;
 154         } else {
 155             $displaytype = GRADE_DISPLAY_TYPE_REAL;
 156         }
 157
 158         return grade_format_gradevalue($grade->finalgrade, $this->grade_items[$grade->itemid], false, $displaytype, null);
 159     }
 160
 161     /**
 162      * Returns the name of column in export
 163      * @param object $grade_item
 164      * @param boolena $feedback feedback colum
 165      * &return string
 166      */
 167     function format_column_name($grade_item, $feedback=false) {
 168         if ($grade_item->itemtype == 'mod') {
 169             $name = get_string('modulename', $grade_item->itemmodule).': '.$grade_item->get_name();
 170         } else {
 171             $name = $grade_item->get_name();
 172         }
 173
 174         if ($feedback) {
 175             $name .= ' ('.get_string('feedback').')';
 176         }
 177
 178         return strip_tags($name);
 179     }
 180
 181     /**
 182      * Returns formatted grade feedback
 183      * @param object $feedback object with properties feedback and feedbackformat
 184      * @return string
 185      */
 186     function format_feedback($feedback) {
 187         return strip_tags(format_text($feedback->feedback, $feedback->feedbackformat));
 188     }
 189
 190     /**
 191      * Implemented by child class
 192      */
 193     function print_grades() { }
 194
 195     /**
 196      * Prints preview of exported grades on screen as a feedback mechanism
 197      */
 198     function display_preview() {
 199
 200         print_heading(get_string('previewrows', 'grades'));
 201
 202         echo '<table>';
 203         echo '<tr>';
 204         echo '<th>'.get_string("firstname")."</th>".
 205              '<th>'.get_string("lastname")."</th>".
 206              '<th>'.get_string("idnumber")."</th>".
 207              '<th>'.get_string("institution")."</th>".
 208              '<th>'.get_string("department")."</th>".
 209              '<th>'.get_string("email")."</th>";
 210         foreach ($this->columns as $grade_item) {
 211             echo '<th>'.$this->format_column_name($grade_item).'</th>';
 212
 213             /// add a column_feedback column
 214             if ($this->export_feedback) {
 215                 echo '<th>'.$this->format_column_name($grade_item, true).'</th>';
 216             }
 217         }
 218         echo '</tr>';
 219         /// Print all the lines of data.
 220
 221         $i = 0;
 222         $gui = new graded_users_iterator($this->course, $this->columns, $this->groupid);
 223         $gui->init();
 224         while ($userdata = $gui->next_user()) {
 225             // number of preview rows
 226             if ($this->previewrows and $this->previewrows < ++$i) {
 227                 break;
 228             }
 229             $user = $userdata->user;
 230
 231             echo '<tr>';
 232             echo "<td>$user->firstname</td><td>$user->lastname</td><td>$user->idnumber</td><td>$user->institution</td><td>$user->department</td><td>$user->email</td>";
 233             foreach ($this->columns as $itemid=>$unused) {
 234                 $gradetxt = $this->format_grade($userdata->grades[$itemid]);
 235
 236                 // get the status of this grade, and put it through track to get the status
 237                 $g = new grade_export_update_buffer();
 238                 $grade_grade = new grade_grade(array('itemid'=>$itemid, 'userid'=>$user->id));
 239                 $status = $g->track($grade_grade);
 240 echo "status is $status";
 241                 if ($this->updatedgradesonly && ($status == 'nochange' || $status == 'unknown')) {
 242                     echo '<td>'.get_string('unchangedgrade', 'grade').'</td>';
 243                 } else {
 244                     echo "<td>$gradetxt</td>";
 245                 }
 246
 247                 if ($this->export_feedback) {
 248                     echo '<td>'.$this->format_feedback($userdata->feedbacks[$itemid]).'</td>';
 249                 }
 250             }
 251             echo "</tr>";
 252         }
 253         echo '</table>';
 254         $gui->close();
 255     }
 256
 257     /**
 258      * Returns array of parameters used by dump.php and export.php.
 259      * @return array
 260      */
 261     function get_export_params() {
 262         $itemids = array_keys($this->columns);
 263
 264         $params = array('id'                =>$this->course->id,
 265                         'groupid'           =>$this->groupid,
 266                         'itemids'           =>implode(',', $itemids),
 267                         'export_letters'    =>$this->export_letters,
 268                         'export_feedback'   =>$this->export_feedback,
 269                         'updatedgradesonly' =>$this->updatedgradesonly);
 270
 271         return $params;
 272     }
 273
 274     /**
 275      * Either prints a "Export" box, which will redirect the user to the download page,
 276      * or prints the URL for the published data.
 277      * @return void
 278      */
 279     function print_continue() {
 280         global $CFG;
 281
 282         $params = $this->get_export_params();
 283
 284
 285         print_heading(get_string('export', 'grades'));
 286
 287         echo '<div class="gradeexportlink">';
 288         if (!$this->userkey) {      // this button should trigger a download prompt
 289             print_single_button($CFG->wwwroot.'/grade/export/'.$this->plugin.'/export.php',
 290                                 $params, get_string('download', 'admin'));
 291
 292         } else {
 293             $paramstr = '';
 294             $sep = '?';
 295             foreach($params as $name=>$value) {
 296                 $paramstr .= $sep.$name.'='.$value;
 297                 $sep = '&amp;';
 298             }
 299
 300             $link = $CFG->wwwroot.'/grade/export/'.$this->plugin.'/dump.php'.$paramstr.'&amp;key='.$this->userkey;
 301
 302             echo get_string('download', 'admin').': <a href="'.$link.'">'.$link.'</a>';
 303         }
 304         echo '</div>';
 305     }
 306 }
 307
 308 /**
 309  * This class is used to update the exported field in grade_grades.
 310  * It does internal buffering to speedup the db operations.
 311  */
 312 class grade_export_update_buffer {
 313     var $update_list;
 314     var $export_time;
 315
 316     /**
 317      * Constructor - creates the buffer and initialises the time stamp
 318      */
 319     function grade_export_update_buffer() {
 320         $this->update_list = array();
 321         $this->export_time = time();
 322     }
 323
 324     function flush($buffersize) {
 325         global $CFG;
 326
 327         if (count($this->update_list) > $buffersize) {
 328             $list = implode(',', $this->update_list);
 329             $sql = "UPDATE {$CFG->prefix}grade_grades SET exported = {$this->export_time} WHERE id IN ($list)";
 330             execute_sql($sql, false);
 331             $this->update_list = array();
 332         }
 333     }
 334
 335     /**
 336      * Track grade export status
 337      * @param object $grade_grade
 338      * @return string $status (unknow, new, regrade, nochange)
 339      */
 340     function track($grade_grade) {
 341
 342         if (empty($grade_grade->exported) or empty($grade_grade->timemodified)) {
 343             if (is_null($grade_grade->finalgrade)) {
 344                 // grade does not exist yet
 345                 $status = 'unknown';
 346             } else {
 347                 $status = 'new';
 348                 $this->update_list[] = $grade_grade->id;
 349             }
 350
 351         } else if ($grade_grade->exported < $grade_grade->timemodified) {
 352             $status = 'regrade';
 353             $this->update_list[] = $grade_grade->id;
 354
 355         } else if ($grade_grade->exported >= $grade_grade->timemodified) {
 356             $status = 'nochange';
 357
 358         } else {
 359             // something is wrong?
 360             $status = 'unknown';
 361         }
 362
 363         $this->flush(100);
 364
 365         return $status;
 366     }
 367
 368     /**
 369      * Flush and close the buffer.
 370      */
 371     function close() {
 372         $this->flush(0);
 373     }
 374 }
 375 ?>