MDL-55491 badges: Add cohort as badge criteria
[moodle.git] / badges / criteria / award_criteria.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/>.
17 /**
18  * Badge award criteria
19  *
20  * @package    core
21  * @subpackage badges
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>
25  */
27 defined('MOODLE_INTERNAL') || die();
29 /*
30  * Role completion criteria type
31  * Criteria type constant, primarily for storing criteria type in the database.
32  */
33 define('BADGE_CRITERIA_TYPE_OVERALL', 0);
35 /*
36  * Activity completion criteria type
37  * Criteria type constant, primarily for storing criteria type in the database.
38  */
39 define('BADGE_CRITERIA_TYPE_ACTIVITY', 1);
41 /*
42  * Duration completion criteria type
43  * Criteria type constant, primarily for storing criteria type in the database.
44  */
45 define('BADGE_CRITERIA_TYPE_MANUAL', 2);
47 /*
48  * Grade completion criteria type
49  * Criteria type constant, primarily for storing criteria type in the database.
50  */
51 define('BADGE_CRITERIA_TYPE_SOCIAL', 3);
53 /*
54  * Course completion criteria type
55  * Criteria type constant, primarily for storing criteria type in the database.
56 */
57 define('BADGE_CRITERIA_TYPE_COURSE', 4);
59 /*
60  * Courseset completion criteria type
61  * Criteria type constant, primarily for storing criteria type in the database.
62  */
63 define('BADGE_CRITERIA_TYPE_COURSESET', 5);
65 /*
66  * Course completion criteria type
67  * Criteria type constant, primarily for storing criteria type in the database.
68  */
69 define('BADGE_CRITERIA_TYPE_PROFILE', 6);
71 /*
72  * Badge completion criteria type
73  * Criteria type constant, primarily for storing criteria type in the database.
74  */
75 define('BADGE_CRITERIA_TYPE_BADGE', 7);
77 /*
78  * Cohort criteria type
79  * Criteria type constant, primarily for storing criteria type in the database.
80  */
81 define('BADGE_CRITERIA_TYPE_COHORT', 98);
83 /*
84  * Criteria type constant to class name mapping
85  */
86 global $BADGE_CRITERIA_TYPES;
87 $BADGE_CRITERIA_TYPES = array(
88     BADGE_CRITERIA_TYPE_OVERALL   => 'overall',
89     BADGE_CRITERIA_TYPE_ACTIVITY  => 'activity',
90     BADGE_CRITERIA_TYPE_MANUAL    => 'manual',
91     BADGE_CRITERIA_TYPE_SOCIAL    => 'social',
92     BADGE_CRITERIA_TYPE_COURSE    => 'course',
93     BADGE_CRITERIA_TYPE_COURSESET => 'courseset',
94     BADGE_CRITERIA_TYPE_PROFILE   => 'profile',
95     BADGE_CRITERIA_TYPE_BADGE     => 'badge',
96     BADGE_CRITERIA_TYPE_COHORT    => 'cohort',
97 );
99 /**
100  * Award criteria abstract definition
101  *
102  */
103 abstract class award_criteria {
105     /**
106      * ID of the criterion.
107      * @var integer
108      */
109     public $id;
111     /**
112      * Aggregation method [BADGE_CRITERIA_AGGREGATION_ANY, BADGE_CRITERIA_AGGREGATION_ALL].
113      * @var integer
114      */
115     public $method;
117     /**
118      * ID of a badge this criterion belongs to.
119      * @var integer
120      */
121     public $badgeid;
123     /**
124      * Criterion HTML/plain text description.
125      * @var string
126      */
127     public $description;
129     /**
130      * Format of the criterion description.
131      * @var integer
132      */
133     public $descriptionformat;
135     /**
136      * Any additional parameters.
137      * @var array
138      */
139     public $params = array();
141     /**
142      * The base constructor
143      *
144      * @param array $params
145      */
146     public function __construct($params) {
147         $this->id = isset($params['id']) ? $params['id'] : 0;
148         $this->method = isset($params['method']) ? $params['method'] : BADGE_CRITERIA_AGGREGATION_ANY;
149         $this->badgeid = $params['badgeid'];
150         $this->description = isset($params['description']) ? $params['description'] : '';
151         $this->descriptionformat = isset($params['descriptionformat']) ? $params['descriptionformat'] : FORMAT_HTML;
152         if (isset($params['id'])) {
153             $this->params = $this->get_params($params['id']);
154         }
155     }
157     /**
158      * Factory method for creating criteria class object
159      *
160      * @param array $params associative arrays varname => value
161      * @return award_criteria
162      */
163     public static function build($params) {
164         global $CFG, $BADGE_CRITERIA_TYPES;
166         if (!isset($params['criteriatype']) || !isset($BADGE_CRITERIA_TYPES[$params['criteriatype']])) {
167             print_error('error:invalidcriteriatype', 'badges');
168         }
170         $class = 'award_criteria_' . $BADGE_CRITERIA_TYPES[$params['criteriatype']];
171         require_once($CFG->dirroot . '/badges/criteria/' . $class . '.php');
173         return new $class($params);
174     }
176     /**
177      * Return criteria title
178      *
179      * @return string
180      */
181     public function get_title() {
182         return get_string('criteria_' . $this->criteriatype, 'badges');
183     }
185     /**
186      * Get criteria details for displaying to users
187      *
188      * @param string $short Print short version of criteria
189      * @return string
190      */
191     abstract public function get_details($short = '');
193     /**
194      * Add appropriate criteria options to the form
195      *
196      */
197     abstract public function get_options(&$mform);
199     /**
200      * Add appropriate parameter elements to the criteria form
201      *
202      */
203     public function config_options(&$mform, $param) {
204         global $OUTPUT;
205         $prefix = $this->required_param . '_';
207         if ($param['error']) {
208             $parameter[] =& $mform->createElement('advcheckbox', $prefix . $param['id'], '',
209                     $OUTPUT->error_text($param['name']), null, array(0, $param['id']));
210             $mform->addGroup($parameter, 'param_' . $prefix . $param['id'], '', array(' '), false);
211         } else {
212             $parameter[] =& $mform->createElement('advcheckbox', $prefix . $param['id'], '', $param['name'], null, array(0, $param['id']));
213             $parameter[] =& $mform->createElement('static', 'break_start_' . $param['id'], null, '<div style="margin-left: 3em;">');
215             if (in_array('grade', $this->optional_params)) {
216                 $parameter[] =& $mform->createElement('static', 'mgrade_' . $param['id'], null, get_string('mingrade', 'badges'));
217                 $parameter[] =& $mform->createElement('text', 'grade_' . $param['id'], '', array('size' => '5'));
218                 $mform->setType('grade_' . $param['id'], PARAM_INT);
219             }
221             if (in_array('bydate', $this->optional_params)) {
222                 $parameter[] =& $mform->createElement('static', 'complby_' . $param['id'], null, get_string('bydate', 'badges'));
223                 $parameter[] =& $mform->createElement('date_selector', 'bydate_' . $param['id'], "", array('optional' => true));
224             }
226             $parameter[] =& $mform->createElement('static', 'break_end_' . $param['id'], null, '</div>');
227             $mform->addGroup($parameter, 'param_' . $prefix . $param['id'], '', array(' '), false);
228             if (in_array('grade', $this->optional_params)) {
229                 $mform->addGroupRule('param_' . $prefix . $param['id'], array(
230                     'grade_' . $param['id'] => array(array(get_string('err_numeric', 'form'), 'numeric', '', 'client'))));
231             }
232             $mform->disabledIf('bydate_' . $param['id'] . '[day]', 'bydate_' . $param['id'] . '[enabled]', 'notchecked');
233             $mform->disabledIf('bydate_' . $param['id'] . '[month]', 'bydate_' . $param['id'] . '[enabled]', 'notchecked');
234             $mform->disabledIf('bydate_' . $param['id'] . '[year]', 'bydate_' . $param['id'] . '[enabled]', 'notchecked');
235             $mform->disabledIf('param_' . $prefix . $param['id'], $prefix . $param['id'], 'notchecked');
236         }
238         // Set default values.
239         $mform->setDefault($prefix . $param['id'], $param['checked']);
240         if (isset($param['bydate'])) {
241             $mform->setDefault('bydate_' . $param['id'], $param['bydate']);
242         }
243         if (isset($param['grade'])) {
244             $mform->setDefault('grade_' . $param['id'], $param['grade']);
245         }
246     }
248     /**
249      * Add appropriate criteria elements
250      *
251      * @param stdClass $data details of various criteria
252      */
253     public function config_form_criteria($data) {
254         global $OUTPUT;
255         $agg = $data->get_aggregation_methods();
257         $editurl = new moodle_url('/badges/criteria_settings.php',
258                 array('badgeid' => $this->badgeid, 'edit' => true, 'type' => $this->criteriatype, 'crit' => $this->id));
259         $deleteurl = new moodle_url('/badges/criteria_action.php',
260                 array('badgeid' => $this->badgeid, 'delete' => true, 'type' => $this->criteriatype));
261         $editaction = $OUTPUT->action_icon($editurl, new pix_icon('t/edit', get_string('edit')), null, array('class' => 'criteria-action'));
262         $deleteaction = $OUTPUT->action_icon($deleteurl, new pix_icon('t/delete', get_string('delete')), null, array('class' => 'criteria-action'));
264         echo $OUTPUT->box_start();
265         if (!$data->is_locked() && !$data->is_active()) {
266             echo $OUTPUT->box($deleteaction . $editaction, array('criteria-header'));
267         }
268         echo $OUTPUT->heading($this->get_title() . $OUTPUT->help_icon('criteria_' . $this->criteriatype, 'badges'), 3, 'main help');
270         if (!empty($this->description)) {
271             $badge = new badge($this->badgeid);
272             echo $OUTPUT->box(
273                 format_text($this->description, $this->descriptionformat, array('context' => $badge->get_context())),
274                 'criteria-description'
275                 );
276         }
278         if (!empty($this->params)) {
279             if (count($this->params) > 1) {
280                 echo $OUTPUT->box(get_string('criteria_descr_' . $this->criteriatype, 'badges',
281                         core_text::strtoupper($agg[$data->get_aggregation_method($this->criteriatype)])), array('clearfix'));
282             } else {
283                 echo $OUTPUT->box(get_string('criteria_descr_single_' . $this->criteriatype , 'badges'), array('clearfix'));
284             }
285             echo $OUTPUT->box($this->get_details(), array('clearfix'));
286         }
287         echo $OUTPUT->box_end();
288     }
290     /**
291      * Review this criteria and decide if the user has completed
292      *
293      * @param int $userid User whose criteria completion needs to be reviewed.
294      * @param bool $filtered An additional parameter indicating that user list
295      *        has been reduced and some expensive checks can be skipped.
296      *
297      * @return bool Whether criteria is complete
298      */
299     abstract public function review($userid, $filtered = false);
301     /**
302      * Returns array with sql code and parameters returning all ids
303      * of users who meet this particular criterion.
304      *
305      * @return array list($join, $where, $params)
306      */
307     abstract public function get_completed_criteria_sql();
309     /**
310      * Mark this criteria as complete for a user
311      *
312      * @param int $userid User whose criteria is completed.
313      */
314     public function mark_complete($userid) {
315         global $DB;
316         $obj = array();
317         $obj['critid'] = $this->id;
318         $obj['userid'] = $userid;
319         $obj['datemet'] = time();
320         if (!$DB->record_exists('badge_criteria_met', array('critid' => $this->id, 'userid' => $userid))) {
321             $DB->insert_record('badge_criteria_met', $obj);
322         }
323     }
325     /**
326      * Return criteria parameters
327      *
328      * @param int $critid Criterion ID
329      * @return array
330      */
331     public function get_params($cid) {
332         global $DB;
333         $params = array();
335         $records = $DB->get_records('badge_criteria_param', array('critid' => $cid));
336         foreach ($records as $rec) {
337             $arr = explode('_', $rec->name);
338             $params[$arr[1]][$arr[0]] = $rec->value;
339         }
341         return $params;
342     }
344     /**
345      * Delete this criterion
346      *
347      */
348     public function delete() {
349         global $DB, $PAGE;
351         // Remove any records if it has already been met.
352         $DB->delete_records('badge_criteria_met', array('critid' => $this->id));
354         // Remove all parameters records.
355         $DB->delete_records('badge_criteria_param', array('critid' => $this->id));
357         // Finally remove criterion itself.
358         $DB->delete_records('badge_criteria', array('id' => $this->id));
360         // Trigger event, badge criteria deleted.
361         $eventparams = array('objectid' => $this->id,
362             'context' => $PAGE->context,
363             'other' => array('badgeid' => $this->badgeid));
364         $event = \core\event\badge_criteria_deleted::create($eventparams);
365         $event->trigger();
366     }
368     /**
369      * Saves intial criteria records with required parameters set up.
370      *
371      * @param array $params Values from the form or any other array.
372      */
373     public function save($params = array()) {
374         global $DB, $PAGE;
376         // Figure out criteria description.
377         // If it is coming from the form editor, it is an array(text, format).
378         $description = '';
379         $descriptionformat = FORMAT_HTML;
380         if (isset($params['description']['text'])) {
381             $description = $params['description']['text'];
382             $descriptionformat = $params['description']['format'];
383         } else if (isset($params['description'])) {
384             $description = $params['description'];
385         }
387         $fordb = new stdClass();
388         $fordb->criteriatype = $this->criteriatype;
389         $fordb->method = isset($params['agg']) ? $params['agg'] : BADGE_CRITERIA_AGGREGATION_ALL;
390         $fordb->badgeid = $this->badgeid;
391         $fordb->description = $description;
392         $fordb->descriptionformat = $descriptionformat;
393         $t = $DB->start_delegated_transaction();
395         // Pick only params that are required by this criterion.
396         // Filter out empty values first.
397         $params = array_filter($params);
398         // Find out which param matches optional and required ones.
399         $match = array_merge($this->optional_params, array($this->required_param));
400         $regex = implode('|', array_map(function($a) {
401             return $a . "_";
402         }, $match));
403         $requiredkeys = preg_grep('/^(' . $regex . ').*$/', array_keys($params));
405         if ($this->id !== 0) {
406             $cid = $this->id;
408             // Update criteria before doing anything with parameters.
409             $fordb->id = $cid;
410             $DB->update_record('badge_criteria', $fordb, true);
412             // Trigger event: badge_criteria_updated.
413             $eventparams = array('objectid' => $this->id,
414                 'context' => $PAGE->context,
415                 'other' => array('badgeid' => $this->badgeid));
416             $event = \core\event\badge_criteria_updated::create($eventparams);
417             $event->trigger();
419             $existing = $DB->get_fieldset_select('badge_criteria_param', 'name', 'critid = ?', array($cid));
420             $todelete = array_diff($existing, $requiredkeys);
422             if (!empty($todelete)) {
423                 // A workaround to add some disabled elements that are still being submitted from the form.
424                 foreach ($todelete as $del) {
425                     $name = explode('_', $del);
426                     if ($name[0] == $this->required_param) {
427                         foreach ($this->optional_params as $opt) {
428                             $todelete[] = $opt . '_' . $name[1];
429                         }
430                     }
431                 }
432                 $todelete = array_unique($todelete);
433                 list($sql, $sqlparams) = $DB->get_in_or_equal($todelete, SQL_PARAMS_NAMED, 'd', true);
434                 $sqlparams = array_merge(array('critid' => $cid), $sqlparams);
435                 $DB->delete_records_select('badge_criteria_param', 'critid = :critid AND name ' . $sql, $sqlparams);
436             }
438             foreach ($requiredkeys as $key) {
439                 if (in_array($key, $existing)) {
440                     $updp = $DB->get_record('badge_criteria_param', array('name' => $key, 'critid' => $cid));
441                     $updp->value = $params[$key];
442                     $DB->update_record('badge_criteria_param', $updp, true);
443                 } else {
444                     $newp = new stdClass();
445                     $newp->critid = $cid;
446                     $newp->name = $key;
447                     $newp->value = $params[$key];
448                     $DB->insert_record('badge_criteria_param', $newp);
449                 }
450             }
451         } else {
452             $cid = $DB->insert_record('badge_criteria', $fordb, true);
453             if ($cid) {
454                 foreach ($requiredkeys as $key) {
455                     $newp = new stdClass();
456                     $newp->critid = $cid;
457                     $newp->name = $key;
458                     $newp->value = $params[$key];
459                     $DB->insert_record('badge_criteria_param', $newp, false, true);
460                 }
461             }
462             // Trigger event: badge_criteria_created.
463             $eventparams = array('objectid' => $this->id,
464                 'context' => $PAGE->context,
465                 'other' => array('badgeid' => $this->badgeid));
466             $event = \core\event\badge_criteria_created::create($eventparams);
467             $event->trigger();
468         }
469         $t->allow_commit();
470     }
472     /**
473      * Saves intial criteria records with required parameters set up.
474      */
475     public function make_clone($newbadgeid) {
476         global $DB;
478         $fordb = new stdClass();
479         $fordb->criteriatype = $this->criteriatype;
480         $fordb->method = $this->method;
481         $fordb->badgeid = $newbadgeid;
482         $fordb->description = $this->description;
483         $fordb->descriptionformat = $this->descriptionformat;
484         if (($newcrit = $DB->insert_record('badge_criteria', $fordb, true)) && isset($this->params)) {
485             foreach ($this->params as $k => $param) {
486                 foreach ($param as $key => $value) {
487                     $paramdb = new stdClass();
488                     $paramdb->critid = $newcrit;
489                     $paramdb->name = $key . '_' . $k;
490                     $paramdb->value = $value;
491                     $DB->insert_record('badge_criteria_param', $paramdb);
492                 }
493             }
494         }
495     }