[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   * 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  global $COMPLETION_CRITERIA_TYPES;
  83  $COMPLETION_CRITERIA_TYPES = array(
  84      COMPLETION_CRITERIA_TYPE_SELF       => 'self',
  85      COMPLETION_CRITERIA_TYPE_DATE       => 'date',
  86      COMPLETION_CRITERIA_TYPE_UNENROL    => 'unenrol',
  87      COMPLETION_CRITERIA_TYPE_ACTIVITY   => 'activity',
  88      COMPLETION_CRITERIA_TYPE_DURATION   => 'duration',
  89      COMPLETION_CRITERIA_TYPE_GRADE      => 'grade',
  90      COMPLETION_CRITERIA_TYPE_ROLE       => 'role',
  91      COMPLETION_CRITERIA_TYPE_COURSE     => 'course',
  92  );
  93  
  94  
  95  /**
  96   * Completion criteria abstract definition
  97   *
  98   * @package core_completion
  99   * @category completion
 100   * @copyright 2009 Catalyst IT Ltd
 101   * @author Aaron Barnes <aaronb@catalyst.net.nz>
 102   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 103   */
 104  abstract class completion_criteria extends data_object {
 105  
 106      /* @var string Database table name that stores completion criteria information  */
 107      public $table = 'course_completion_criteria';
 108  
 109      /**
 110       * Array of required table fields, must start with 'id'.
 111       * Defaults to id, course, criteriatype, module, moduleinstane, courseinstance,
 112       * enrolperiod, timeend, gradepass, role
 113       * @var array
 114       */
 115      public $required_fields = array('id', 'course', 'criteriatype', 'module', 'moduleinstance', 'courseinstance', 'enrolperiod', 'timeend', 'gradepass', 'role');
 116  
 117      /* @var int Course id  */
 118      public $course;
 119  
 120      /**
 121       * Criteria type
 122       * One of the COMPLETION_CRITERIA_TYPE_* constants
 123       * @var int
 124       */
 125      public $criteriatype;
 126  
 127      /* @var string Module type this criteria relates to (for activity criteria)  */
 128      public $module;
 129  
 130      /* @var int Course module instance id this criteria relates to (for activity criteria) */
 131      public $moduleinstance;
 132  
 133      /**
 134       * Period after enrolment completion will be triggered (for period criteria)
 135       * The value here is the number of days as an int.
 136       * @var int
 137       */
 138      public $enrolperiod;
 139  
 140      /**
 141       * Date of course completion (for date criteria)
 142       * This is a timestamp value
 143       * @var int
 144       */
 145      public $date;
 146  
 147      /* @var float Passing grade required to complete course (for grade completion) */
 148      public $gradepass;
 149  
 150      /* @var int Role ID that has the ability to mark a user as complete (for role completion) */
 151      public $role;
 152  
 153      /**
 154       * Finds and returns all data_object instances based on params.
 155       *
 156       * @param array $params associative arrays varname=>value
 157       * @return array array of data_object insatnces or false if none found.
 158       */
 159      public static function fetch_all($params) {}
 160  
 161      /**
 162       * Factory method for creating correct class object
 163       *
 164       * @param array $params associative arrays varname=>value
 165       * @return completion_criteria
 166       */
 167      public static function factory($params) {
 168          global $CFG, $COMPLETION_CRITERIA_TYPES;
 169  
 170          if (!isset($params['criteriatype']) || !isset($COMPLETION_CRITERIA_TYPES[$params['criteriatype']])) {
 171              print_error('invalidcriteriatype', 'completion');
 172          }
 173  
 174          $class = 'completion_criteria_'.$COMPLETION_CRITERIA_TYPES[$params['criteriatype']];
 175          require_once($CFG->dirroot.'/completion/criteria/'.$class.'.php');
 176  
 177          return new $class($params, false);
 178      }
 179  
 180      /**
 181       * Add appropriate form elements to the critieria form
 182       *
 183       * @param moodleform $mform Moodle forms object
 184       * @param mixed $data optional Any additional data that can be used to set default values in the form
 185       * @return void
 186       */
 187      abstract public function config_form_display(&$mform, $data = null);
 188  
 189      /**
 190       * Update the criteria information stored in the database
 191       *
 192       * @param array $data Form data
 193       * @return void
 194       */
 195      abstract public function update_config(&$data);
 196  
 197      /**
 198       * Review this criteria and decide if the user has completed
 199       *
 200       * @param object $completion The user's completion record
 201       * @param boolean $mark Optionally set false to not save changes to database
 202       * @return boolean
 203       */
 204      abstract public function review($completion, $mark = true);
 205  
 206      /**
 207       * Return criteria title for display in reports
 208       *
 209       * @return string
 210       */
 211      abstract public function get_title();
 212  
 213      /**
 214       * Return a more detailed criteria title for display in reports
 215       *
 216       * @return string
 217       */
 218      abstract public function get_title_detailed();
 219  
 220      /**
 221       * Return criteria type title for display in reports
 222       *
 223       * @return string
 224       */
 225      abstract public function get_type_title();
 226  
 227      /**
 228       * Return criteria progress details for display in reports
 229       *
 230       * @param completion_completion $completion The user's completion record
 231       * @return array
 232       */
 233      abstract public function get_details($completion);
 234  
 235      /**
 236       * Return pix_icon for display in reports.
 237       *
 238       * @param string $alt The alt text to use for the icon
 239       * @param array $attributes html attributes
 240       * @return pix_icon
 241       */
 242      public function get_icon($alt, array $attributes = null) {
 243          global $COMPLETION_CRITERIA_TYPES;
 244  
 245          $criteriatype = $COMPLETION_CRITERIA_TYPES[$this->criteriatype];
 246          return new pix_icon('i/'.$criteriatype, $alt, 'moodle', $attributes);
 247      }
 248  
 249      /**
 250       * Return criteria status text for display in reports
 251       *
 252       * @param completion_completion $completion The user's completion record
 253       * @return string
 254       */
 255      public function get_status($completion) {
 256          return $completion->is_complete() ? get_string('yes') : get_string('no');
 257      }
 258  
 259      /**
 260       * Return true if the criteria's current status is different to what is sorted
 261       * in the database, e.g. pending an update
 262       *
 263       * @param completion_completion $completion The user's criteria completion record
 264       * @return bool
 265       */
 266      public function is_pending($completion) {
 267          $review = $this->review($completion, false);
 268  
 269          return $review !== $completion->is_complete();
 270      }
 271  }