grade/export/lib.php

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