grade/querylib.php

   1 <?php  //$Id$
   2
   3 /**
   4  * Returns the aggregated or calculated course grade(s) in given course.
   5  * @public
   6  * @param int $courseid id of course
   7  * @param int $userid_or_ids optional id of the graded user or array of ids; if userid not used, returns only information about grade_item
   8  * @return information about course grade item scaleid, name, grade and locked status, etc. + user grades
   9  */
  10 function grade_get_course_grades($courseid, $userid_or_ids=null) {
  11
  12     $grade_item = grade_item::fetch_course_item($courseid);
  13
  14     if ($grade_item->needsupdate) {
  15         grade_regrade_final_grades($courseid);
  16     }
  17
  18     $item = new object();
  19     $item->scaleid    = $grade_item->scaleid;
  20     $item->name       = $grade_item->get_name();
  21     $item->grademin   = $grade_item->grademin;
  22     $item->grademax   = $grade_item->grademax;
  23     $item->gradepass  = $grade_item->gradepass;
  24     $item->locked     = $grade_item->is_locked();
  25     $item->hidden     = $grade_item->is_hidden();
  26     $item->grades     = array();
  27
  28     switch ($grade_item->gradetype) {
  29         case GRADE_TYPE_NONE:
  30             continue;
  31
  32         case GRADE_TYPE_VALUE:
  33             $item->scaleid = 0;
  34             break;
  35
  36         case GRADE_TYPE_TEXT:
  37             $item->scaleid   = 0;
  38             $item->grademin   = 0;
  39             $item->grademax   = 0;
  40             $item->gradepass  = 0;
  41             break;
  42     }
  43
  44     if (empty($userid_or_ids)) {
  45         $userids = array();
  46
  47     } else if (is_array($userid_or_ids)) {
  48         $userids = $userid_or_ids;
  49
  50     } else {
  51         $userids = array($userid_or_ids);
  52     }
  53
  54     if ($userids) {
  55         $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);
  56         foreach ($userids as $userid) {
  57             $grade_grades[$userid]->grade_item =& $grade_item;
  58
  59             $grade = new object();
  60             $grade->grade          = $grade_grades[$userid]->finalgrade;
  61             $grade->locked         = $grade_grades[$userid]->is_locked();
  62             $grade->hidden         = $grade_grades[$userid]->is_hidden();
  63             $grade->overridden     = $grade_grades[$userid]->overridden;
  64             $grade->feedback       = $grade_grades[$userid]->feedback;
  65             $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;
  66             $grade->usermodified   = $grade_grades[$userid]->usermodified;
  67             $grade->dategraded     = $grade_grades[$userid]->get_dategraded();
  68
  69             // create text representation of grade
  70             if ($grade_item->needsupdate) {
  71                 $grade->grade          = false;
  72                 $grade->str_grade      = get_string('error');
  73                 $grade->str_long_grade = $grade->str_grade;
  74
  75             } else if (is_null($grade->grade)) {
  76                 $grade->str_grade      = '-';
  77                 $grade->str_long_grade = $grade->str_grade;
  78
  79             } else {
  80                 $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
  81                 if ($grade_item->gradetype == GRADE_TYPE_SCALE or $grade_item->get_displaytype() != GRADE_DISPLAY_TYPE_REAL) {
  82                     $grade->str_long_grade = $grade->str_grade;
  83                 } else {
  84                     $a = new object();
  85                     $a->grade = $grade->str_grade;
  86                     $a->max   = grade_format_gradevalue($grade_item->grademax, $grade_item);
  87                     $grade->str_long_grade = get_string('gradelong', 'grades', $a);
  88                 }
  89             }
  90
  91             // create html representation of feedback
  92             if (is_null($grade->feedback)) {
  93                 $grade->str_feedback = '';
  94             } else {
  95                 $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
  96             }
  97
  98             $item->grades[$userid] = $grade;
  99         }
 100     }
 101
 102     return $item;
 103 }
 104
 105 /**
 106  * Returns the aggregated or calculated course grade for the given user(s).
 107  * @public
 108  * @param int $userid
 109  * @param int $courseid optional id of course or array of ids, empty means all uses courses (returns array if not present)
 110  * @return mixed grade info or grades array including item info, false if error
 111  */
 112 function grade_get_course_grade($userid, $courseid_or_ids=null) {
 113
 114     if (!is_array($courseid_or_ids)) {
 115         if (empty($courseid_or_ids)) {
 116             if (!$courses = get_my_courses($userid, $sort='visible DESC,sortorder ASC', 'id')) {
 117                 return false;
 118             }
 119             $courseids = array_keys($courses);
 120             return grade_get_course_grade($userid, $courseids);
 121         }
 122         if (!is_numeric($courseid_or_ids)) {
 123             return false;
 124         }
 125         if (!$grades = grade_get_course_grade($userid, array($courseid_or_ids))) {
 126             return false;
 127         } else {
 128             // only one grade - not array
 129             $grade = reset($grades);
 130             return $grade;
 131         }
 132     }
 133
 134     foreach ($courseid_or_ids as $courseid) {
 135         $grade_item = grade_item::fetch_course_item($courseid);
 136         $course_items[$grade_item->courseid] = $grade_item;
 137     }
 138
 139     $grades = array();
 140     foreach ($course_items as $grade_item) {
 141         if ($grade_item->needsupdate) {
 142             grade_regrade_final_grades($courseid);
 143         }
 144
 145         $item = new object();
 146         $item->scaleid    = $grade_item->scaleid;
 147         $item->name       = $grade_item->get_name();
 148         $item->grademin   = $grade_item->grademin;
 149         $item->grademax   = $grade_item->grademax;
 150         $item->gradepass  = $grade_item->gradepass;
 151         $item->locked     = $grade_item->is_locked();
 152         $item->hidden     = $grade_item->is_hidden();
 153
 154         switch ($grade_item->gradetype) {
 155             case GRADE_TYPE_NONE:
 156                 continue;
 157
 158             case GRADE_TYPE_VALUE:
 159                 $item->scaleid = 0;
 160                 break;
 161
 162             case GRADE_TYPE_TEXT:
 163                 $item->scaleid   = 0;
 164                 $item->grademin   = 0;
 165                 $item->grademax   = 0;
 166                 $item->gradepass  = 0;
 167                 break;
 168         }
 169         $grade_grade = new grade_grade(array('userid'=>$userid, 'itemid'=>$grade_item->id));
 170         $grade_grade->grade_item =& $grade_item;
 171
 172         $grade = new object();
 173         $grade->grade          = $grade_grade->finalgrade;
 174         $grade->locked         = $grade_grade->is_locked();
 175         $grade->hidden         = $grade_grade->is_hidden();
 176         $grade->overridden     = $grade_grade->overridden;
 177         $grade->feedback       = $grade_grade->feedback;
 178         $grade->feedbackformat = $grade_grade->feedbackformat;
 179         $grade->usermodified   = $grade_grade->usermodified;
 180         $grade->dategraded     = $grade_grade->get_dategraded();
 181         $grade->item           = $item;
 182
 183         // create text representation of grade
 184         if ($grade_item->needsupdate) {
 185             $grade->grade          = false;
 186             $grade->str_grade      = get_string('error');
 187             $grade->str_long_grade = $grade->str_grade;
 188
 189         } else if (is_null($grade->grade)) {
 190             $grade->str_grade      = '-';
 191             $grade->str_long_grade = $grade->str_grade;
 192
 193         } else {
 194             $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
 195             if ($grade_item->gradetype == GRADE_TYPE_SCALE or $grade_item->get_displaytype() != GRADE_DISPLAY_TYPE_REAL) {
 196                 $grade->str_long_grade = $grade->str_grade;
 197             } else {
 198                 $a = new object();
 199                 $a->grade = $grade->str_grade;
 200                 $a->max   = grade_format_gradevalue($grade_item->grademax, $grade_item);
 201                 $grade->str_long_grade = get_string('gradelong', 'grades', $a);
 202             }
 203         }
 204
 205         // create html representation of feedback
 206         if (is_null($grade->feedback)) {
 207             $grade->str_feedback = '';
 208         } else {
 209             $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
 210         }
 211
 212         $grades[$grade_item->courseid] = $grade;
 213     }
 214
 215     return $grades;
 216 }
 217
 218 /**
 219  * Returns all grade items (including outcomes) or main item for a given activity identified by $cm object.
 220  *
 221  * @param object $cm A course module object (preferably with modname property)
 222  * @return mixed - array of grade item instances (one if $only_main_item true), false if error or not found
 223  */
 224 function grade_get_grade_items_for_activity($cm, $only_main_item=false) {
 225     global $CFG;
 226
 227     if (!isset($cm->modname)) {
 228         $cm = get_record_sql("SELECT cm.*, m.name, md.name as modname
 229                                 FROM {$CFG->prefix}course_modules cm,
 230                                      {$CFG->prefix}modules md,
 231                                WHERE cm.id = {$cm->id} AND md.id = cm.module");
 232     }
 233
 234
 235     if (empty($cm) or empty($cm->instance) or empty($cm->course)) {
 236         debugging("Incorrect cm parameter in grade_get_grade_items_for_activity()!");
 237         return false;
 238     }
 239
 240     if ($only_main_item) {
 241         return grade_item::fetch_all(array('itemtype'=>'mod', 'itemmodule'=>$cm->modname, 'iteminstance'=>$cm->instance, 'courseid'=>$cm->course, 'itemnumber'=>0));
 242     } else {
 243         return grade_item::fetch_all(array('itemtype'=>'mod', 'itemmodule'=>$cm->modname, 'iteminstance'=>$cm->instance, 'courseid'=>$cm->course));
 244     }
 245 }
 246
 247 /**
 248  * Returns whether or not user received grades in main grade item for given activity.
 249  *
 250  * @param object $cm
 251  * @param int $userid
 252  * @return bool True if graded false if user not graded yet
 253  */
 254 function grade_is_user_graded_in_activity($cm, $userid) {
 255
 256     $grade_items = grade_get_grade_items_for_activity($cm, true);
 257     if (empty($grade_items)) {
 258         return false;
 259     }
 260
 261     $grade_item = reset($grade_items);
 262
 263     if ($grade_item->gradetype == GRADE_TYPE_NONE) {
 264         return false;
 265     }
 266
 267     if ($grade_item->needsupdate) {
 268         // activity items should never fail to regrade
 269         grade_regrade_final_grades($grade_item->courseid);
 270     }
 271
 272     if (!$grade = $grade_item->get_final($userid)) {
 273         return false;
 274     }
 275
 276     if (is_null($grade->finalgrade)) {
 277         return false;
 278     }
 279
 280     return true;
 281 }
 282
 283 /**
 284  * Returns an array of activities (defined as $cm objects) which are gradeable from gradebook, outcomes are ignored.
 285  *
 286  * @param int $courseid If provided then restrict to one course.
 287  * @param string $modulename If defined (could be 'forum', 'assignment' etc) then only that type are returned.
 288  * @return array $cm objects
 289  */
 290 function grade_get_gradable_activities($courseid, $modulename='') {
 291     global $CFG;
 292
 293     if (empty($modulename)) {
 294         if (!$modules = get_records('modules', 'visible', '1')) {
 295             return false;
 296         }
 297         $result = array();
 298         foreach ($modules as $module) {
 299             if ($cms = grade_get_gradable_activities($courseid, $module->name)) {
 300                 $result =  $result + $cms;
 301             }
 302         }
 303         if (empty($result)) {
 304             return false;
 305         } else {
 306             return $result;
 307         }
 308     }
 309
 310     $sql = "SELECT cm.*, m.name, md.name as modname
 311               FROM {$CFG->prefix}grade_items gi, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules md, {$CFG->prefix}$modulename m
 312              WHERE gi.courseid = $courseid AND
 313                    gi.itemtype = 'mod' AND
 314                    gi.itemmodule = '$modulename' AND
 315                    gi.itemnumber = 0 AND
 316                    gi.gradetype != ".GRADE_TYPE_NONE." AND
 317                    gi.iteminstance = cm.instance AND
 318                    cm.instance = m.id AND
 319                    md.name = '$modulename' AND
 320                    md.id = cm.module";
 321
 322     return get_records_sql($sql);
 323 }
 324 ?>