completion/criteria/completion_criteria_grade.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Course completion critieria - completion on achieving course grade
  19  *
  20  * @package core_completion
  21  * @category completion
  22  * @copyright 2009 Catalyst IT Ltd
  23  * @author Aaron Barnes <aaronb@catalyst.net.nz>
  24  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 defined('MOODLE_INTERNAL') || die();
  28 require_once $CFG->dirroot.'/grade/lib.php';
  29 require_once $CFG->dirroot.'/grade/querylib.php';
  30
  31 /**
  32  * Course completion critieria - completion on achieving course grade
  33  *
  34  * @package core_completion
  35  * @category completion
  36  * @copyright 2009 Catalyst IT Ltd
  37  * @author Aaron Barnes <aaronb@catalyst.net.nz>
  38  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39  */
  40 class completion_criteria_grade extends completion_criteria {
  41
  42     /* @var int Criteria type constant [COMPLETION_CRITERIA_TYPE_GRADE] */
  43     public $criteriatype = COMPLETION_CRITERIA_TYPE_GRADE;
  44
  45     /**
  46      * Finds and returns a data_object instance based on params.
  47      *
  48      * @param array $params associative array varname => value of various
  49      * parameters used to fetch data_object
  50      * @return data_object data_object instance or false if none found.
  51      */
  52     public static function fetch($params) {
  53         $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_GRADE;
  54         return self::fetch_helper('course_completion_criteria', __CLASS__, $params);
  55     }
  56
  57     /**
  58      * Add appropriate form elements to the critieria form
  59      *
  60      * @param moodle_form $mform Moodle forms object
  61      * @param stdClass $data containing default values to be set in the form
  62      */
  63     public function config_form_display(&$mform, $data = null) {
  64         $mform->addElement('checkbox', 'criteria_grade', get_string('enable'));
  65         $mform->addElement('text', 'criteria_grade_value', get_string('graderequired', 'completion'));
  66         $mform->disabledIf('criteria_grade_value', 'criteria_grade');
  67         $mform->setType('criteria_grade_value', PARAM_RAW); // Uses unformat_float.
  68         $mform->setDefault('criteria_grade_value', format_float($data));
  69
  70         if ($this->id) {
  71             $mform->setDefault('criteria_grade', 1);
  72             $mform->setDefault('criteria_grade_value', format_float($this->gradepass));
  73         }
  74     }
  75
  76     /**
  77      * Update the criteria information stored in the database
  78      *
  79      * @param stdClass $data Form data
  80      */
  81     public function update_config(&$data) {
  82
  83         if (!empty($data->criteria_grade)) {
  84             $formatedgrade = unformat_float($data->criteria_grade_value);
  85             // TODO validation
  86             if (!empty($formatedgrade) && is_numeric($formatedgrade)) {
  87                 $this->course = $data->id;
  88                 $this->gradepass = $formatedgrade;
  89                 $this->insert();
  90             }
  91         }
  92     }
  93
  94     /**
  95      * Get user's course grade in this course
  96      *
  97      * @param completion_completion $completion an instance of completion_completion class
  98      * @return float
  99      */
 100     private function get_grade($completion) {
 101         $grade = grade_get_course_grade($completion->userid, $this->course);
 102         return $grade->grade;
 103     }
 104
 105     /**
 106      * Review this criteria and decide if the user has completed
 107      *
 108      * @param completion_completion $completion The user's completion record
 109      * @param bool $mark Optionally set false to not save changes to database
 110      * @return bool
 111      */
 112     public function review($completion, $mark = true) {
 113         // Get user's course grade
 114         $grade = $this->get_grade($completion);
 115
 116         // If user's current course grade is higher than the required pass grade
 117         if ($this->gradepass && $this->gradepass <= $grade) {
 118             if ($mark) {
 119                 $completion->gradefinal = $grade;
 120                 $completion->mark_complete();
 121             }
 122
 123             return true;
 124         }
 125
 126         return false;
 127     }
 128
 129     /**
 130      * Return criteria title for display in reports
 131      *
 132      * @return  string
 133      */
 134     public function get_title() {
 135         return get_string('coursegrade', 'completion');
 136     }
 137
 138     /**
 139      * Return a more detailed criteria title for display in reports
 140      *
 141      * @return string
 142      */
 143     public function get_title_detailed() {
 144         $graderequired = round($this->gradepass, 2).'%';
 145         return get_string('gradexrequired', 'completion', $graderequired);
 146     }
 147
 148     /**
 149      * Return criteria type title for display in reports
 150      *
 151      * @return string
 152      */
 153     public function get_type_title() {
 154         return get_string('grade');
 155     }
 156
 157     /**
 158      * Return criteria status text for display in reports
 159      *
 160      * @param completion_completion $completion The user's completion record
 161      * @return string
 162      */
 163     public function get_status($completion) {
 164         $grade = $this->get_grade($completion);
 165         $graderequired = $this->get_title_detailed();
 166
 167         if ($grade) {
 168             $grade = round($grade, 2).'%';
 169         } else {
 170             $grade = get_string('nograde');
 171         }
 172
 173         return $grade.' ('.$graderequired.')';
 174     }
 175
 176     /**
 177      * Find user's who have completed this criteria
 178      */
 179     public function cron() {
 180         global $DB;
 181
 182         // Get all users who meet this criteria
 183         $sql = '
 184             SELECT DISTINCT
 185                 c.id AS course,
 186                 cr.id AS criteriaid,
 187                 ra.userid AS userid,
 188                 gg.finalgrade AS gradefinal,
 189                 gg.timemodified AS timecompleted
 190             FROM
 191                 {course_completion_criteria} cr
 192             INNER JOIN
 193                 {course} c
 194              ON cr.course = c.id
 195             INNER JOIN
 196                 {context} con
 197              ON con.instanceid = c.id
 198             INNER JOIN
 199                 {role_assignments} ra
 200               ON ra.contextid = con.id
 201             INNER JOIN
 202                 {grade_items} gi
 203              ON gi.courseid = c.id
 204             AND gi.itemtype = \'course\'
 205             INNER JOIN
 206                 {grade_grades} gg
 207              ON gg.itemid = gi.id
 208             AND gg.userid = ra.userid
 209             LEFT JOIN
 210                 {course_completion_crit_compl} cc
 211              ON cc.criteriaid = cr.id
 212             AND cc.userid = ra.userid
 213             WHERE
 214                 cr.criteriatype = '.COMPLETION_CRITERIA_TYPE_GRADE.'
 215             AND con.contextlevel = '.CONTEXT_COURSE.'
 216             AND c.enablecompletion = 1
 217             AND cc.id IS NULL
 218             AND gg.finalgrade >= cr.gradepass
 219         ';
 220
 221         // Loop through completions, and mark as complete
 222         $rs = $DB->get_recordset_sql($sql);
 223         foreach ($rs as $record) {
 224             $completion = new completion_criteria_completion((array) $record, DATA_OBJECT_FETCH_BY_KEY);
 225             $completion->mark_complete($record->timecompleted);
 226         }
 227         $rs->close();
 228     }
 229
 230     /**
 231      * Return criteria progress details for display in reports
 232      *
 233      * @param completion_completion $completion The user's completion record
 234      * @return array An array with the following keys:
 235      *     type, criteria, requirement, status
 236      */
 237     public function get_details($completion) {
 238         $details = array();
 239         $details['type'] = get_string('coursegrade', 'completion');
 240         $details['criteria'] = get_string('graderequired', 'completion');
 241         $details['requirement'] = round($this->gradepass, 2).'%';
 242         $details['status'] = '';
 243
 244         $grade = round($this->get_grade($completion), 2);
 245         if ($grade) {
 246             $details['status'] = $grade.'%';
 247         }
 248
 249         return $details;
 250     }
 251 }