grade/export/lib.php

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