MDL-65276 core: fix CiBoT complains
[moodle.git] / completion / criteria / completion_criteria.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
2be4d090
MD
17/**
18 * Course completion criteria
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();
75342343
AB
28require_once($CFG->dirroot.'/completion/data_object.php');
29require_once($CFG->dirroot.'/completion/completion_criteria_completion.php');
2be4d090 30
2be4d090 31/**
836375ec
SH
32 * Self completion criteria type
33 * Criteria type constant, primarily for storing criteria type in the database.
2be4d090
MD
34 */
35define('COMPLETION_CRITERIA_TYPE_SELF', 1);
836375ec
SH
36
37/**
38 * Date completion criteria type
39 * Criteria type constant, primarily for storing criteria type in the database.
40 */
2be4d090 41define('COMPLETION_CRITERIA_TYPE_DATE', 2);
836375ec
SH
42
43/**
44 * Unenrol completion criteria type
45 * Criteria type constant, primarily for storing criteria type in the database.
46 */
2be4d090 47define('COMPLETION_CRITERIA_TYPE_UNENROL', 3);
836375ec
SH
48
49/**
50 * Activity completion criteria type
51 * Criteria type constant, primarily for storing criteria type in the database.
52 */
2be4d090 53define('COMPLETION_CRITERIA_TYPE_ACTIVITY', 4);
836375ec
SH
54
55/**
56 * Duration completion criteria type
57 * Criteria type constant, primarily for storing criteria type in the database.
58 */
2be4d090 59define('COMPLETION_CRITERIA_TYPE_DURATION', 5);
836375ec
SH
60
61/**
62 * Grade completion criteria type
63 * Criteria type constant, primarily for storing criteria type in the database.
64 */
2be4d090 65define('COMPLETION_CRITERIA_TYPE_GRADE', 6);
836375ec
SH
66
67/**
68 * Role completion criteria type
69 * Criteria type constant, primarily for storing criteria type in the database.
70 */
2be4d090 71define('COMPLETION_CRITERIA_TYPE_ROLE', 7);
836375ec
SH
72
73/**
74 * Course completion criteria type
75 * Criteria type constant, primarily for storing criteria type in the database.
76 */
2be4d090
MD
77define('COMPLETION_CRITERIA_TYPE_COURSE', 8);
78
79/**
846c5859
SL
80 * Criteria type constant to class name mapping.
81 *
82 * This global variable would be improved if it was implemented as a cache.
2be4d090
MD
83 */
84global $COMPLETION_CRITERIA_TYPES;
85$COMPLETION_CRITERIA_TYPES = array(
86 COMPLETION_CRITERIA_TYPE_SELF => 'self',
87 COMPLETION_CRITERIA_TYPE_DATE => 'date',
88 COMPLETION_CRITERIA_TYPE_UNENROL => 'unenrol',
89 COMPLETION_CRITERIA_TYPE_ACTIVITY => 'activity',
90 COMPLETION_CRITERIA_TYPE_DURATION => 'duration',
91 COMPLETION_CRITERIA_TYPE_GRADE => 'grade',
92 COMPLETION_CRITERIA_TYPE_ROLE => 'role',
93 COMPLETION_CRITERIA_TYPE_COURSE => 'course',
94);
95
96
97/**
98 * Completion criteria abstract definition
836375ec
SH
99 *
100 * @package core_completion
101 * @category completion
102 * @copyright 2009 Catalyst IT Ltd
103 * @author Aaron Barnes <aaronb@catalyst.net.nz>
104 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2be4d090
MD
105 */
106abstract class completion_criteria extends data_object {
836375ec 107
95dd54ee 108 /* @var string Database table name that stores completion criteria information */
2be4d090
MD
109 public $table = 'course_completion_criteria';
110
111 /**
112 * Array of required table fields, must start with 'id'.
836375ec
SH
113 * Defaults to id, course, criteriatype, module, moduleinstane, courseinstance,
114 * enrolperiod, timeend, gradepass, role
115 * @var array
2be4d090 116 */
fe09ccba 117 public $required_fields = array('id', 'course', 'criteriatype', 'module', 'moduleinstance', 'courseinstance', 'enrolperiod', 'timeend', 'gradepass', 'role');
2be4d090 118
95dd54ee 119 /* @var int Course id */
2be4d090
MD
120 public $course;
121
122 /**
123 * Criteria type
124 * One of the COMPLETION_CRITERIA_TYPE_* constants
836375ec 125 * @var int
2be4d090
MD
126 */
127 public $criteriatype;
128
95dd54ee 129 /* @var string Module type this criteria relates to (for activity criteria) */
2be4d090
MD
130 public $module;
131
95dd54ee 132 /* @var int Course module instance id this criteria relates to (for activity criteria) */
2be4d090
MD
133 public $moduleinstance;
134
135 /**
136 * Period after enrolment completion will be triggered (for period criteria)
836375ec
SH
137 * The value here is the number of days as an int.
138 * @var int
2be4d090
MD
139 */
140 public $enrolperiod;
141
142 /**
143 * Date of course completion (for date criteria)
836375ec
SH
144 * This is a timestamp value
145 * @var int
2be4d090
MD
146 */
147 public $date;
148
95dd54ee 149 /* @var float Passing grade required to complete course (for grade completion) */
2be4d090
MD
150 public $gradepass;
151
95dd54ee 152 /* @var int Role ID that has the ability to mark a user as complete (for role completion) */
2be4d090
MD
153 public $role;
154
155 /**
156 * Finds and returns all data_object instances based on params.
2be4d090
MD
157 *
158 * @param array $params associative arrays varname=>value
159 * @return array array of data_object insatnces or false if none found.
160 */
161 public static function fetch_all($params) {}
162
163 /**
164 * Factory method for creating correct class object
836375ec
SH
165 *
166 * @param array $params associative arrays varname=>value
167 * @return completion_criteria
2be4d090
MD
168 */
169 public static function factory($params) {
170 global $CFG, $COMPLETION_CRITERIA_TYPES;
171
dbfcf440 172 if (!isset($params['criteriatype']) || !isset($COMPLETION_CRITERIA_TYPES[$params['criteriatype']])) {
2149326b 173 print_error('invalidcriteriatype', 'completion');
2be4d090
MD
174 }
175
dbfcf440 176 $class = 'completion_criteria_'.$COMPLETION_CRITERIA_TYPES[$params['criteriatype']];
60829d80 177 require_once($CFG->dirroot.'/completion/criteria/'.$class.'.php');
2be4d090
MD
178
179 return new $class($params, false);
180 }
181
182 /**
183 * Add appropriate form elements to the critieria form
95dd54ee 184 *
836375ec 185 * @param moodleform $mform Moodle forms object
95dd54ee 186 * @param mixed $data optional Any additional data that can be used to set default values in the form
836375ec 187 * @return void
2be4d090
MD
188 */
189 abstract public function config_form_display(&$mform, $data = null);
190
191 /**
192 * Update the criteria information stored in the database
836375ec
SH
193 *
194 * @param array $data Form data
195 * @return void
2be4d090
MD
196 */
197 abstract public function update_config(&$data);
198
199 /**
200 * Review this criteria and decide if the user has completed
836375ec
SH
201 *
202 * @param object $completion The user's completion record
203 * @param boolean $mark Optionally set false to not save changes to database
204 * @return boolean
2be4d090
MD
205 */
206 abstract public function review($completion, $mark = true);
207
208 /**
209 * Return criteria title for display in reports
836375ec
SH
210 *
211 * @return string
2be4d090
MD
212 */
213 abstract public function get_title();
214
215 /**
216 * Return a more detailed criteria title for display in reports
836375ec
SH
217 *
218 * @return string
2be4d090
MD
219 */
220 abstract public function get_title_detailed();
221
222 /**
223 * Return criteria type title for display in reports
836375ec
SH
224 *
225 * @return string
2be4d090
MD
226 */
227 abstract public function get_type_title();
228
229 /**
230 * Return criteria progress details for display in reports
836375ec
SH
231 *
232 * @param completion_completion $completion The user's completion record
233 * @return array
2be4d090
MD
234 */
235 abstract public function get_details($completion);
236
7062e7c6
CB
237 /**
238 * Return pix_icon for display in reports.
239 *
240 * @param string $alt The alt text to use for the icon
241 * @param array $attributes html attributes
242 * @return pix_icon
243 */
244 public function get_icon($alt, array $attributes = null) {
245 global $COMPLETION_CRITERIA_TYPES;
246
247 $criteriatype = $COMPLETION_CRITERIA_TYPES[$this->criteriatype];
248 return new pix_icon('i/'.$criteriatype, $alt, 'moodle', $attributes);
249 }
250
2be4d090
MD
251 /**
252 * Return criteria status text for display in reports
836375ec
SH
253 *
254 * @param completion_completion $completion The user's completion record
255 * @return string
2be4d090
MD
256 */
257 public function get_status($completion) {
258 return $completion->is_complete() ? get_string('yes') : get_string('no');
259 }
260
261 /**
262 * Return true if the criteria's current status is different to what is sorted
263 * in the database, e.g. pending an update
264 *
836375ec 265 * @param completion_completion $completion The user's criteria completion record
2be4d090
MD
266 * @return bool
267 */
268 public function is_pending($completion) {
269 $review = $this->review($completion, false);
270
271 return $review !== $completion->is_complete();
272 }
95dd54ee 273}