[moodle.git] / grade / querylib.php

<?php  //$Id$

/**
 * Returns the aggregated or calculated course grade(s) in given course.
 * @public
 * @param int $courseid id of course
 * @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 information about course grade item scaleid, name, grade and locked status, etc. + user grades
 */
function grade_get_course_grades($courseid, $userid_or_ids=null) {

    $grade_item = grade_item::fetch_course_item($courseid);

    if ($grade_item->needsupdate) {
        grade_regrade_final_grades($courseid);
    }

    $item = new object();
    $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->dategraded     = $grade_grades[$userid]->get_dategraded();

            // create text representation of grade
            if ($grade_item->needsupdate) {
                $grade->grade          = false;
                $grade->str_grade      = get_string('error');
                $grade->str_long_grade = $grade->str_grade;

            } else if (is_null($grade->grade)) {
                $grade->str_grade      = '-';
                $grade->str_long_grade = $grade->str_grade;

            } else {
                $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
                if ($grade_item->gradetype == GRADE_TYPE_SCALE or $grade_item->get_displaytype() != GRADE_DISPLAY_TYPE_REAL) {
                    $grade->str_long_grade = $grade->str_grade;
                } else {
                    $a = new object();
                    $a->grade = $grade->str_grade;
                    $a->max   = grade_format_gradevalue($grade_item->grademax, $grade_item);
                    $grade->str_long_grade = get_string('gradelong', 'grades', $a);
                }
            }

            // 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 the aggregated or calculated course grade for the given user(s).
 * @public
 * @param int $userid
 * @param int $courseid optional id of course or array of ids, empty means all uses courses (returns array if not present)
 * @return mixed grade info or grades array including item info, false if error
 */
function grade_get_course_grade($userid, $courseid_or_ids=null) {

    if (!is_array($courseid_or_ids)) {
        if (empty($courseid_or_ids)) {
            if (!$courses = get_my_courses($userid, $sort='visible DESC,sortorder ASC', 'id')) {
                return false;
            }
            $courseids = array_keys($courses);
            return grade_get_course_grade($userid, $courseids);
        }
        if (!is_numeric($courseid_or_ids)) {
            return false;
        }
        if (!$grades = grade_get_course_grade($userid, array($courseid_or_ids))) {
            return false;
        } else {
            // only one grade - not array
            $grade = reset($grades);
            return $grade;
        }
    }

    foreach ($courseid_or_ids as $courseid) {
        $grade_item = grade_item::fetch_course_item($courseid);
        $course_items[$grade_item->courseid] = $grade_item;
    }

    $grades = array();
    foreach ($course_items as $grade_item) {
        if ($grade_item->needsupdate) {
            grade_regrade_final_grades($courseid);
        }

        $item = new object();
        $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();

        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;
        }
        $grade_grade = new grade_grade(array('userid'=>$userid, 'itemid'=>$grade_item->id));
        $grade_grade->grade_item =& $grade_item;

        $grade = new object();
        $grade->grade          = $grade_grade->finalgrade;
        $grade->locked         = $grade_grade->is_locked();
        $grade->hidden         = $grade_grade->is_hidden();
        $grade->overridden     = $grade_grade->overridden;
        $grade->feedback       = $grade_grade->feedback;
        $grade->feedbackformat = $grade_grade->feedbackformat;
        $grade->usermodified   = $grade_grade->usermodified;
        $grade->dategraded     = $grade_grade->get_dategraded();
        $grade->item           = $item;

        // create text representation of grade
        if ($grade_item->needsupdate) {
            $grade->grade          = false;
            $grade->str_grade      = get_string('error');
            $grade->str_long_grade = $grade->str_grade;

        } else if (is_null($grade->grade)) {
            $grade->str_grade      = '-';
            $grade->str_long_grade = $grade->str_grade;

        } else {
            $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
            if ($grade_item->gradetype == GRADE_TYPE_SCALE or $grade_item->get_displaytype() != GRADE_DISPLAY_TYPE_REAL) {
                $grade->str_long_grade = $grade->str_grade;
            } else {
                $a = new object();
                $a->grade = $grade->str_grade;
                $a->max   = grade_format_gradevalue($grade_item->grademax, $grade_item);
                $grade->str_long_grade = get_string('gradelong', 'grades', $a);
            }
        }

        // create html representation of feedback
        if (is_null($grade->feedback)) {
            $grade->str_feedback = '';
        } else {
            $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
        }

        $grades[$grade_item->courseid] = $grade;
    }

    return $grades;
}

/**
 * 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);
}
?>
Commit	Line	Data
b9f49659	1	<?php //$Id$
	2
	3	/**
028553e7	4	* Returns the aggregated or calculated course grade(s) in given course.
b9f49659	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();
b9f49659	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;
b9f49659	67	$grade->dategraded = $grade_grades[$userid]->get_dategraded();
	68
	69	// create text representation of grade
	70	if ($grade_item->needsupdate) {
85a0a69f	71	$grade->grade = false;
	72	$grade->str_grade = get_string('error');
	73	$grade->str_long_grade = $grade->str_grade;
b9f49659	74
b9f49659	75	} else if (is_null($grade->grade)) {
85a0a69f	76	$grade->str_grade = '-';
85a0a69f	77	$grade->str_long_grade = $grade->str_grade;
b9f49659	78
	79	} else {
	80	$grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
85a0a69f	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	}
b9f49659	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
028553e7	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) {
85a0a69f	185	$grade->grade = false;
	186	$grade->str_grade = get_string('error');
	187	$grade->str_long_grade = $grade->str_grade;
028553e7	188
028553e7	189	} else if (is_null($grade->grade)) {
85a0a69f	190	$grade->str_grade = '-';
85a0a69f	191	$grade->str_long_grade = $grade->str_grade;
028553e7	192
	193	} else {
	194	$grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
85a0a69f	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	}
028553e7	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
b9f49659	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	}
028553e7	324	?>