MDL-30995 completion: Fixed up PHPdocs for activity completion
[moodle.git] / lib / completion / completion_criteria_grade.php
CommitLineData
2be4d090 1<?php
2be4d090
MD
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 *
836375ec
SH
20 * @package core_completion
21 * @category completion
2be4d090 22 * @copyright 2009 Catalyst IT Ltd
836375ec
SH
23 * @author Aaron Barnes <aaronb@catalyst.net.nz>
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2be4d090 25 */
836375ec
SH
26
27defined('MOODLE_INTERNAL') || die();
2be4d090
MD
28require_once $CFG->dirroot.'/grade/lib.php';
29require_once $CFG->dirroot.'/grade/querylib.php';
30
31/**
32 * Course completion critieria - completion on achieving course grade
836375ec
SH
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
2be4d090
MD
39 */
40class completion_criteria_grade extends completion_criteria {
41
42 /**
836375ec 43 * Criteria type constant [COMPLETION_CRITERIA_TYPE_GRADE]
2be4d090
MD
44 * @var int
45 */
46 public $criteriatype = COMPLETION_CRITERIA_TYPE_GRADE;
47
48 /**
49 * Finds and returns a data_object instance based on params.
2be4d090 50 *
836375ec
SH
51 * @param array $params associative arrays varname => value
52 * @return data_object data_object instance or false if none found.
2be4d090
MD
53 */
54 public static function fetch($params) {
55 $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_GRADE;
56 return self::fetch_helper('course_completion_criteria', __CLASS__, $params);
57 }
58
59 /**
60 * Add appropriate form elements to the critieria form
836375ec
SH
61 *
62 * @param moodle_form $mform Moodle forms object
63 * @param stdClass $data
2be4d090
MD
64 */
65 public function config_form_display(&$mform, $data = null) {
66 $mform->addElement('checkbox', 'criteria_grade', get_string('enable'));
67 $mform->addElement('text', 'criteria_grade_value', get_string('passinggrade', 'completion'));
68 $mform->setDefault('criteria_grade_value', $data);
69
70 if ($this->id) {
71 $mform->setDefault('criteria_grade', 1);
72 $mform->setDefault('criteria_grade_value', $this->gradepass);
73 }
74 }
75
76 /**
77 * Update the criteria information stored in the database
836375ec
SH
78 *
79 * @param stdClass $data Form data
2be4d090
MD
80 */
81 public function update_config(&$data) {
836375ec 82 if (!empty($data->criteria_grade) && is_numeric($data->criteria_grade_value)) {
2be4d090
MD
83 $this->course = $data->id;
84 $this->gradepass = $data->criteria_grade_value;
85 $this->insert();
86 }
87 }
88
89 /**
90 * Get user's course grade in this course
836375ec
SH
91 *
92 * @param completion_completion $completion
93 * @return float
2be4d090
MD
94 */
95 private function get_grade($completion) {
96 $grade = grade_get_course_grade($completion->userid, $this->course);
97 return $grade->grade;
98 }
99
100 /**
101 * Review this criteria and decide if the user has completed
836375ec
SH
102 *
103 * @param completion_completion $completion The user's completion record
104 * @param boolean $mark Optionally set false to not save changes to database
105 * @return boolean
2be4d090
MD
106 */
107 public function review($completion, $mark = true) {
108 // Get user's course grade
109 $grade = $this->get_grade($completion);
110
111 // If user's current course grade is higher than the required pass grade
112 if ($this->gradepass && $this->gradepass <= $grade) {
113 if ($mark) {
114 $completion->gradefinal = $grade;
115 $completion->mark_complete();
116 }
117
118 return true;
119 }
120
121 return false;
122 }
123
124 /**
125 * Return criteria title for display in reports
836375ec 126 *
2be4d090
MD
127 * @return string
128 */
129 public function get_title() {
130 return get_string('grade');
131 }
132
133 /**
134 * Return a more detailed criteria title for display in reports
836375ec
SH
135 *
136 * @return string
2be4d090
MD
137 */
138 public function get_title_detailed() {
139 return (float) $this->gradepass . '% required';
140 }
141
142 /**
143 * Return criteria type title for display in reports
836375ec
SH
144 *
145 * @return string
2be4d090
MD
146 */
147 public function get_type_title() {
148 return get_string('grade');
149 }
150
151 /**
152 * Return criteria status text for display in reports
836375ec
SH
153 *
154 * @param completion_completion $completion The user's completion record
155 * @return string
2be4d090
MD
156 */
157 public function get_status($completion) {
158 // Cast as floats to get rid of excess decimal places
159 $grade = (float) $this->get_grade($completion);
160 $gradepass = (float) $this->gradepass;
161
162 if ($grade) {
163 return $grade.'% ('.$gradepass.'% to pass)';
164 } else {
165 return $gradepass.'% to pass';
166 }
167 }
168
169 /**
170 * Find user's who have completed this criteria
2be4d090
MD
171 */
172 public function cron() {
173 global $DB;
174
175 // Get all users who meet this criteria
176 $sql = '
177 SELECT DISTINCT
178 c.id AS course,
2be4d090
MD
179 cr.id AS criteriaid,
180 ra.userid AS userid,
181 gg.finalgrade AS gradefinal,
182 gg.timemodified AS timecompleted
183 FROM
184 {course_completion_criteria} cr
185 INNER JOIN
186 {course} c
187 ON cr.course = c.id
188 INNER JOIN
189 {context} con
190 ON con.instanceid = c.id
191 INNER JOIN
192 {role_assignments} ra
193 ON ra.contextid = con.id
194 INNER JOIN
195 {grade_items} gi
196 ON gi.courseid = c.id
197 AND gi.itemtype = \'course\'
198 INNER JOIN
199 {grade_grades} gg
200 ON gg.itemid = gi.id
201 AND gg.userid = ra.userid
202 LEFT JOIN
203 {course_completion_crit_compl} cc
204 ON cc.criteriaid = cr.id
205 AND cc.userid = ra.userid
206 WHERE
207 cr.criteriatype = '.COMPLETION_CRITERIA_TYPE_GRADE.'
208 AND con.contextlevel = '.CONTEXT_COURSE.'
209 AND c.enablecompletion = 1
210 AND cc.id IS NULL
211 AND gg.finalgrade >= cr.gradepass
212 ';
213
214 // Loop through completions, and mark as complete
419178d7
EL
215 $rs = $DB->get_recordset_sql($sql);
216 foreach ($rs as $record) {
217 $completion = new completion_criteria_completion((array)$record);
218 $completion->mark_complete($record->timecompleted);
2be4d090 219 }
419178d7 220 $rs->close();
2be4d090
MD
221 }
222
223 /**
224 * Return criteria progress details for display in reports
836375ec
SH
225 *
226 * @param completion_completion $completion The user's completion record
227 * @return array An array with the following keys:
228 * type, criteria, requirement, status
2be4d090
MD
229 */
230 public function get_details($completion) {
231 $details = array();
232 $details['type'] = get_string('coursegrade', 'completion');
233 $details['criteria'] = get_string('passinggrade', 'completion');
234 $details['requirement'] = ((float)$this->gradepass).'%';
235 $details['status'] = '';
236
237 $grade = (float)$this->get_grade($completion);
238 if ($grade) {
239 $details['status'] = $grade.'%';
240 }
241
242 return $details;
243 }
836375ec 244}