badges/lib/awardlib.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/>.
  16
  17 /**
  18  * Classes to manage manual badge award.
  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  */
  26
  27 defined('MOODLE_INTERNAL') || die();
  28
  29 require_once($CFG->libdir . '/badgeslib.php');
  30 require_once($CFG->dirroot . '/user/selector/lib.php');
  31
  32 abstract class badge_award_selector_base extends user_selector_base {
  33
  34     /**
  35      * The id of the badge this selector is being used for
  36      * @var int
  37      */
  38     protected $badgeid = null;
  39     /**
  40      * The context of the badge this selector is being used for
  41      * @var object
  42      */
  43     protected $context = null;
  44     /**
  45      * The id of the role of badge issuer in current context
  46      * @var int
  47      */
  48     protected $issuerrole = null;
  49     /**
  50      * The id of badge issuer
  51      * @var int
  52      */
  53     protected $issuerid = null;
  54
  55     /**
  56      * Constructor method
  57      * @param string $name
  58      * @param array $options
  59      */
  60     public function __construct($name, array $options) {
  61         $options['accesscontext'] = $options['context'];
  62         parent::__construct($name, $options);
  63         if (isset($options['context'])) {
  64             if ($options['context'] instanceof context_system) {
  65                 // If it is a site badge, we need to get context of frontpage.
  66                 $this->context = context_course::instance(SITEID);
  67             } else {
  68                 $this->context = $options['context'];
  69             }
  70         }
  71         if (isset($options['badgeid'])) {
  72             $this->badgeid = $options['badgeid'];
  73         }
  74         if (isset($options['issuerid'])) {
  75             $this->issuerid = $options['issuerid'];
  76         }
  77         if (isset($options['issuerrole'])) {
  78             $this->issuerrole = $options['issuerrole'];
  79         }
  80     }
  81
  82     /**
  83      * Returns an array of options to seralise and store for searches
  84      *
  85      * @return array
  86      */
  87     protected function get_options() {
  88         global $CFG;
  89         $options = parent::get_options();
  90         $options['file'] =  'badges/lib/awardlib.php';
  91         $options['context'] = $this->context;
  92         $options['badgeid'] = $this->badgeid;
  93         $options['issuerid'] = $this->issuerid;
  94         $options['issuerrole'] = $this->issuerrole;
  95         return $options;
  96     }
  97 }
  98
  99 /**
 100  * A user selector control for potential users to award badge
 101  */
 102 class badge_potential_users_selector extends badge_award_selector_base {
 103     const MAX_USERS_PER_PAGE = 100;
 104
 105     /**
 106      * Existing recipients
 107      */
 108     protected $existingrecipients = array();
 109
 110     /**
 111      * Finds all potential badge recipients
 112      *
 113      * Potential badge recipients are all enroled users
 114      * who haven't got a badge from current issuer role.
 115      *
 116      * @param string $search
 117      * @return array
 118      */
 119     public function find_users($search) {
 120         global $DB;
 121
 122         $whereconditions = array();
 123         list($wherecondition, $params) = $this->search_sql($search, 'u');
 124         if ($wherecondition) {
 125             $whereconditions[] = $wherecondition;
 126         }
 127
 128         $existingids = array();
 129         foreach ($this->existingrecipients as $group) {
 130             foreach ($group as $user) {
 131                 $existingids[] = $user->id;
 132             }
 133         }
 134         if ($existingids) {
 135             list($usertest, $userparams) = $DB->get_in_or_equal($existingids, SQL_PARAMS_NAMED, 'ex', false);
 136             $whereconditions[] = 'u.id ' . $usertest;
 137             $params = array_merge($params, $userparams);
 138         }
 139
 140         if ($whereconditions) {
 141             $wherecondition = ' WHERE ' . implode(' AND ', $whereconditions);
 142         }
 143
 144         list($esql, $eparams) = get_enrolled_sql($this->context, 'moodle/badges:earnbadge', 0, true);
 145         $params = array_merge($params, $eparams);
 146
 147         $fields      = 'SELECT ' . $this->required_fields_sql('u');
 148         $countfields = 'SELECT COUNT(u.id)';
 149
 150         $params['badgeid'] = $this->badgeid;
 151         $params['issuerrole'] = $this->issuerrole;
 152
 153         $sql = " FROM {user} u JOIN ($esql) je ON je.id = u.id
 154                  LEFT JOIN {badge_manual_award} bm
 155                      ON (bm.recipientid = u.id AND bm.badgeid = :badgeid AND bm.issuerrole = :issuerrole)
 156                  $wherecondition AND bm.id IS NULL";
 157
 158         list($sort, $sortparams) = users_order_by_sql('u', $search, $this->accesscontext);
 159         $order = ' ORDER BY ' . $sort;
 160
 161         if (!$this->is_validating()) {
 162             $potentialmemberscount = $DB->count_records_sql($countfields . $sql, $params);
 163             if ($potentialmemberscount > self::MAX_USERS_PER_PAGE) {
 164                 return $this->too_many_results($search, $potentialmemberscount);
 165             }
 166         }
 167
 168         $availableusers = $DB->get_records_sql($fields . $sql . $order, array_merge($params, $sortparams));
 169
 170         if (empty($availableusers)) {
 171             return array();
 172         }
 173
 174         return array(get_string('potentialrecipients', 'badges') => $availableusers);
 175     }
 176
 177     /**
 178      * Sets the existing recipients
 179      * @param array $users
 180      */
 181     public function set_existing_recipients(array $users) {
 182         $this->existingrecipients = $users;
 183     }
 184 }
 185
 186 /**
 187  * A user selector control for existing users to award badge
 188  */
 189 class badge_existing_users_selector extends badge_award_selector_base {
 190
 191     /**
 192      * Finds all users who already have been awarded a badge by current role
 193      *
 194      * @param string $search
 195      * @return array
 196      */
 197     public function find_users($search) {
 198         global $DB;
 199         list($wherecondition, $params) = $this->search_sql($search, 'u');
 200         $params['badgeid'] = $this->badgeid;
 201         $params['issuerrole'] = $this->issuerrole;
 202
 203         list($esql, $eparams) = get_enrolled_sql($this->context, 'moodle/badges:earnbadge', 0, true);
 204         $fields = $this->required_fields_sql('u');
 205         list($sort, $sortparams) = users_order_by_sql('u', $search, $this->accesscontext);
 206
 207         $params = array_merge($params, $eparams, $sortparams);
 208         $recipients = $DB->get_records_sql("SELECT $fields
 209                 FROM {user} u
 210                 JOIN ($esql) je ON je.id = u.id
 211                 JOIN {badge_manual_award} s ON s.recipientid = u.id
 212                 WHERE $wherecondition AND s.badgeid = :badgeid AND s.issuerrole = :issuerrole
 213                 ORDER BY $sort", $params);
 214
 215         return array(get_string('existingrecipients', 'badges') => $recipients);
 216     }
 217 }
 218
 219 function process_manual_award($recipientid, $issuerid, $issuerrole, $badgeid) {
 220     global $DB;
 221     $params = array(
 222                 'badgeid' => $badgeid,
 223                 'issuerid' => $issuerid,
 224                 'issuerrole' => $issuerrole,
 225                 'recipientid' => $recipientid
 226             );
 227
 228     if (!$DB->record_exists('badge_manual_award', $params)) {
 229         $award = new stdClass();
 230         $award->badgeid = $badgeid;
 231         $award->issuerid = $issuerid;
 232         $award->issuerrole = $issuerrole;
 233         $award->recipientid = $recipientid;
 234         $award->datemet = time();
 235         if ($DB->insert_record('badge_manual_award', $award)) {
 236             return true;
 237         }
 238     }
 239     return false;
 240 }
 241
 242 /**
 243  * Manually revoke awarded badges.
 244  *
 245  * @param int $recipientid
 246  * @param int $issuerid
 247  * @param int $issuerrole
 248  * @param int $badgeid
 249  * @return bool
 250  */
 251 function process_manual_revoke($recipientid, $issuerid, $issuerrole, $badgeid) {
 252     global $DB;
 253     $params = array(
 254                 'badgeid' => $badgeid,
 255                 'issuerid' => $issuerid,
 256                 'issuerrole' => $issuerrole,
 257                 'recipientid' => $recipientid
 258             );
 259     if ($DB->record_exists('badge_manual_award', $params)) {
 260         if ($DB->delete_records('badge_manual_award', array('badgeid' => $badgeid,
 261                                                             'issuerid' => $issuerid,
 262                                                             'recipientid' => $recipientid))
 263             && $DB->delete_records('badge_issued', array('badgeid' => $badgeid,
 264                                                       'userid' => $recipientid))) {
 265
 266             // Trigger event, badge revoked.
 267             $badge = new \badge($badgeid);
 268             $eventparams = array(
 269                 'objectid' => $badgeid,
 270                 'relateduserid' => $recipientid,
 271                 'context' => $badge->get_context()
 272             );
 273             $event = \core\event\badge_revoked::create($eventparams);
 274             $event->trigger();
 275
 276             return true;
 277         }
 278     } else {
 279         throw new moodle_exception('error:badgenotfound', 'badges');
 280     }
 281     return false;
 282 }