From b9f49659b6d59a81504c73607a022a6169468987 Mon Sep 17 00:00:00 2001 From: skodak Date: Wed, 9 Jan 2008 18:19:42 +0000 Subject: [PATCH] MDL-12822 removing some unused grade functions (obsoleted by format grade function), renaming PUBLIC API to activity communication API and adding new querylib.php with useful functions (requested by other devs); merged from MOODLE_19_STABLE --- grade/lib.php | 27 +----- grade/querylib.php | 203 +++++++++++++++++++++++++++++++++++++++++++ grade/report/lib.php | 29 ------- lib/gradelib.php | 188 ++++----------------------------------- 4 files changed, 220 insertions(+), 227 deletions(-) create mode 100644 grade/querylib.php diff --git a/grade/lib.php b/grade/lib.php index fa4e1fa84b9..a5a6ace97ac 100644 --- a/grade/lib.php +++ b/grade/lib.php @@ -25,10 +25,9 @@ require_once $CFG->libdir.'/gradelib.php'; - /** * This class iterates over all users that are graded in a course. - * Returns fetailed info about users and their grades. + * Returns detailed info about users and their grades. */ class graded_users_iterator { var $course; @@ -678,30 +677,6 @@ function grade_build_nav($path, $pagename=null, $id=null) { return $navigation; } -/** - * Computes then returns the percentage value of the grade value within the given range. - * @param float $gradeval - * @param float $grademin - * @param float $grademx - * @return float $percentage - */ -function grade_to_percentage($gradeval, $grademin, $grademax) { - if ($grademin >= $grademax) { - debugging("The minimum grade ($grademin) was higher than or equal to the maximum grade ($grademax)!!! Cannot proceed with computation."); - } - - // If given gradevalue is lower than grademin, adjust it to grademin - if ($gradeval < $grademin || empty($gradeval)) { - $gradeval = $grademin; - } - - $offset_value = $gradeval - $grademin; - $offset_max = $grademax - $grademin; - $factor = 100 / $offset_max; - $percentage = $offset_value * $factor; - return $percentage; -} - /** * General structure representing grade items in course */ diff --git a/grade/querylib.php b/grade/querylib.php new file mode 100644 index 00000000000..4b9ca9b300b --- /dev/null +++ b/grade/querylib.php @@ -0,0 +1,203 @@ +needsupdate) { + grade_regrade_final_grades($courseid); + } + + $item = new object(); + $item->itemnumber = $grade_item->itemnumber; + $item->scaleid = $grade_item->scaleid; + $item->name = $grade_item->get_name(); + $item->grademin = $grade_item->grademin; + $item->grademax = $grade_item->grademax; + $item->gradepass = $grade_item->gradepass; + $item->locked = $grade_item->is_locked(); + $item->hidden = $grade_item->is_hidden(); + $item->grades = array(); + + switch ($grade_item->gradetype) { + case GRADE_TYPE_NONE: + continue; + + case GRADE_TYPE_VALUE: + $item->scaleid = 0; + break; + + case GRADE_TYPE_TEXT: + $item->scaleid = 0; + $item->grademin = 0; + $item->grademax = 0; + $item->gradepass = 0; + break; + } + + if (empty($userid_or_ids)) { + $userids = array(); + + } else if (is_array($userid_or_ids)) { + $userids = $userid_or_ids; + + } else { + $userids = array($userid_or_ids); + } + + if ($userids) { + $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true); + foreach ($userids as $userid) { + $grade_grades[$userid]->grade_item =& $grade_item; + + $grade = new object(); + $grade->grade = $grade_grades[$userid]->finalgrade; + $grade->locked = $grade_grades[$userid]->is_locked(); + $grade->hidden = $grade_grades[$userid]->is_hidden(); + $grade->overridden = $grade_grades[$userid]->overridden; + $grade->feedback = $grade_grades[$userid]->feedback; + $grade->feedbackformat = $grade_grades[$userid]->feedbackformat; + $grade->usermodified = $grade_grades[$userid]->usermodified; + $grade->datesubmitted = $grade_grades[$userid]->get_datesubmitted(); + $grade->dategraded = $grade_grades[$userid]->get_dategraded(); + + // create text representation of grade + if ($grade_item->needsupdate) { + $grade->grade = false; + $grade->str_grade = get_string('error'); + + } else if (is_null($grade->grade)) { + $grade->str_grade = '-'; + + } else { + $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item); + } + + // create html representation of feedback + if (is_null($grade->feedback)) { + $grade->str_feedback = ''; + } else { + $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat); + } + + $item->grades[$userid] = $grade; + } + } + + return $item; +} + +/** + * Returns all grade items (including outcomes) or main item for a given activity identified by $cm object. + * + * @param object $cm A course module object (preferably with modname property) + * @return mixed - array of grade item instances (one if $only_main_item true), false if error or not found + */ +function grade_get_grade_items_for_activity($cm, $only_main_item=false) { + global $CFG; + + if (!isset($cm->modname)) { + $cm = get_record_sql("SELECT cm.*, m.name, md.name as modname + FROM {$CFG->prefix}course_modules cm, + {$CFG->prefix}modules md, + WHERE cm.id = {$cm->id} AND md.id = cm.module"); + } + + + if (empty($cm) or empty($cm->instance) or empty($cm->course)) { + debugging("Incorrect cm parameter in grade_get_grade_items_for_activity()!"); + return false; + } + + if ($only_main_item) { + return grade_item::fetch_all(array('itemtype'=>'mod', 'itemmodule'=>$cm->modname, 'iteminstance'=>$cm->instance, 'courseid'=>$cm->course, 'itemnumber'=>0)); + } else { + return grade_item::fetch_all(array('itemtype'=>'mod', 'itemmodule'=>$cm->modname, 'iteminstance'=>$cm->instance, 'courseid'=>$cm->course)); + } +} + +/** + * Returns whether or not user received grades in main grade item for given activity. + * + * @param object $cm + * @param int $userid + * @return bool True if graded false if user not graded yet + */ +function grade_is_user_graded_in_activity($cm, $userid) { + + $grade_items = grade_get_grade_items_for_activity($cm, true); + if (empty($grade_items)) { + return false; + } + + $grade_item = reset($grade_items); + + if ($grade_item->gradetype == GRADE_TYPE_NONE) { + return false; + } + + if ($grade_item->needsupdate) { + // activity items should never fail to regrade + grade_regrade_final_grades($grade_item->courseid); + } + + if (!$grade = $grade_item->get_final($userid)) { + return false; + } + + if (is_null($grade->finalgrade)) { + return false; + } + + return true; +} + +/** + * Returns an array of activities (defined as $cm objects) which are gradeable from gradebook, outcomes are ignored. + * + * @param int $courseid If provided then restrict to one course. + * @param string $modulename If defined (could be 'forum', 'assignment' etc) then only that type are returned. + * @return array $cm objects + */ +function grade_get_gradable_activities($courseid, $modulename='') { + global $CFG; + + if (empty($modulename)) { + if (!$modules = get_records('modules', 'visible', '1')) { + return false; + } + $result = array(); + foreach ($modules as $module) { + if ($cms = grade_get_gradable_activities($courseid, $module->name)) { + $result = $result + $cms; + } + } + if (empty($result)) { + return false; + } else { + return $result; + } + } + + $sql = "SELECT cm.*, m.name, md.name as modname + FROM {$CFG->prefix}grade_items gi, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules md, {$CFG->prefix}$modulename m + WHERE gi.courseid = $courseid AND + gi.itemtype = 'mod' AND + gi.itemmodule = '$modulename' AND + gi.itemnumber = 0 AND + gi.gradetype != ".GRADE_TYPE_NONE." AND + gi.iteminstance = cm.instance AND + cm.instance = m.id AND + md.name = '$modulename' AND + md.id = cm.module"; + + return get_records_sql($sql); +} +?> diff --git a/grade/report/lib.php b/grade/report/lib.php index 672beec5e30..4c9c3ae899d 100755 --- a/grade/report/lib.php +++ b/grade/report/lib.php @@ -209,7 +209,6 @@ class grade_report { * @param mixed $pref_value The value of the preference. * @param int $itemid An optional itemid to which the preference will be assigned * @return bool Success or failure. - * TODO print visual feedback */ function set_pref($pref, $pref_value='default', $itemid=null) { $fullprefname = 'grade_report_' . $pref; @@ -254,34 +253,6 @@ class grade_report { return $this->lang_strings[$strcode]; } - /** - * Computes then returns the percentage value of the grade value within the given range. - * @param float $gradeval - * @param float $grademin - * @param float $grademx - * @return float $percentage - */ - function grade_to_percentage($gradeval, $grademin, $grademax) { - if ($grademin >= $grademax) { - debugging("The minimum grade ($grademin) was higher than or equal to the maximum grade ($grademax)!!! Cannot proceed with computation."); - } - $offset_value = $gradeval - $grademin; - $offset_max = $grademax - $grademin; - $factor = 100 / $offset_max; - $percentage = $offset_value * $factor; - return $percentage; - } - - /** - * Fetches and returns an array of grade letters indexed by their grade boundaries, as stored in course item settings or site preferences. - * @return array - */ - function get_grade_letters() { - global $COURSE; - $context = get_context_instance(CONTEXT_COURSE, $COURSE->id); - return grade_get_letters($context); - } - /** * Fetches and returns a count of all the users that will be shown on this page. * @param boolean $groups include groups limit diff --git a/lib/gradelib.php b/lib/gradelib.php index 80afed6c7b8..d6b550f62f9 100644 --- a/lib/gradelib.php +++ b/lib/gradelib.php @@ -23,7 +23,7 @@ /////////////////////////////////////////////////////////////////////////// /** - * Library of functions for gradebook + * Library of functions for gradebook - both public and internal * * @author Moodle HQ developers * @version $Id$ @@ -39,7 +39,9 @@ require_once($CFG->libdir . '/grade/grade_grade.php'); require_once($CFG->libdir . '/grade/grade_scale.php'); require_once($CFG->libdir . '/grade/grade_outcome.php'); -/***** PUBLIC GRADE API - only these functions should be used in modules *****/ +///////////////////////////////////////////////////////////////////// +///// Start of public API for communication with modules/blocks ///// +///////////////////////////////////////////////////////////////////// /** * Submit new or update grade; update/create grade_item definition. Grade must have userid specified, @@ -50,7 +52,7 @@ require_once($CFG->libdir . '/grade/grade_outcome.php'); * 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted' and 'hidden'. 'reset' means delete all current grades including locked ones. * * Manual, course or category items can not be updated by this function. - + * @public * @param string $source source of the grade such as 'mod/assignment' * @param int $courseid id of course * @param string $itemtype type of grade item - mod, block @@ -237,6 +239,7 @@ function grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, /** * Updates outcomes of user * Manual outcomes can not be updated. + * @public * @param string $source source of the grade such as 'mod/assignment' * @param int $courseid id of course * @param string $itemtype 'mod', 'block' @@ -260,14 +263,15 @@ function grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $item /** * Returns grading information for given activity - optionally with users grades * Manual, course or category items can not be queried. + * @public * @param int $courseid id of course * @param string $itemtype 'mod', 'block' * @param string $itemmodule 'forum, 'quiz', etc. * @param int $iteminstance id of the item module - * @param int $userid optional id of the graded user; if userid not used, returns only information about grade_item + * @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 * @return array of grade information objects (scaleid, name, grade and locked status, etc.) indexed with itemnumbers */ -function grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=0) { +function grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=null) { global $CFG; $return = new object(); @@ -439,164 +443,15 @@ 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) { +/////////////////////////////////////////////////////////////////// +///// End of public API for communication with modules/blocks ///// +/////////////////////////////////////////////////////////////////// - $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) - if ($grade_items = grade_item::fetch_all(array('iteminstance' => $cm->instance, 'courseid' => $cm->courseid))) { - $std_grade_items = array(); - foreach ($grade_items as $key => $gi) { - $std_grade_items[$key] = $gi->get_record_data(); - } - - if (count($std_grade_items) == 0 || empty($std_grade_items)) { - return null; - } elseif (count($std_grade_items) == 1) { - return reset($std_grade_items); - } else { - return $std_grade_items; - } - } else { - return null; - } -} - -/** - * 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. 'course' can be used to get the course item. - * @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)) { - if ($type == 'course' && !empty($courseid)) { - $params['itemtype'] = 'course'; - } else { - $params['itemtype'] = 'mod'; - $params['itemmodule'] = $type; - } - } - - $grade_items = $grade_items = grade_item::fetch_all($params); - $std_grade_items = array(); - foreach ($grade_items as $key => $gi) { - $std_grade_items[$key] = $gi->get_record_data(); - } - return $std_grade_items; -} - -/** - * 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, $userid) { - if (!method_exists($gradeitem, 'get_final')) { - $fetch_from_db = empty($gradeitem->id); - $gradeitem = new grade_item($gradeitem, $fetch_from_db); - } - - 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($userid, $courseid = null) { - $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 *****/ +/////////////////////////////////////////////////////////////////// +///// Internal API: used by gradebook plugins and Moodle core ///// +/////////////////////////////////////////////////////////////////// /** * Returns course gradebook setting @@ -683,7 +538,7 @@ function grade_set_setting($courseid, $name, $value) { * @param float $value grade value * @param object $grade_item - by reference to prevent scale reloading * @param bool $localized use localised decimal separator - * @param int $displaytype type of display - raw, letter, percentage + * @param int $displaytype type of display - GRADE_DISPLAY_TYPE_REAL, GRADE_DISPLAY_TYPE_PERCENTAGE, GRADE_DISPLAY_TYPE_LETTER * @param int $decimalplaces number of decimal places when displaying float values * @return string */ @@ -1235,17 +1090,6 @@ function remove_course_grades($courseid, $showfeedback) { } } -/** - * Builds an array of percentages indexed by integers for the purpose of building a select drop-down element. - * @param int $steps The value between each level. - * @param string $order 'asc' for 0-100 and 'desc' for 100-0 - * @param int $lowest The lowest value to include - * @param int $highest The highest value to include - */ -function build_percentages_array($steps=1, $order='desc', $lowest=0, $highest=100) { - // TODO reject or implement -} - /** * Grading cron job */