MDL-9506 Implemented and tested the new API functions

diff --git a/lib/gradelib.php b/lib/gradelib.php
index 17da4ffa41c71d3cba0344985cfbf60fc817cc3c..819ba82b344a5c2853e0a70690a84e735ff31db2 100644 (file)
--- a/lib/gradelib.php
+++ b/lib/gradelib.php
@@ -434,6 +434,161 @@ function grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $use
     return $return;
 }
 
+/**
+ * Returns whether or not there are any grades yet for the given course module object. A userid can be given to check for a single user's grades.
+ *
+ * @param object $cm
+ * @param int $userid
+ * @return bool True if grades are present, false otherwise
+ */
+function grade_exists($cm, $userid = null) {
+
+    $grade_items = grade_get_grade_items_for_activity($cm);
+    $grades_exist = false;
+
+    // Query each grade_item for existing grades
+    foreach ($grade_items as $gi) {
+        $grades = $gi->get_final($userid);
+        $grades_exist = $grades_exist || !empty($grades); // get_final should return false, an empty array or an array of grade_grade objects
+    }
+
+    return $grades_exist; 
+}
+
+/**
+ * For a given activity module $cm object, return the related grade item object (or array of objects if there are more than one, or NULL if there are none).
+ *
+ * @param object $cm A course module object
+ * @return mixed the related grade item object (or array of objects if there are more than one, or NULL if there are none)
+ */
+function grade_get_grade_items_for_activity($cm) {
+    if (!isset($cm->instance) || !isset($cm->courseid)) {
+        error("The coursemodule object you gave to grade_exists() isn't set up correctly. Either instance ($cm->instance) or courseid ($cm->courseid) field isn't set.");
+    }
+    
+    // Get grade_item object for this course module (or array of grade_items)
+    $grade_items = grade_item::fetch_all(array('iteminstance' => $cm->instance, 'courseid' => $cm->courseid));
+    if (count($grade_items) == 0 || empty($grade_items)) {
+        return null; 
+    } elseif (count($grade_items) == 1) {
+        return reset($grade_items);
+    } else {
+        return $grade_items;
+    } 
+}
+
+/**
+ * Returns an array of activities (defined as $cm objects) for which grade_items are defined. 
+ *  
+ * @param int $courseid If provided then restrict to one course.
+ * @param string $type If defined (could be 'forum', 'assignment' etc) then only that type are returned.
+ * @return array $cm objects
+ */
+function grade_get_grade_activities($courseid = null, $type = null) {
+    if ($grade_items = grade_get_grade_items($courseid, $type)) {
+        $cms = array();
+
+        foreach ($grade_items as $gi) {
+            // Get moduleid
+            $moduleid = get_field('modules', 'id', 'name', $gi->itemmodule);
+            if ($cm = get_record('course_modules', 'instance', $gi->iteminstance, 'course', $gi->courseid, 'module', $moduleid)) {
+                $cms[$cm->id] = $cm;
+            }
+        }
+        return $cms;
+    } else {
+        return false;
+    }
+}
+
+/**
+ * Returns an array of $gradeitem objects.
+ *
+ * @param int $courseid If provided then restrict to one course.
+ * @param string $type If defined (could be 'forum', 'assignment' etc) then only that type are returned.
+ * @return array $gradeitem objects
+ */
+function grade_get_grade_items($courseid = null, $type = null) {
+    // Get list of grade_items for the given course, of the given type
+    $params = array();
+    if (!empty($courseid)) {
+        $params['courseid'] = $courseid;
+    }
+    if (!empty($type)) {
+        $params['itemtype'] = 'mod';
+        $params['itemmodule'] = $type;
+    }
+
+    return $grade_items = grade_item::fetch_all($params); 
+} 
+
+/**
+ * Returns the float grade for the given user in the given grade_item / column. NULL if it doesn't exist. 
+ *
+ * @param object $gradeitem A grade_item object (properly instantiated, or plain stdClass)
+ * @param object $user A user object or a userid (int)
+ * @return float 
+ */
+function grade_get_user_grade($gradeitem, $user) {
+    if (!method_exists($gradeitem, 'get_final')) {
+        $fetch_from_db = empty($gradeitem->id); 
+        $gradeitem = new grade_item($gradeitem, $fetch_from_db);
+    }
+    
+    $userid = $user;
+    if (isset($user->id)) {
+        $userid = $user->id;
+    }
+    
+    if ($final = $gradeitem->get_final($userid)) {
+        return $final->finalgrade;
+    } else {
+        return null;
+    }
+} 
+
+/**
+ * Returns the course grade(s) for the given user. 
+ * If $course is not specified, then return an array of all the course grades for all the courses that user is a part of.
+ *
+ * @param object $user A user object or a userid (int)
+ * @param object $course A course object or a courseid (int)
+ * @return mixed Course grade or array of course grades if $course param is not given
+ */
+function grade_get_course_grade($user, $course = null) {
+    $userid = $user;
+    if (isset($user->id)) {
+        $userid = $user->id;
+    }
+
+    $courseid = $course;
+    if (isset($course->id)) {
+        $courseid = $course->id;
+    }
+    
+    $coursegrades = array();
+
+    // Get the course item(s)
+    if (!empty($courseid)) {
+        $courseitem  = grade_item::fetch_course_item($courseid);
+        if ($final = $courseitem->get_final($userid)) { 
+            return $final->finalgrade;
+        } else {
+            return null;
+        }
+    } else {
+        $courses = get_my_courses($userid);
+        foreach ($courses as $course_object) {
+            $courseitem = grade_item::fetch_course_item($course_object->id);
+            if ($final = $courseitem->get_final($userid)) {
+                $coursegrades[$course_object->id] = $final->finalgrade;
+            }
+        }
+        return $coursegrades;
+    }
+} 
+
+
 /***** END OF PUBLIC API *****/