[Summary view] [Print] [Text view]

   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   * 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 <[email protected]>
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die();
  28  
  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);
  34  
  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);
  40  
  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);
  46  
  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);
  52  
  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);
  58  
  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);
  64  
  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);
  70  
  71  /*
  72   * Criteria type constant to class name mapping
  73   */
  74  global $BADGE_CRITERIA_TYPES;
  75  $BADGE_CRITERIA_TYPES = array(
  76      BADGE_CRITERIA_TYPE_OVERALL   => 'overall',
  77      BADGE_CRITERIA_TYPE_ACTIVITY  => 'activity',
  78      BADGE_CRITERIA_TYPE_MANUAL    => 'manual',
  79      BADGE_CRITERIA_TYPE_SOCIAL    => 'social',
  80      BADGE_CRITERIA_TYPE_COURSE    => 'course',
  81      BADGE_CRITERIA_TYPE_COURSESET => 'courseset',
  82      BADGE_CRITERIA_TYPE_PROFILE   => 'profile'
  83  );
  84  
  85  /**
  86   * Award criteria abstract definition
  87   *
  88   */
  89  abstract class award_criteria {
  90  
  91      public $id;
  92      public $method;
  93      public $badgeid;
  94      public $params = array();
  95  
  96      /**
  97       * The base constructor
  98       *
  99       * @param array $params
 100       */
 101      public function __construct($params) {
 102          $this->id = isset($params['id']) ? $params['id'] : 0;
 103          $this->method = isset($params['method']) ? $params['method'] : BADGE_CRITERIA_AGGREGATION_ANY;
 104          $this->badgeid = $params['badgeid'];
 105          if (isset($params['id'])) {
 106              $this->params = $this->get_params($params['id']);
 107          }
 108      }
 109  
 110      /**
 111       * Factory method for creating criteria class object
 112       *
 113       * @param array $params associative arrays varname => value
 114       * @return award_criteria
 115       */
 116      public static function build($params) {
 117          global $CFG, $BADGE_CRITERIA_TYPES;
 118  
 119          if (!isset($params['criteriatype']) || !isset($BADGE_CRITERIA_TYPES[$params['criteriatype']])) {
 120              print_error('error:invalidcriteriatype', 'badges');
 121          }
 122  
 123          $class = 'award_criteria_' . $BADGE_CRITERIA_TYPES[$params['criteriatype']];
 124          require_once($CFG->dirroot . '/badges/criteria/' . $class . '.php');
 125  
 126          return new $class($params);
 127      }
 128  
 129      /**
 130       * Return criteria title
 131       *
 132       * @return string
 133       */
 134      public function get_title() {
 135          return get_string('criteria_' . $this->criteriatype, 'badges');
 136      }
 137  
 138      /**
 139       * Get criteria details for displaying to users
 140       *
 141       * @param string $short Print short version of criteria
 142       * @return string
 143       */
 144      abstract public function get_details($short = '');
 145  
 146      /**
 147       * Add appropriate criteria options to the form
 148       *
 149       */
 150      abstract public function get_options(&$mform);
 151  
 152      /**
 153       * Add appropriate parameter elements to the criteria form
 154       *
 155       */
 156      public function config_options(&$mform, $param) {
 157          global $OUTPUT;
 158          $prefix = $this->required_param . '_';
 159  
 160          if ($param['error']) {
 161              $parameter[] =& $mform->createElement('advcheckbox', $prefix . $param['id'], '',
 162                      $OUTPUT->error_text($param['name']), null, array(0, $param['id']));
 163              $mform->addGroup($parameter, 'param_' . $prefix . $param['id'], '', array(' '), false);
 164          } else {
 165              $parameter[] =& $mform->createElement('advcheckbox', $prefix . $param['id'], '', $param['name'], null, array(0, $param['id']));
 166              $parameter[] =& $mform->createElement('static', 'break_start_' . $param['id'], null, '<div style="margin-left: 3em;">');
 167  
 168              if (in_array('grade', $this->optional_params)) {
 169                  $parameter[] =& $mform->createElement('static', 'mgrade_' . $param['id'], null, get_string('mingrade', 'badges'));
 170                  $parameter[] =& $mform->createElement('text', 'grade_' . $param['id'], '', array('size' => '5'));
 171                  $mform->setType('grade_' . $param['id'], PARAM_INT);
 172              }
 173  
 174              if (in_array('bydate', $this->optional_params)) {
 175                  $parameter[] =& $mform->createElement('static', 'complby_' . $param['id'], null, get_string('bydate', 'badges'));
 176                  $parameter[] =& $mform->createElement('date_selector', 'bydate_' . $param['id'], "", array('optional' => true));
 177              }
 178  
 179              $parameter[] =& $mform->createElement('static', 'break_end_' . $param['id'], null, '</div>');
 180              $mform->addGroup($parameter, 'param_' . $prefix . $param['id'], '', array(' '), false);
 181              if (in_array('grade', $this->optional_params)) {
 182                  $mform->addGroupRule('param_' . $prefix . $param['id'], array(
 183                      'grade_' . $param['id'] => array(array(get_string('err_numeric', 'form'), 'numeric', '', 'client'))));
 184              }
 185              $mform->disabledIf('bydate_' . $param['id'] . '[day]', 'bydate_' . $param['id'] . '[enabled]', 'notchecked');
 186              $mform->disabledIf('bydate_' . $param['id'] . '[month]', 'bydate_' . $param['id'] . '[enabled]', 'notchecked');
 187              $mform->disabledIf('bydate_' . $param['id'] . '[year]', 'bydate_' . $param['id'] . '[enabled]', 'notchecked');
 188              $mform->disabledIf('param_' . $prefix . $param['id'], $prefix . $param['id'], 'notchecked');
 189          }
 190  
 191          // Set default values.
 192          $mform->setDefault($prefix . $param['id'], $param['checked']);
 193          if (isset($param['bydate'])) {
 194              $mform->setDefault('bydate_' . $param['id'], $param['bydate']);
 195          }
 196          if (isset($param['grade'])) {
 197              $mform->setDefault('grade_' . $param['id'], $param['grade']);
 198          }
 199      }
 200  
 201      /**
 202       * Add appropriate criteria elements
 203       *
 204       * @param stdClass $data details of various criteria
 205       */
 206      public function config_form_criteria($data) {
 207          global $OUTPUT;
 208          $agg = $data->get_aggregation_methods();
 209  
 210          $editurl = new moodle_url('/badges/criteria_settings.php',
 211                  array('badgeid' => $this->badgeid, 'edit' => true, 'type' => $this->criteriatype, 'crit' => $this->id));
 212          $deleteurl = new moodle_url('/badges/criteria_action.php',
 213                  array('badgeid' => $this->badgeid, 'delete' => true, 'type' => $this->criteriatype));
 214          $editaction = $OUTPUT->action_icon($editurl, new pix_icon('t/edit', get_string('edit')), null, array('class' => 'criteria-action'));
 215          $deleteaction = $OUTPUT->action_icon($deleteurl, new pix_icon('t/delete', get_string('delete')), null, array('class' => 'criteria-action'));
 216  
 217          echo $OUTPUT->box_start();
 218          if (!$data->is_locked() && !$data->is_active()) {
 219              echo $OUTPUT->box($deleteaction . $editaction, array('criteria-header'));
 220          }
 221          echo $OUTPUT->heading($this->get_title() . $OUTPUT->help_icon('criteria_' . $this->criteriatype, 'badges'), 3, 'main help');
 222  
 223          if (!empty($this->params)) {
 224              if (count($this->params) > 1) {
 225                  echo $OUTPUT->box(get_string('criteria_descr_' . $this->criteriatype, 'badges',
 226                          core_text::strtoupper($agg[$data->get_aggregation_method($this->criteriatype)])), array('clearfix'));
 227              } else {
 228                  echo $OUTPUT->box(get_string('criteria_descr_single_' . $this->criteriatype , 'badges'), array('clearfix'));
 229              }
 230              echo $OUTPUT->box($this->get_details(), array('clearfix'));
 231          }
 232          echo $OUTPUT->box_end();
 233      }
 234  
 235      /**
 236       * Review this criteria and decide if the user has completed
 237       *
 238       * @param int $userid User whose criteria completion needs to be reviewed.
 239       * @param bool $filtered An additional parameter indicating that user list
 240       *        has been reduced and some expensive checks can be skipped.
 241       *
 242       * @return bool Whether criteria is complete
 243       */
 244      abstract public function review($userid, $filtered = false);
 245  
 246      /**
 247       * Returns array with sql code and parameters returning all ids
 248       * of users who meet this particular criterion.
 249       *
 250       * @return array list($join, $where, $params)
 251       */
 252      abstract public function get_completed_criteria_sql();
 253  
 254      /**
 255       * Mark this criteria as complete for a user
 256       *
 257       * @param int $userid User whose criteria is completed.
 258       */
 259      public function mark_complete($userid) {
 260          global $DB;
 261          $obj = array();
 262          $obj['critid'] = $this->id;
 263          $obj['userid'] = $userid;
 264          $obj['datemet'] = time();
 265          if (!$DB->record_exists('badge_criteria_met', array('critid' => $this->id, 'userid' => $userid))) {
 266              $DB->insert_record('badge_criteria_met', $obj);
 267          }
 268      }
 269  
 270      /**
 271       * Return criteria parameters
 272       *
 273       * @param int $critid Criterion ID
 274       * @return array
 275       */
 276      public function get_params($cid) {
 277          global $DB;
 278          $params = array();
 279  
 280          $records = $DB->get_records('badge_criteria_param', array('critid' => $cid));
 281          foreach ($records as $rec) {
 282              $arr = explode('_', $rec->name);
 283              $params[$arr[1]][$arr[0]] = $rec->value;
 284          }
 285  
 286          return $params;
 287      }
 288  
 289      /**
 290       * Delete this criterion
 291       *
 292       */
 293      public function delete() {
 294          global $DB;
 295  
 296          // Remove any records if it has already been met.
 297          $DB->delete_records('badge_criteria_met', array('critid' => $this->id));
 298  
 299          // Remove all parameters records.
 300          $DB->delete_records('badge_criteria_param', array('critid' => $this->id));
 301  
 302          // Finally remove criterion itself.
 303          $DB->delete_records('badge_criteria', array('id' => $this->id));
 304      }
 305  
 306      /**
 307       * Saves intial criteria records with required parameters set up.
 308       */
 309      public function save($params = array()) {
 310          global $DB;
 311          $fordb = new stdClass();
 312          $fordb->criteriatype = $this->criteriatype;
 313          $fordb->method = isset($params->agg) ? $params->agg : $params['agg'];
 314          $fordb->badgeid = $this->badgeid;
 315          $t = $DB->start_delegated_transaction();
 316  
 317          // Unset unnecessary parameters supplied with form.
 318          if (isset($params->agg)) {
 319              unset($params->agg);
 320          } else {
 321              unset($params['agg']);
 322          }
 323          unset($params->submitbutton);
 324          $params = array_filter((array)$params);
 325  
 326          if ($this->id !== 0) {
 327              $cid = $this->id;
 328  
 329              // Update criteria before doing anything with parameters.
 330              $fordb->id = $cid;
 331              $DB->update_record('badge_criteria', $fordb, true);
 332  
 333              $existing = $DB->get_fieldset_select('badge_criteria_param', 'name', 'critid = ?', array($cid));
 334              $todelete = array_diff($existing, array_keys($params));
 335  
 336              if (!empty($todelete)) {
 337                  // A workaround to add some disabled elements that are still being submitted from the form.
 338                  foreach ($todelete as $del) {
 339                      $name = explode('_', $del);
 340                      if ($name[0] == $this->required_param) {
 341                          foreach ($this->optional_params as $opt) {
 342                              $todelete[] = $opt . '_' . $name[1];
 343                          }
 344                      }
 345                  }
 346                  $todelete = array_unique($todelete);
 347                  list($sql, $sqlparams) = $DB->get_in_or_equal($todelete, SQL_PARAMS_NAMED, 'd', true);
 348                  $sqlparams = array_merge(array('critid' => $cid), $sqlparams);
 349                  $DB->delete_records_select('badge_criteria_param', 'critid = :critid AND name ' . $sql, $sqlparams);
 350              }
 351  
 352              foreach ($params as $key => $value) {
 353                  if (in_array($key, $existing)) {
 354                      $updp = $DB->get_record('badge_criteria_param', array('name' => $key, 'critid' => $cid));
 355                      $updp->value = $value;
 356                      $DB->update_record('badge_criteria_param', $updp, true);
 357                  } else {
 358                      $newp = new stdClass();
 359                      $newp->critid = $cid;
 360                      $newp->name = $key;
 361                      $newp->value = $value;
 362                      $DB->insert_record('badge_criteria_param', $newp);
 363                  }
 364              }
 365          } else {
 366              $cid = $DB->insert_record('badge_criteria', $fordb, true);
 367              if ($cid) {
 368                  foreach ($params as $key => $value) {
 369                      $newp = new stdClass();
 370                      $newp->critid = $cid;
 371                      $newp->name = $key;
 372                      $newp->value = $value;
 373                      $DB->insert_record('badge_criteria_param', $newp, false, true);
 374                  }
 375              }
 376           }
 377           $t->allow_commit();
 378      }
 379  
 380      /**
 381       * Saves intial criteria records with required parameters set up.
 382       */
 383      public function make_clone($newbadgeid) {
 384          global $DB;
 385  
 386          $fordb = new stdClass();
 387          $fordb->criteriatype = $this->criteriatype;
 388          $fordb->method = $this->method;
 389          $fordb->badgeid = $newbadgeid;
 390          if (($newcrit = $DB->insert_record('badge_criteria', $fordb, true)) && isset($this->params)) {
 391              foreach ($this->params as $k => $param) {
 392                  foreach ($param as $key => $value) {
 393                      $paramdb = new stdClass();
 394                      $paramdb->critid = $newcrit;
 395                      $paramdb->name = $key . '_' . $k;
 396                      $paramdb->value = $value;
 397                      $DB->insert_record('badge_criteria_param', $paramdb);
 398                  }
 399              }
 400          }
 401      }
 402  }