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         // Grades are stored in Moodle with 5 decimal points, make sure we do not accidentally round them
  69         // when setting the form value.
  70         $mform->setDefault('criteria_grade_value', format_float($data, 5));
  71
  72         if ($this->id) {
  73             $mform->setDefault('criteria_grade', 1);
  74             $mform->setDefault('criteria_grade_value', format_float($this->gradepass, 5));
  75         }
  76     }
  77
  78     /**
  79      * Update the criteria information stored in the database
  80      *
  81      * @param stdClass $data Form data
  82      */
  83     public function update_config(&$data) {
  84
  85         if (!empty($data->criteria_grade)) {
  86             $formatedgrade = unformat_float($data->criteria_grade_value);
  87             // TODO validation
  88             if (!empty($formatedgrade) && is_numeric($formatedgrade)) {
  89                 $this->course = $data->id;
  90                 $this->gradepass = $formatedgrade;
  91                 $this->insert();
  92             }
  93         }
  94     }
  95
  96     /**
  97      * Get user's course grade in this course
  98      *
  99      * @param completion_completion $completion an instance of completion_completion class
 100      * @return float
 101      */
 102     private function get_grade($completion) {
 103         $grade = grade_get_course_grade($completion->userid, $this->course);
 104         return $grade->grade;
 105     }
 106
 107     /**
 108      * Review this criteria and decide if the user has completed
 109      *
 110      * @param completion_completion $completion The user's completion record
 111      * @param bool $mark Optionally set false to not save changes to database
 112      * @return bool
 113      */
 114     public function review($completion, $mark = true) {
 115         // Get user's course grade
 116         $grade = $this->get_grade($completion);
 117
 118         // If user's current course grade is higher than the required pass grade
 119         if ($this->gradepass && $this->gradepass <= $grade) {
 120             if ($mark) {
 121                 $completion->gradefinal = $grade;
 122                 $completion->mark_complete();
 123             }
 124
 125             return true;
 126         }
 127
 128         return false;
 129     }
 130
 131     /**
 132      * Return criteria title for display in reports
 133      *
 134      * @return  string
 135      */
 136     public function get_title() {
 137         return get_string('coursegrade', 'completion');
 138     }
 139
 140     /**
 141      * Return a more detailed criteria title for display in reports
 142      *
 143      * @return string
 144      */
 145     public function get_title_detailed() {
 146         global $CFG;
 147         require_once($CFG->libdir . '/gradelib.php');
 148         $decimalpoints = grade_get_setting($this->course, 'decimalpoints', $CFG->grade_decimalpoints);
 149         $graderequired = format_float($this->gradepass, $decimalpoints);
 150         return get_string('gradexrequired', 'completion', $graderequired);
 151     }
 152
 153     /**
 154      * Return criteria type title for display in reports
 155      *
 156      * @return string
 157      */
 158     public function get_type_title() {
 159         return get_string('gradenoun');
 160     }
 161
 162     /**
 163      * Return criteria status text for display in reports
 164      *
 165      * @param completion_completion $completion The user's completion record
 166      * @return string
 167      */
 168     public function get_status($completion) {
 169         global $CFG;
 170         require_once($CFG->libdir . '/gradelib.php');
 171         $decimalpoints = grade_get_setting($this->course, 'decimalpoints', $CFG->grade_decimalpoints);
 172
 173         $grade = $this->get_grade($completion);
 174         $graderequired = $this->get_title_detailed();
 175
 176         if ($grade) {
 177             $grade = format_float($grade, $decimalpoints);
 178         } else {
 179             $grade = get_string('nograde');
 180         }
 181
 182         return $grade.' ('.$graderequired.')';
 183     }
 184
 185     /**
 186      * Find user's who have completed this criteria
 187      */
 188     public function cron() {
 189         global $DB;
 190
 191         // Get all users who meet this criteria
 192         $sql = '
 193             SELECT DISTINCT
 194                 c.id AS course,
 195                 cr.id AS criteriaid,
 196                 ra.userid AS userid,
 197                 gg.finalgrade AS gradefinal,
 198                 gg.timemodified AS timecompleted
 199             FROM
 200                 {course_completion_criteria} cr
 201             INNER JOIN
 202                 {course} c
 203              ON cr.course = c.id
 204             INNER JOIN
 205                 {context} con
 206              ON con.instanceid = c.id
 207             INNER JOIN
 208                 {role_assignments} ra
 209               ON ra.contextid = con.id
 210             INNER JOIN
 211                 {grade_items} gi
 212              ON gi.courseid = c.id
 213             AND gi.itemtype = \'course\'
 214             INNER JOIN
 215                 {grade_grades} gg
 216              ON gg.itemid = gi.id
 217             AND gg.userid = ra.userid
 218             LEFT JOIN
 219                 {course_completion_crit_compl} cc
 220              ON cc.criteriaid = cr.id
 221             AND cc.userid = ra.userid
 222             WHERE
 223                 cr.criteriatype = '.COMPLETION_CRITERIA_TYPE_GRADE.'
 224             AND con.contextlevel = '.CONTEXT_COURSE.'
 225             AND c.enablecompletion = 1
 226             AND cc.id IS NULL
 227             AND gg.finalgrade >= cr.gradepass
 228         ';
 229
 230         // Loop through completions, and mark as complete
 231         $rs = $DB->get_recordset_sql($sql);
 232         foreach ($rs as $record) {
 233             $completion = new completion_criteria_completion((array) $record, DATA_OBJECT_FETCH_BY_KEY);
 234             $completion->mark_complete($record->timecompleted);
 235         }
 236         $rs->close();
 237     }
 238
 239     /**
 240      * Return criteria progress details for display in reports
 241      *
 242      * @param completion_completion $completion The user's completion record
 243      * @return array An array with the following keys:
 244      *     type, criteria, requirement, status
 245      */
 246     public function get_details($completion) {
 247         global $CFG;
 248         require_once($CFG->libdir . '/gradelib.php');
 249         $decimalpoints = grade_get_setting($this->course, 'decimalpoints', $CFG->grade_decimalpoints);
 250
 251         $details = array();
 252         $details['type'] = get_string('coursegrade', 'completion');
 253         $details['criteria'] = get_string('graderequired', 'completion');
 254         $details['requirement'] = format_float($this->gradepass, $decimalpoints);
 255         $details['status'] = '';
 256
 257         $grade = format_float($this->get_grade($completion), $decimalpoints);
 258         if ($grade) {
 259             $details['status'] = $grade;
 260         }
 261
 262         return $details;
 263     }
 264
 265     /**
 266      * Return pix_icon for display in reports.
 267      *
 268      * @param string $alt The alt text to use for the icon
 269      * @param array $attributes html attributes
 270      * @return pix_icon
 271      */
 272     public function get_icon($alt, array $attributes = null) {
 273         return new pix_icon('i/grades', $alt, 'moodle', $attributes);
 274     }
 275 }