MDL-30995 completion: Fixed up PHPdocs for activity completion
[moodle.git] / lib / completion / completion_criteria_activity.php
CommitLineData
2be4d090
MD
1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
836375ec
SH
18/**
19 * This file contains the activity completion criteria type class and any
20 * supporting functions it may require.
21 *
22 * @package core_completion
23 * @category completion
24 * @copyright 2009 Catalyst IT Ltd
25 * @author Aaron Barnes <aaronb@catalyst.net.nz>
26 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 */
28
29defined('MOODLE_INTERNAL') || die();
30
2be4d090
MD
31/**
32 * Course completion critieria - completion on activity completion
33 *
836375ec
SH
34 * @package core_completion
35 * @category completion
2be4d090 36 * @copyright 2009 Catalyst IT Ltd
836375ec
SH
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_activity extends completion_criteria {
41
42 /**
43 * Criteria type constant
836375ec 44 * @var int [COMPLETION_CRITERIA_TYPE_ACTIVITY]
2be4d090
MD
45 */
46 public $criteriatype = COMPLETION_CRITERIA_TYPE_ACTIVITY;
47
48 /**
49 * Finds and returns a data_object instance based on params.
2be4d090
MD
50 *
51 * @param array $params associative arrays varname=>value
836375ec 52 * @return completion_criteria_activity data_object instance or false if none found.
2be4d090
MD
53 */
54 public static function fetch($params) {
55 $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_ACTIVITY;
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 moodleform $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_activity['.$data->id.']', ucfirst(self::get_mod_name($data->module)).' - '.$data->name);
67
68 if ($this->id) {
69 $mform->setDefault('criteria_activity['.$data->id.']', 1);
70 }
71 }
72
73 /**
74 * Update the criteria information stored in the database
836375ec
SH
75 *
76 * @param stdClass $data Form data
2be4d090
MD
77 */
78 public function update_config(&$data) {
79 global $DB;
80
81 if (!empty($data->criteria_activity) && is_array($data->criteria_activity)) {
82
83 $this->course = $data->id;
84
85 foreach (array_keys($data->criteria_activity) as $activity) {
86
87 $module = $DB->get_record('course_modules', array('id' => $activity));
88 $this->module = self::get_mod_name($module->module);
89 $this->moduleinstance = $activity;
90 $this->id = NULL;
91 $this->insert();
92 }
93 }
94 }
95
96 /**
97 * Get module instance module type
836375ec
SH
98 *
99 * @param int $type Module type id
100 * @return string
2be4d090
MD
101 */
102 public static function get_mod_name($type) {
103 static $types;
104
105 if (!is_array($types)) {
106 global $DB;
107 $types = $DB->get_records('modules');
108 }
109
110 return $types[$type]->name;
111 }
112
113 /**
836375ec
SH
114 * Gets the module instance from the database and returns it.
115 * If no module instance exists this function returns false.
116 *
117 * @return stdClass|false
2be4d090
MD
118 */
119 public function get_mod_instance() {
120 global $DB;
121
122 return $DB->get_record_sql(
123 "
124 SELECT
125 m.*
126 FROM
127 {{$this->module}} m
128 INNER JOIN
129 {course_modules} cm
130 ON cm.id = {$this->moduleinstance}
131 AND m.id = cm.instance
132 "
133 );
134 }
135
136 /**
137 * Review this criteria and decide if the user has completed
836375ec
SH
138 *
139 * @param completion_completion $completion The user's completion record
140 * @param boolean $mark Optionally set false to not save changes to database
141 * @return boolean
2be4d090
MD
142 */
143 public function review($completion, $mark = true) {
144 global $DB;
145
146 $course = $DB->get_record('course', array('id' => $completion->course));
147 $cm = $DB->get_record('course_modules', array('id' => $this->moduleinstance));
148 $info = new completion_info($course);
149
150 $data = $info->get_data($cm, false, $completion->userid);
151
152 // If the activity is complete
153 if (in_array($data->completionstate, array(COMPLETION_COMPLETE, COMPLETION_COMPLETE_PASS))) {
154 if ($mark) {
155 $completion->mark_complete();
156 }
157
158 return true;
159 }
160
161 return false;
162 }
163
164 /**
165 * Return criteria title for display in reports
836375ec
SH
166 *
167 * @return string
2be4d090
MD
168 */
169 public function get_title() {
170 return get_string('activitiescompleted', 'completion');
171 }
172
173 /**
174 * Return a more detailed criteria title for display in reports
836375ec 175 *
2be4d090
MD
176 * @return string
177 */
178 public function get_title_detailed() {
179 global $DB;
180 $module = $DB->get_record('course_modules', array('id' => $this->moduleinstance));
181 $activity = $DB->get_record($this->module, array('id' => $module->instance));
182
183 return shorten_text(urldecode($activity->name));
184 }
185
186 /**
187 * Return criteria type title for display in reports
836375ec 188 *
2be4d090
MD
189 * @return string
190 */
191 public function get_type_title() {
192 return get_string('activities', 'completion');
193 }
194
195 /**
836375ec 196 * Find user's who have completed this criteria and mark them accordingly
2be4d090
MD
197 */
198 public function cron() {
199 global $DB;
200
201 // Get all users who meet this criteria
202 $sql = '
203 SELECT DISTINCT
204 c.id AS course,
2be4d090
MD
205 cr.id AS criteriaid,
206 ra.userid AS userid,
207 mc.timemodified AS timecompleted
208 FROM
209 {course_completion_criteria} cr
210 INNER JOIN
211 {course} c
212 ON cr.course = c.id
213 INNER JOIN
214 {context} con
215 ON con.instanceid = c.id
216 INNER JOIN
217 {role_assignments} ra
218 ON ra.contextid = con.id
219 INNER JOIN
220 {course_modules_completion} mc
221 ON mc.coursemoduleid = cr.moduleinstance
222 AND mc.userid = ra.userid
223 LEFT JOIN
224 {course_completion_crit_compl} cc
225 ON cc.criteriaid = cr.id
226 AND cc.userid = ra.userid
227 WHERE
228 cr.criteriatype = '.COMPLETION_CRITERIA_TYPE_ACTIVITY.'
229 AND con.contextlevel = '.CONTEXT_COURSE.'
230 AND c.enablecompletion = 1
231 AND cc.id IS NULL
232 AND (
233 mc.completionstate = '.COMPLETION_COMPLETE.'
234 OR mc.completionstate = '.COMPLETION_COMPLETE_PASS.'
235 )
236 ';
237
238 // Loop through completions, and mark as complete
419178d7
EL
239 $rs = $DB->get_recordset_sql($sql);
240 foreach ($rs as $record) {
2be4d090 241
419178d7
EL
242 $completion = new completion_criteria_completion((array)$record);
243 $completion->mark_complete($record->timecompleted);
2be4d090 244 }
419178d7 245 $rs->close();
2be4d090
MD
246 }
247
248 /**
249 * Return criteria progress details for display in reports
836375ec
SH
250 *
251 * @param completion_completion $completion The user's completion record
252 * @return array An array with the following keys:
253 * type, criteria, requirement, status
2be4d090
MD
254 */
255 public function get_details($completion) {
256 global $DB, $CFG;
257
258 // Get completion info
365a5941 259 $course = new stdClass();
2be4d090
MD
260 $course->id = $completion->course;
261 $info = new completion_info($course);
262
263 $module = $DB->get_record('course_modules', array('id' => $this->moduleinstance));
264 $data = $info->get_data($module, false, $completion->userid);
265
266 $activity = $DB->get_record($this->module, array('id' => $module->instance));
267
268 $details = array();
269 $details['type'] = $this->get_title();
270 $details['criteria'] = '<a href="'.$CFG->wwwroot.'/mod/'.$this->module.'/view.php?id='.$this->moduleinstance.'">'.$activity->name.'</a>';
271
272 // Build requirements
273 $details['requirement'] = array();
274
275 if ($module->completion == 1) {
276 $details['requirement'][] = get_string('markingyourselfcomplete', 'completion');
277 } elseif ($module->completion == 2) {
278 if ($module->completionview) {
279 $details['requirement'][] = get_string('viewingactivity', 'completion', $this->module);
280 }
281
47567108 282 if (!is_null($module->completiongradeitemnumber)) {
2be4d090
MD
283 $details['requirement'][] = get_string('achievinggrade', 'completion');
284 }
285 }
286
287 $details['requirement'] = implode($details['requirement'], ', ');
288
289 $details['status'] = '';
290
291 return $details;
292 }
836375ec 293}\