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