/**
* Check grade lock status. Uses both grade item lock and grade lock.
* Internally any date in locked field (including future ones) means locked,
* the date is stored for logging purposes only.
*
* @return bool True if locked, false if not
*/
public function is_locked() {
$this->load_grade_item();
if (empty($this->grade_item)) {
return !empty($this->locked);
} else {
return !empty($this->locked) or $this->grade_item->is_locked();
}
}
/**
* Returns the locked state/date of the grade categories' associated grade_item.
*
* This method is also available in grade_item, for cases where the object type is not known.
*
* @return bool
*/
public function is_locked()
{
$this->load_grade_item();
return $this->grade_item->is_locked();
}
break;
default:
// existing grade items
if (!empty($map[$key])) {
// case of an id, only maps id of a grade_item
// this was idnumber
if (!($gradeitem = new grade_item(array('id' => $map[$key], 'courseid' => $course->id)))) {
// supplied bad mapping, should not be possible since user
// had to pick mapping
$status = false;
import_cleanup($importcode);
echo $OUTPUT->notification(get_string('importfailed', 'grades'));
break 3;
}
// check if grade item is locked if so, abort
if ($gradeitem->is_locked()) {
$status = false;
import_cleanup($importcode);
echo $OUTPUT->notification(get_string('gradeitemlocked', 'grades'));
break 3;
}
$newgrade = new stdClass();
$newgrade->itemid = $gradeitem->id;
if ($gradeitem->gradetype == GRADE_TYPE_SCALE and $verbosescales) {
if ($value === '' or $value == '-') {
$value = null;
// no grade
} else {
$scale = $gradeitem->load_scale();
$scales = explode(',', $scale->scale);
$scales = array_map('trim', $scales);
/**
* Submit new or update grade; update/create grade_item definition. Grade must have userid specified,
* rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded', missing property
* or key means do not change existing.
*
* Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax',
* 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted' and 'hidden'.
*
* Manual, course or category items can not be updated by this function.
* @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
* @param string $itemmodule more specific then $itemtype - assignment, forum, etc.; maybe NULL for some item types
* @param int $iteminstance instance it of graded subject
* @param int $itemnumber most probably 0, modules can use other numbers when having more than one grades for each user
* @param mixed $grades grade (object, array) or several grades (arrays of arrays or objects), NULL if updating grade_item definition only
* @param mixed $itemdetails object or array describing the grading item, NULL if no change
*/
function grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades = NULL, $itemdetails = NULL)
{
global $USER;
// only following grade_item properties can be changed in this function
$allowed = array('itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted', 'hidden');
// grade item identification
$params = compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber');
if (is_null($courseid) or is_null($itemtype)) {
debugging('Missing courseid or itemtype');
return GRADE_UPDATE_FAILED;
}
if (!($grade_items = grade_item::fetch_all($params))) {
// create a new one
$grade_item = false;
} else {
if (count($grade_items) == 1) {
$grade_item = reset($grade_items);
unset($grade_items);
//release memory
} else {
debugging('Found more than one grade item');
return GRADE_UPDATE_MULTIPLE;
}
}
if (!empty($itemdetails['deleted'])) {
if ($grade_item) {
if ($grade_item->delete($source)) {
return GRADE_UPDATE_OK;
} else {
return GRADE_UPDATE_FAILED;
}
}
return GRADE_UPDATE_OK;
}
/// Create or update the grade_item if needed
if (!$grade_item) {
if ($itemdetails) {
$itemdetails = (array) $itemdetails;
// grademin and grademax ignored when scale specified
if (array_key_exists('scaleid', $itemdetails)) {
if ($itemdetails['scaleid']) {
unset($itemdetails['grademin']);
unset($itemdetails['grademax']);
}
}
foreach ($itemdetails as $k => $v) {
if (!in_array($k, $allowed)) {
// ignore it
continue;
}
if ($k == 'gradetype' and $v == GRADE_TYPE_NONE) {
// no grade item needed!
return GRADE_UPDATE_OK;
}
$params[$k] = $v;
}
}
$grade_item = new grade_item($params);
$grade_item->insert();
} else {
if ($grade_item->is_locked()) {
$message = get_string('gradeitemislocked', 'grades', $grade_item->itemname);
notice($message);
return GRADE_UPDATE_ITEM_LOCKED;
}
if ($itemdetails) {
$itemdetails = (array) $itemdetails;
$update = false;
foreach ($itemdetails as $k => $v) {
if (!in_array($k, $allowed)) {
// ignore it
continue;
}
if ($grade_item->{$k} != $v) {
$grade_item->{$k} = $v;
$update = true;
}
}
if ($update) {
$grade_item->update();
}
}
}
/// Some extra checks
// do we use grading?
if ($grade_item->gradetype == GRADE_TYPE_NONE) {
return GRADE_UPDATE_OK;
}
// no grade submitted
if (empty($grades)) {
return GRADE_UPDATE_OK;
}
/// Finally start processing of grades
if (is_object($grades)) {
$grades = array($grades);
} else {
if (array_key_exists('userid', $grades)) {
$grades = array($grades);
}
}
$failed = false;
foreach ($grades as $grade) {
$grade = (array) $grade;
if (empty($grade['userid'])) {
$failed = true;
debugging('Invalid userid in grade submitted');
continue;
} else {
$userid = $grade['userid'];
}
$rawgrade = false;
$feedback = false;
$feedbackformat = FORMAT_MOODLE;
if (array_key_exists('rawgrade', $grade)) {
$rawgrade = $grade['rawgrade'];
}
if (array_key_exists('feedback', $grade)) {
$feedback = $grade['feedback'];
}
if (array_key_exists('feedbackformat', $grade)) {
$feedbackformat = $grade['feedbackformat'];
}
if (array_key_exists('usermodified', $grade)) {
$usermodified = $grade['usermodified'];
} else {
$usermodified = $USER->id;
}
// update or insert the grade
if (!$grade_item->update_raw_grade($userid, $rawgrade, $source, null, $feedback, $feedbackformat, $usermodified)) {
$failed = true;
}
}
if (!$failed) {
return GRADE_UPDATE_OK;
} else {
return GRADE_UPDATE_FAILED;
}
}
/**
* Submit new or update grade; update/create grade_item definition. Grade must have userid specified,
* rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded'.
* Missing property or key means does not change the existing value.
*
* Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax',
* '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.
*
* @category grade
* @param string $source Source of the grade such as 'mod/assignment'
* @param int $courseid ID of course
* @param string $itemtype Type of grade item. For example, mod or block
* @param string $itemmodule More specific then $itemtype. For example, assignment or forum. May be NULL for some item types
* @param int $iteminstance Instance ID of graded item
* @param int $itemnumber Most probably 0. Modules can use other numbers when having more than one grade for each user
* @param mixed $grades Grade (object, array) or several grades (arrays of arrays or objects), NULL if updating grade_item definition only
* @param mixed $itemdetails Object or array describing the grading item, NULL if no change
* @return int Returns GRADE_UPDATE_OK, GRADE_UPDATE_FAILED, GRADE_UPDATE_MULTIPLE or GRADE_UPDATE_ITEM_LOCKED
*/
function grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades = NULL, $itemdetails = NULL)
{
global $USER, $CFG, $DB;
// only following grade_item properties can be changed in this function
$allowed = array('itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted', 'hidden');
// list of 10,5 numeric fields
$floats = array('grademin', 'grademax', 'multfactor', 'plusfactor');
// grade item identification
$params = compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber');
if (is_null($courseid) or is_null($itemtype)) {
debugging('Missing courseid or itemtype');
return GRADE_UPDATE_FAILED;
}
if (!($grade_items = grade_item::fetch_all($params))) {
// create a new one
$grade_item = false;
} else {
if (count($grade_items) == 1) {
$grade_item = reset($grade_items);
unset($grade_items);
//release memory
} else {
debugging('Found more than one grade item');
return GRADE_UPDATE_MULTIPLE;
}
}
if (!empty($itemdetails['deleted'])) {
if ($grade_item) {
if ($grade_item->delete($source)) {
return GRADE_UPDATE_OK;
} else {
return GRADE_UPDATE_FAILED;
}
}
return GRADE_UPDATE_OK;
}
/// Create or update the grade_item if needed
if (!$grade_item) {
if ($itemdetails) {
$itemdetails = (array) $itemdetails;
// grademin and grademax ignored when scale specified
if (array_key_exists('scaleid', $itemdetails)) {
if ($itemdetails['scaleid']) {
unset($itemdetails['grademin']);
unset($itemdetails['grademax']);
}
}
foreach ($itemdetails as $k => $v) {
if (!in_array($k, $allowed)) {
// ignore it
continue;
}
if ($k == 'gradetype' and $v == GRADE_TYPE_NONE) {
// no grade item needed!
return GRADE_UPDATE_OK;
}
$params[$k] = $v;
}
}
$grade_item = new grade_item($params);
$grade_item->insert();
} else {
if ($grade_item->is_locked()) {
// no notice() here, test returned value instead!
return GRADE_UPDATE_ITEM_LOCKED;
}
if ($itemdetails) {
$itemdetails = (array) $itemdetails;
$update = false;
foreach ($itemdetails as $k => $v) {
if (!in_array($k, $allowed)) {
// ignore it
continue;
}
if (in_array($k, $floats)) {
if (grade_floats_different($grade_item->{$k}, $v)) {
$grade_item->{$k} = $v;
$update = true;
}
} else {
if ($grade_item->{$k} != $v) {
$grade_item->{$k} = $v;
$update = true;
}
}
}
if ($update) {
$grade_item->update();
}
}
}
/// reset grades if requested
if (!empty($itemdetails['reset'])) {
$grade_item->delete_all_grades('reset');
return GRADE_UPDATE_OK;
}
/// Some extra checks
// do we use grading?
if ($grade_item->gradetype == GRADE_TYPE_NONE) {
return GRADE_UPDATE_OK;
}
// no grade submitted
if (empty($grades)) {
return GRADE_UPDATE_OK;
}
/// Finally start processing of grades
if (is_object($grades)) {
$grades = array($grades->userid => $grades);
} else {
if (array_key_exists('userid', $grades)) {
$grades = array($grades['userid'] => $grades);
}
}
/// normalize and verify grade array
foreach ($grades as $k => $g) {
if (!is_array($g)) {
$g = (array) $g;
$grades[$k] = $g;
}
if (empty($g['userid']) or $k != $g['userid']) {
debugging('Incorrect grade array index, must be user id! Grade ignored.');
unset($grades[$k]);
}
}
if (empty($grades)) {
return GRADE_UPDATE_FAILED;
}
$count = count($grades);
if ($count > 0 and $count < 200) {
list($uids, $params) = $DB->get_in_or_equal(array_keys($grades), SQL_PARAMS_NAMED, $start = 'uid');
$params['gid'] = $grade_item->id;
$sql = "SELECT * FROM {grade_grades} WHERE itemid = :gid AND userid {$uids}";
} else {
$sql = "SELECT * FROM {grade_grades} WHERE itemid = :gid";
$params = array('gid' => $grade_item->id);
}
$rs = $DB->get_recordset_sql($sql, $params);
$failed = false;
while (count($grades) > 0) {
$grade_grade = null;
$grade = null;
foreach ($rs as $gd) {
$userid = $gd->userid;
if (!isset($grades[$userid])) {
// this grade not requested, continue
continue;
}
// existing grade requested
$grade = $grades[$userid];
$grade_grade = new grade_grade($gd, false);
unset($grades[$userid]);
break;
}
if (is_null($grade_grade)) {
if (count($grades) == 0) {
// no more grades to process
break;
}
$grade = reset($grades);
$userid = $grade['userid'];
$grade_grade = new grade_grade(array('itemid' => $grade_item->id, 'userid' => $userid), false);
$grade_grade->load_optional_fields();
// add feedback and info too
unset($grades[$userid]);
}
$rawgrade = false;
$feedback = false;
$feedbackformat = FORMAT_MOODLE;
$usermodified = $USER->id;
$datesubmitted = null;
$dategraded = null;
if (array_key_exists('rawgrade', $grade)) {
$rawgrade = $grade['rawgrade'];
}
if (array_key_exists('feedback', $grade)) {
$feedback = $grade['feedback'];
}
if (array_key_exists('feedbackformat', $grade)) {
$feedbackformat = $grade['feedbackformat'];
}
if (array_key_exists('usermodified', $grade)) {
$usermodified = $grade['usermodified'];
}
if (array_key_exists('datesubmitted', $grade)) {
$datesubmitted = $grade['datesubmitted'];
}
if (array_key_exists('dategraded', $grade)) {
$dategraded = $grade['dategraded'];
}
// update or insert the grade
if (!$grade_item->update_raw_grade($userid, $rawgrade, $source, $feedback, $feedbackformat, $usermodified, $dategraded, $datesubmitted, $grade_grade)) {
$failed = true;
}
}
if ($rs) {
$rs->close();
}
if (!$failed) {
return GRADE_UPDATE_OK;
} else {
return GRADE_UPDATE_FAILED;
}
}
/**
* This updates existing grade items.
*
* @param int $courseid The course ID.
* @param array $map Mapping information provided by the user.
* @param int $key The line that we are currently working on.
* @param bool $verbosescales Form setting for grading with scales.
* @param string $value The grade value.
* @return array grades to be updated.
*/
protected function update_grade_item($courseid, $map, $key, $verbosescales, $value)
{
// Case of an id, only maps id of a grade_item.
// This was idnumber.
if (!($gradeitem = new grade_item(array('id' => $map[$key], 'courseid' => $courseid)))) {
// Supplied bad mapping, should not be possible since user
// had to pick mapping.
$this->cleanup_import(get_string('importfailed', 'grades'));
return null;
}
// Check if grade item is locked if so, abort.
if ($gradeitem->is_locked()) {
$this->cleanup_import(get_string('gradeitemlocked', 'grades'));
return null;
}
$newgrade = new stdClass();
$newgrade->itemid = $gradeitem->id;
if ($gradeitem->gradetype == GRADE_TYPE_SCALE and $verbosescales) {
if ($value === '' or $value == '-') {
$value = null;
// No grade.
} else {
$scale = $gradeitem->load_scale();
$scales = explode(',', $scale->scale);
$scales = array_map('trim', $scales);
// Hack - trim whitespace around scale options.
array_unshift($scales, '-');
// Scales start at key 1.
$key = array_search($value, $scales);
if ($key === false) {
$this->cleanup_import(get_string('badgrade', 'grades'));
return null;
}
$value = $key;
}
$newgrade->finalgrade = $value;
} else {
if ($value === '' or $value == '-') {
$value = null;
// No grade.
} else {
// If the value has a local decimal or can correctly be unformatted, do it.
$validvalue = unformat_float($value, true);
if ($validvalue !== false) {
$value = $validvalue;
} else {
// Non numeric grade value supplied, possibly mapped wrong column.
$this->cleanup_import(get_string('badgrade', 'grades'));
return null;
}
}
$newgrade->finalgrade = $value;
}
$this->newgrades[] = $newgrade;
return $this->newgrades;
}
