2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * Badge award criteria
22 * @copyright 2012 onwards Totara Learning Solutions Ltd {@link http://www.totaralms.com/}
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 * @author Yuliya Bozhko <yuliya.bozhko@totaralms.com>
27 defined('MOODLE_INTERNAL') ||
die();
30 * Role completion criteria type
31 * Criteria type constant, primarily for storing criteria type in the database.
33 define('BADGE_CRITERIA_TYPE_OVERALL', 0);
36 * Activity completion criteria type
37 * Criteria type constant, primarily for storing criteria type in the database.
39 define('BADGE_CRITERIA_TYPE_ACTIVITY', 1);
42 * Duration completion criteria type
43 * Criteria type constant, primarily for storing criteria type in the database.
45 define('BADGE_CRITERIA_TYPE_MANUAL', 2);
48 * Grade completion criteria type
49 * Criteria type constant, primarily for storing criteria type in the database.
51 define('BADGE_CRITERIA_TYPE_SOCIAL', 3);
54 * Course completion criteria type
55 * Criteria type constant, primarily for storing criteria type in the database.
57 define('BADGE_CRITERIA_TYPE_COURSE', 4);
60 * Courseset completion criteria type
61 * Criteria type constant, primarily for storing criteria type in the database.
63 define('BADGE_CRITERIA_TYPE_COURSESET', 5);
66 * Course completion criteria type
67 * Criteria type constant, primarily for storing criteria type in the database.
69 define('BADGE_CRITERIA_TYPE_PROFILE', 6);
72 * Badge completion criteria type
73 * Criteria type constant, primarily for storing criteria type in the database.
75 define('BADGE_CRITERIA_TYPE_BADGE', 7);
78 * Cohort criteria type
79 * Criteria type constant, primarily for storing criteria type in the database.
81 define('BADGE_CRITERIA_TYPE_COHORT', 8);
84 * Competency criteria type
85 * Criteria type constant, primarily for storing criteria type in the database.
87 define('BADGE_CRITERIA_TYPE_COMPETENCY', 9);
90 * Award criteria abstract definition
93 abstract class award_criteria
{
96 * ID of the criterion.
102 * Aggregation method [BADGE_CRITERIA_AGGREGATION_ANY, BADGE_CRITERIA_AGGREGATION_ALL].
108 * ID of a badge this criterion belongs to.
114 * Criterion HTML/plain text description.
120 * Format of the criterion description.
123 public $descriptionformat;
126 * Any additional parameters.
129 public $params = array();
132 * The base constructor
134 * @param array $params
136 public function __construct($params) {
137 $this->id
= isset($params['id']) ?
$params['id'] : 0;
138 $this->method
= isset($params['method']) ?
$params['method'] : BADGE_CRITERIA_AGGREGATION_ANY
;
139 $this->badgeid
= $params['badgeid'];
140 $this->description
= isset($params['description']) ?
$params['description'] : '';
141 $this->descriptionformat
= isset($params['descriptionformat']) ?
$params['descriptionformat'] : FORMAT_HTML
;
142 if (isset($params['id'])) {
143 $this->params
= $this->get_params($params['id']);
148 * Factory method for creating criteria class object
150 * @param array $params associative arrays varname => value
151 * @return award_criteria
153 public static function build($params) {
156 require_once($CFG->libdir
. '/badgeslib.php');
158 $types = badges_list_criteria(false);
160 if (!isset($params['criteriatype']) ||
!isset($types[$params['criteriatype']])) {
161 throw new \
moodle_exception('error:invalidcriteriatype', 'badges');
164 $class = 'award_criteria_' . $types[$params['criteriatype']];
165 require_once($CFG->dirroot
. '/badges/criteria/' . $class . '.php');
167 return new $class($params);
171 * Return criteria title
175 public function get_title() {
176 return get_string('criteria_' . $this->criteriatype
, 'badges');
180 * Get criteria details for displaying to users
182 * @param string $short Print short version of criteria
185 abstract public function get_details($short = '');
188 * Add appropriate criteria options to the form
191 abstract public function get_options(&$mform);
194 * Add appropriate parameter elements to the criteria form
197 public function config_options(&$mform, $param) {
199 $prefix = $this->required_param
. '_';
201 if ($param['error']) {
202 $parameter[] =& $mform->createElement('advcheckbox', $prefix . $param['id'], '',
203 $OUTPUT->error_text($param['name']), null, array(0, $param['id']));
204 $mform->addGroup($parameter, 'param_' . $prefix . $param['id'], '', array(' '), false);
206 $parameter[] =& $mform->createElement('advcheckbox', $prefix . $param['id'], '', $param['name'], null, array(0, $param['id']));
207 $parameter[] =& $mform->createElement('static', 'break_start_' . $param['id'], null,
208 '<div class="ml-3 mt-1 w-100 align-items-center">');
210 if (in_array('grade', $this->optional_params
)) {
211 $parameter[] =& $mform->createElement('static', 'mgrade_' . $param['id'], null, get_string('mingrade', 'badges'));
212 $parameter[] =& $mform->createElement('text', 'grade_' . $param['id'], '', array('size' => '5'));
213 $mform->setType('grade_' . $param['id'], PARAM_INT
);
216 if (in_array('bydate', $this->optional_params
)) {
217 $parameter[] =& $mform->createElement('static', 'complby_' . $param['id'], null, get_string('bydate', 'badges'));
218 $parameter[] =& $mform->createElement('date_selector', 'bydate_' . $param['id'], "", array('optional' => true));
221 $parameter[] =& $mform->createElement('static', 'break_end_' . $param['id'], null, '</div>');
222 $mform->addGroup($parameter, 'param_' . $prefix . $param['id'], '', array(' '), false);
223 if (in_array('grade', $this->optional_params
)) {
224 $mform->addGroupRule('param_' . $prefix . $param['id'], array(
225 'grade_' . $param['id'] => array(array(get_string('err_numeric', 'form'), 'numeric', '', 'client'))));
227 $mform->disabledIf('bydate_' . $param['id'] . '[day]', 'bydate_' . $param['id'] . '[enabled]', 'notchecked');
228 $mform->disabledIf('bydate_' . $param['id'] . '[month]', 'bydate_' . $param['id'] . '[enabled]', 'notchecked');
229 $mform->disabledIf('bydate_' . $param['id'] . '[year]', 'bydate_' . $param['id'] . '[enabled]', 'notchecked');
230 $mform->disabledIf('param_' . $prefix . $param['id'], $prefix . $param['id'], 'notchecked');
233 // Set default values.
234 $mform->setDefault($prefix . $param['id'], $param['checked']);
235 if (isset($param['bydate'])) {
236 $mform->setDefault('bydate_' . $param['id'], $param['bydate']);
238 if (isset($param['grade'])) {
239 $mform->setDefault('grade_' . $param['id'], $param['grade']);
244 * Add appropriate criteria elements
246 * @param stdClass $data details of various criteria
248 public function config_form_criteria($data) {
250 $agg = $data->get_aggregation_methods();
252 $editurl = new moodle_url('/badges/criteria_settings.php',
253 array('badgeid' => $this->badgeid
, 'edit' => true, 'type' => $this->criteriatype
, 'crit' => $this->id
));
254 $deleteurl = new moodle_url('/badges/criteria_action.php',
255 array('badgeid' => $this->badgeid
, 'delete' => true, 'type' => $this->criteriatype
));
256 $editaction = $OUTPUT->action_icon($editurl, new pix_icon('t/edit', get_string('edit')), null, array('class' => 'criteria-action'));
257 $deleteaction = $OUTPUT->action_icon($deleteurl, new pix_icon('t/delete', get_string('delete')), null, array('class' => 'criteria-action'));
259 echo $OUTPUT->box_start();
260 if (!$data->is_locked() && !$data->is_active()) {
261 echo $OUTPUT->box($deleteaction . $editaction, array('criteria-header'));
263 echo $OUTPUT->heading($this->get_title() . $OUTPUT->help_icon('criteria_' . $this->criteriatype
, 'badges'), 3, 'main help');
265 if (!empty($this->description
)) {
266 $badge = new badge($this->badgeid
);
268 format_text($this->description
, $this->descriptionformat
, array('context' => $badge->get_context())),
269 'criteria-description'
273 if (!empty($this->params
)) {
274 if (count($this->params
) > 1) {
275 echo $OUTPUT->box(get_string('criteria_descr_' . $this->criteriatype
, 'badges',
276 core_text
::strtoupper($agg[$data->get_aggregation_method($this->criteriatype
)])), array('clearfix'));
278 echo $OUTPUT->box(get_string('criteria_descr_single_' . $this->criteriatype
, 'badges'), array('clearfix'));
280 echo $OUTPUT->box($this->get_details(), array('clearfix'));
282 echo $OUTPUT->box_end();
286 * Review this criteria and decide if the user has completed
288 * @param int $userid User whose criteria completion needs to be reviewed.
289 * @param bool $filtered An additional parameter indicating that user list
290 * has been reduced and some expensive checks can be skipped.
292 * @return bool Whether criteria is complete
294 abstract public function review($userid, $filtered = false);
297 * Returns array with sql code and parameters returning all ids
298 * of users who meet this particular criterion.
300 * @return array list($join, $where, $params)
302 abstract public function get_completed_criteria_sql();
305 * Mark this criteria as complete for a user
307 * @param int $userid User whose criteria is completed.
309 public function mark_complete($userid) {
312 $obj['critid'] = $this->id
;
313 $obj['userid'] = $userid;
314 $obj['datemet'] = time();
315 if (!$DB->record_exists('badge_criteria_met', array('critid' => $this->id
, 'userid' => $userid))) {
316 $DB->insert_record('badge_criteria_met', $obj);
321 * Return criteria parameters
323 * @param int $critid Criterion ID
326 public function get_params($cid) {
330 $records = $DB->get_records('badge_criteria_param', array('critid' => $cid));
331 foreach ($records as $rec) {
332 $arr = explode('_', $rec->name
);
333 $params[$arr[1]][$arr[0]] = $rec->value
;
340 * Delete this criterion
343 public function delete() {
346 // Remove any records if it has already been met.
347 $DB->delete_records('badge_criteria_met', array('critid' => $this->id
));
349 // Remove all parameters records.
350 $DB->delete_records('badge_criteria_param', array('critid' => $this->id
));
352 // Finally remove criterion itself.
353 $DB->delete_records('badge_criteria', array('id' => $this->id
));
355 // Trigger event, badge criteria deleted.
356 $eventparams = array('objectid' => $this->id
,
357 'context' => $PAGE->context
,
358 'other' => array('badgeid' => $this->badgeid
));
359 $event = \core\event\badge_criteria_deleted
::create($eventparams);
364 * Saves intial criteria records with required parameters set up.
366 * @param array $params Values from the form or any other array.
368 public function save($params = array()) {
371 // Figure out criteria description.
372 // If it is coming from the form editor, it is an array(text, format).
374 $descriptionformat = FORMAT_HTML
;
375 if (isset($params['description']['text'])) {
376 $description = $params['description']['text'];
377 $descriptionformat = $params['description']['format'];
378 } else if (isset($params['description'])) {
379 $description = $params['description'];
382 $fordb = new stdClass();
383 $fordb->criteriatype
= $this->criteriatype
;
384 $fordb->method
= isset($params['agg']) ?
$params['agg'] : BADGE_CRITERIA_AGGREGATION_ALL
;
385 $fordb->badgeid
= $this->badgeid
;
386 $fordb->description
= $description;
387 $fordb->descriptionformat
= $descriptionformat;
388 $t = $DB->start_delegated_transaction();
390 // Pick only params that are required by this criterion.
391 // Filter out empty values first.
392 $params = array_filter($params);
393 // Find out which param matches optional and required ones.
394 $match = array_merge($this->optional_params
, array($this->required_param
));
395 $regex = implode('|', array_map(function($a) {
398 $requiredkeys = preg_grep('/^(' . $regex . ').*$/', array_keys($params));
400 if ($this->id
!== 0) {
403 // Update criteria before doing anything with parameters.
405 $DB->update_record('badge_criteria', $fordb, true);
407 // Trigger event: badge_criteria_updated.
408 $eventparams = array('objectid' => $this->id
,
409 'context' => $PAGE->context
,
410 'other' => array('badgeid' => $this->badgeid
));
411 $event = \core\event\badge_criteria_updated
::create($eventparams);
414 $existing = $DB->get_fieldset_select('badge_criteria_param', 'name', 'critid = ?', array($cid));
415 $todelete = array_diff($existing, $requiredkeys);
417 if (!empty($todelete)) {
418 // A workaround to add some disabled elements that are still being submitted from the form.
419 foreach ($todelete as $del) {
420 $name = explode('_', $del);
421 if ($name[0] == $this->required_param
) {
422 foreach ($this->optional_params
as $opt) {
423 $todelete[] = $opt . '_' . $name[1];
427 $todelete = array_unique($todelete);
428 list($sql, $sqlparams) = $DB->get_in_or_equal($todelete, SQL_PARAMS_NAMED
, 'd', true);
429 $sqlparams = array_merge(array('critid' => $cid), $sqlparams);
430 $DB->delete_records_select('badge_criteria_param', 'critid = :critid AND name ' . $sql, $sqlparams);
433 foreach ($requiredkeys as $key) {
434 if (in_array($key, $existing)) {
435 $updp = $DB->get_record('badge_criteria_param', array('name' => $key, 'critid' => $cid));
436 $updp->value
= $params[$key];
437 $DB->update_record('badge_criteria_param', $updp, true);
439 $newp = new stdClass();
440 $newp->critid
= $cid;
442 $newp->value
= $params[$key];
443 $DB->insert_record('badge_criteria_param', $newp);
447 $cid = $DB->insert_record('badge_criteria', $fordb, true);
449 foreach ($requiredkeys as $key) {
450 $newp = new stdClass();
451 $newp->critid
= $cid;
453 $newp->value
= $params[$key];
454 $DB->insert_record('badge_criteria_param', $newp, false, true);
457 // Trigger event: badge_criteria_created.
458 $eventparams = array('objectid' => $this->id
,
459 'context' => $PAGE->context
,
460 'other' => array('badgeid' => $this->badgeid
));
461 $event = \core\event\badge_criteria_created
::create($eventparams);
468 * Saves intial criteria records with required parameters set up.
470 public function make_clone($newbadgeid) {
473 $fordb = new stdClass();
474 $fordb->criteriatype
= $this->criteriatype
;
475 $fordb->method
= $this->method
;
476 $fordb->badgeid
= $newbadgeid;
477 $fordb->description
= $this->description
;
478 $fordb->descriptionformat
= $this->descriptionformat
;
479 if (($newcrit = $DB->insert_record('badge_criteria', $fordb, true)) && isset($this->params
)) {
480 foreach ($this->params
as $k => $param) {
481 foreach ($param as $key => $value) {
482 $paramdb = new stdClass();
483 $paramdb->critid
= $newcrit;
484 $paramdb->name
= $key . '_' . $k;
485 $paramdb->value
= $value;
486 $DB->insert_record('badge_criteria_param', $paramdb);
493 * Allow some specific criteria types to be disabled based on config.
497 public static function is_enabled() {