lib/completion/completion_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/>.
  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->libdir.'/completion/data_object.php');
  29 require_once($CFG->libdir.'/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             error('invalidcriteriatype', 'completion');
 172         }
 173
 174         $class = 'completion_criteria_'.$COMPLETION_CRITERIA_TYPES[$params['criteriatype']];
 175         require_once($CFG->libdir.'/completion/'.$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 criteria status text for display in reports
 237      *
 238      * @param completion_completion $completion The user's completion record
 239      * @return string
 240      */
 241     public function get_status($completion) {
 242         return $completion->is_complete() ? get_string('yes') : get_string('no');
 243     }
 244
 245     /**
 246      * Return true if the criteria's current status is different to what is sorted
 247      * in the database, e.g. pending an update
 248      *
 249      * @param completion_completion $completion The user's criteria completion record
 250      * @return bool
 251      */
 252     public function is_pending($completion) {
 253         $review = $this->review($completion, false);
 254
 255         return $review !== $completion->is_complete();
 256     }
 257 }