[Summary view]

Differences Between: [Versions 39 and 401] [Versions 39 and 402] [Versions 39 and 403]

   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   * Course completion criteria
  19   *
  20   * @package core_completion
  21   * @category completion
  22   * @copyright 2009 Catalyst IT Ltd
  23   * @author Aaron Barnes <aaronb@catalyst.net.nz>
  24   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die();
  28  require_once($CFG->dirroot.'/completion/data_object.php');
  29  require_once($CFG->dirroot.'/completion/completion_criteria_completion.php');
  30  
  31  /**
  32   * Self completion criteria type
  33   * Criteria type constant, primarily for storing criteria type in the database.
  34   */
  35  define('COMPLETION_CRITERIA_TYPE_SELF',         1);
  36  
  37  /**
  38   * Date completion criteria type
  39   * Criteria type constant, primarily for storing criteria type in the database.
  40   */
  41  define('COMPLETION_CRITERIA_TYPE_DATE',         2);
  42  
  43  /**
  44   * Unenrol completion criteria type
  45   * Criteria type constant, primarily for storing criteria type in the database.
  46   */
  47  define('COMPLETION_CRITERIA_TYPE_UNENROL',      3);
  48  
  49  /**
  50   * Activity completion criteria type
  51   * Criteria type constant, primarily for storing criteria type in the database.
  52   */
  53  define('COMPLETION_CRITERIA_TYPE_ACTIVITY',     4);
  54  
  55  /**
  56   * Duration completion criteria type
  57   * Criteria type constant, primarily for storing criteria type in the database.
  58   */
  59  define('COMPLETION_CRITERIA_TYPE_DURATION',     5);
  60  
  61  /**
  62   * Grade completion criteria type
  63   * Criteria type constant, primarily for storing criteria type in the database.
  64   */
  65  define('COMPLETION_CRITERIA_TYPE_GRADE',        6);
  66  
  67  /**
  68   * Role completion criteria type
  69   * Criteria type constant, primarily for storing criteria type in the database.
  70   */
  71  define('COMPLETION_CRITERIA_TYPE_ROLE',         7);
  72  
  73  /**
  74   * Course completion criteria type
  75   * Criteria type constant, primarily for storing criteria type in the database.
  76   */
  77  define('COMPLETION_CRITERIA_TYPE_COURSE',       8);
  78  
  79  /**
  80   * Criteria type constant to class name mapping.
  81   *
  82   * This global variable would be improved if it was implemented as a cache.
  83   */
  84  global $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
  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
 105   */
 106  abstract class completion_criteria extends data_object {
 107  
 108      /* @var string Database table name that stores completion criteria information  */
 109      public $table = 'course_completion_criteria';
 110  
 111      /**
 112       * Array of required table fields, must start with 'id'.
 113       * Defaults to id, course, criteriatype, module, moduleinstane, courseinstance,
 114       * enrolperiod, timeend, gradepass, role
 115       * @var array
 116       */
 117      public $required_fields = array('id', 'course', 'criteriatype', 'module', 'moduleinstance', 'courseinstance', 'enrolperiod', 'timeend', 'gradepass', 'role');
 118  
 119      /* @var int Course id  */
 120      public $course;
 121  
 122      /**
 123       * Criteria type
 124       * One of the COMPLETION_CRITERIA_TYPE_* constants
 125       * @var int
 126       */
 127      public $criteriatype;
 128  
 129      /* @var string Module type this criteria relates to (for activity criteria)  */
 130      public $module;
 131  
 132      /* @var int Course module instance id this criteria relates to (for activity criteria) */
 133      public $moduleinstance;
 134  
 135      /**
 136       * Period after enrolment completion will be triggered (for period criteria)
 137       * The value here is the number of days as an int.
 138       * @var int
 139       */
 140      public $enrolperiod;
 141  
 142      /**
 143       * Date of course completion (for date criteria)
 144       * This is a timestamp value
 145       * @var int
 146       */
 147      public $date;
 148  
 149      /* @var float Passing grade required to complete course (for grade completion) */
 150      public $gradepass;
 151  
 152      /* @var int Role ID that has the ability to mark a user as complete (for role completion) */
 153      public $role;
 154  
 155      /**
 156       * Finds and returns all data_object instances based on params.
 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
 165       *
 166       * @param array $params associative arrays varname=>value
 167       * @return completion_criteria
 168       */
 169      public static function factory($params) {
 170          global $CFG, $COMPLETION_CRITERIA_TYPES;
 171  
 172          if (!isset($params['criteriatype']) || !isset($COMPLETION_CRITERIA_TYPES[$params['criteriatype']])) {
 173              print_error('invalidcriteriatype', 'completion');
 174          }
 175  
 176          $class = 'completion_criteria_'.$COMPLETION_CRITERIA_TYPES[$params['criteriatype']];
 177          require_once($CFG->dirroot.'/completion/criteria/'.$class.'.php');
 178  
 179          return new $class($params, false);
 180      }
 181  
 182      /**
 183       * Add appropriate form elements to the critieria form
 184       *
 185       * @param moodleform $mform Moodle forms object
 186       * @param mixed $data optional Any additional data that can be used to set default values in the form
 187       * @return void
 188       */
 189      abstract public function config_form_display(&$mform, $data = null);
 190  
 191      /**
 192       * Update the criteria information stored in the database
 193       *
 194       * @param array $data Form data
 195       * @return void
 196       */
 197      abstract public function update_config(&$data);
 198  
 199      /**
 200       * Review this criteria and decide if the user has completed
 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
 205       */
 206      abstract public function review($completion, $mark = true);
 207  
 208      /**
 209       * Return criteria title for display in reports
 210       *
 211       * @return string
 212       */
 213      abstract public function get_title();
 214  
 215      /**
 216       * Return a more detailed criteria title for display in reports
 217       *
 218       * @return string
 219       */
 220      abstract public function get_title_detailed();
 221  
 222      /**
 223       * Return criteria type title for display in reports
 224       *
 225       * @return string
 226       */
 227      abstract public function get_type_title();
 228  
 229      /**
 230       * Return criteria progress details for display in reports
 231       *
 232       * @param completion_completion $completion The user's completion record
 233       * @return array
 234       */
 235      abstract public function get_details($completion);
 236  
 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  
 251      /**
 252       * Return criteria status text for display in reports
 253       *
 254       * @param completion_completion $completion The user's completion record
 255       * @return string
 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       *
 265       * @param completion_completion $completion The user's criteria completion record
 266       * @return bool
 267       */
 268      public function is_pending($completion) {
 269          $review = $this->review($completion, false);
 270  
 271          return $review !== $completion->is_complete();
 272      }
 273  }