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