[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');

            } 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 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');

        } 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);
        }

        $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) {
	71	$grade->grade = false;
	72	$grade->str_grade = get_string('error');
	73
	74	} else if (is_null($grade->grade)) {
	75	$grade->str_grade = '-';
	76
	77	} else {
	78	$grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
	79	}
	80
	81	// create html representation of feedback
	82	if (is_null($grade->feedback)) {
	83	$grade->str_feedback = '';
	84	} else {
	85	$grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
	86	}
	87
	88	$item->grades[$userid] = $grade;
	89	}
	90	}
	91
	92	return $item;
	93	}
	94
028553e7	95	/**
	96	* Returns the aggregated or calculated course grade for the given user(s).
	97	* @public
	98	* @param int $userid
	99	* @param int $courseid optional id of course or array of ids, empty means all uses courses (returns array if not present)
	100	* @return mixed grade info or grades array including item info, false if error
	101	*/
	102	function grade_get_course_grade($userid, $courseid_or_ids=null) {
	103
	104	if (!is_array($courseid_or_ids)) {
	105	if (empty($courseid_or_ids)) {
	106	if (!$courses = get_my_courses($userid, $sort='visible DESC,sortorder ASC', 'id')) {
	107	return false;
	108	}
	109	$courseids = array_keys($courses);
	110	return grade_get_course_grade($userid, $courseids);
	111	}
	112	if (!is_numeric($courseid_or_ids)) {
	113	return false;
	114	}
	115	if (!$grades = grade_get_course_grade($userid, array($courseid_or_ids))) {
	116	return false;
	117	} else {
	118	// only one grade - not array
	119	$grade = reset($grades);
	120	return $grade;
	121	}
	122	}
	123
	124	foreach ($courseid_or_ids as $courseid) {
	125	$grade_item = grade_item::fetch_course_item($courseid);
	126	$course_items[$grade_item->courseid] = $grade_item;
	127	}
	128
	129	$grades = array();
	130	foreach ($course_items as $grade_item) {
	131	if ($grade_item->needsupdate) {
	132	grade_regrade_final_grades($courseid);
	133	}
	134
	135	$item = new object();
	136	$item->scaleid = $grade_item->scaleid;
	137	$item->name = $grade_item->get_name();
	138	$item->grademin = $grade_item->grademin;
	139	$item->grademax = $grade_item->grademax;
	140	$item->gradepass = $grade_item->gradepass;
	141	$item->locked = $grade_item->is_locked();
	142	$item->hidden = $grade_item->is_hidden();
	143
	144	switch ($grade_item->gradetype) {
	145	case GRADE_TYPE_NONE:
	146	continue;
	147
	148	case GRADE_TYPE_VALUE:
	149	$item->scaleid = 0;
	150	break;
	151
	152	case GRADE_TYPE_TEXT:
	153	$item->scaleid = 0;
	154	$item->grademin = 0;
	155	$item->grademax = 0;
	156	$item->gradepass = 0;
	157	break;
	158	}
159	$grade_grade = new grade_grade(array('userid'=>$userid, 'itemid'=>$grade_item->id));
160	$grade_grade->grade_item =& $grade_item;
161
162	$grade = new object();
163	$grade->grade = $grade_grade->finalgrade;
164	$grade->locked = $grade_grade->is_locked();
165	$grade->hidden = $grade_grade->is_hidden();
166	$grade->overridden = $grade_grade->overridden;
167	$grade->feedback = $grade_grade->feedback;
168	$grade->feedbackformat = $grade_grade->feedbackformat;
169	$grade->usermodified = $grade_grade->usermodified;
170	$grade->dategraded = $grade_grade->get_dategraded();
171	$grade->item = $item;
172
173	// create text representation of grade
174	if ($grade_item->needsupdate) {
175	$grade->grade = false;
176	$grade->str_grade = get_string('error');
177
178	} else if (is_null($grade->grade)) {
179	$grade->str_grade = '-';
180
181	} else {
182	$grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
183	}
184
185	// create html representation of feedback
186	if (is_null($grade->feedback)) {
187	$grade->str_feedback = '';
188	} else {
189	$grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
190	}
191
192	$grades[$grade_item->courseid] = $grade;
193	}
194
195	return $grades;
196	}
197
b9f49659	198	/**
	199	* Returns all grade items (including outcomes) or main item for a given activity identified by $cm object.
	200	*
	201	* @param object $cm A course module object (preferably with modname property)
	202	* @return mixed - array of grade item instances (one if $only_main_item true), false if error or not found
	203	*/
	204	function grade_get_grade_items_for_activity($cm, $only_main_item=false) {
	205	global $CFG;
	206
	207	if (!isset($cm->modname)) {
	208	$cm = get_record_sql("SELECT cm.*, m.name, md.name as modname
	209	FROM {$CFG->prefix}course_modules cm,
	210	{$CFG->prefix}modules md,
	211	WHERE cm.id = {$cm->id} AND md.id = cm.module");
	212	}
	213
	214
	215	if (empty($cm) or empty($cm->instance) or empty($cm->course)) {
	216	debugging("Incorrect cm parameter in grade_get_grade_items_for_activity()!");
	217	return false;
	218	}
	219
	220	if ($only_main_item) {
	221	return grade_item::fetch_all(array('itemtype'=>'mod', 'itemmodule'=>$cm->modname, 'iteminstance'=>$cm->instance, 'courseid'=>$cm->course, 'itemnumber'=>0));
	222	} else {
	223	return grade_item::fetch_all(array('itemtype'=>'mod', 'itemmodule'=>$cm->modname, 'iteminstance'=>$cm->instance, 'courseid'=>$cm->course));
	224	}
	225	}
	226
	227	/**
	228	* Returns whether or not user received grades in main grade item for given activity.
	229	*
	230	* @param object $cm
	231	* @param int $userid
	232	* @return bool True if graded false if user not graded yet
	233	*/
	234	function grade_is_user_graded_in_activity($cm, $userid) {
	235
	236	$grade_items = grade_get_grade_items_for_activity($cm, true);
	237	if (empty($grade_items)) {
	238	return false;
	239	}
	240
	241	$grade_item = reset($grade_items);
	242
	243	if ($grade_item->gradetype == GRADE_TYPE_NONE) {
	244	return false;
	245	}
	246
	247	if ($grade_item->needsupdate) {
	248	// activity items should never fail to regrade
	249	grade_regrade_final_grades($grade_item->courseid);
	250	}
	251
	252	if (!$grade = $grade_item->get_final($userid)) {
	253	return false;
	254	}
	255
	256	if (is_null($grade->finalgrade)) {
	257	return false;
	258	}
	259
	260	return true;
	261	}
262
263	/**
264	* Returns an array of activities (defined as $cm objects) which are gradeable from gradebook, outcomes are ignored.
265	*
266	* @param int $courseid If provided then restrict to one course.
267	* @param string $modulename If defined (could be 'forum', 'assignment' etc) then only that type are returned.
268	* @return array $cm objects
269	*/
270	function grade_get_gradable_activities($courseid, $modulename='') {
271	global $CFG;
272
273	if (empty($modulename)) {
274	if (!$modules = get_records('modules', 'visible', '1')) {
275	return false;
276	}
277	$result = array();
278	foreach ($modules as $module) {
279	if ($cms = grade_get_gradable_activities($courseid, $module->name)) {
280	$result = $result + $cms;
281	}
282	}
283	if (empty($result)) {
284	return false;
285	} else {
286	return $result;
287	}
288	}
289
290	$sql = "SELECT cm.*, m.name, md.name as modname
291	FROM {$CFG->prefix}grade_items gi, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules md, {$CFG->prefix}$modulename m
292	WHERE gi.courseid = $courseid AND
293	gi.itemtype = 'mod' AND
294	gi.itemmodule = '$modulename' AND
295	gi.itemnumber = 0 AND
296	gi.gradetype != ".GRADE_TYPE_NONE." AND
297	gi.iteminstance = cm.instance AND
298	cm.instance = m.id AND
299	md.name = '$modulename' AND
300	md.id = cm.module";
301
302	return get_records_sql($sql);
303	}
028553e7	304	?>