Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 39 and 401]

   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 critieria - completion on achieving course grade
  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.'/grade/lib.php';
  29  require_once $CFG->dirroot.'/grade/querylib.php';
  30  
  31  /**
  32   * Course completion critieria - completion on achieving course grade
  33   *
  34   * @package core_completion
  35   * @category completion
  36   * @copyright 2009 Catalyst IT Ltd
  37   * @author Aaron Barnes <aaronb@catalyst.net.nz>
  38   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39   */
  40  class completion_criteria_grade extends completion_criteria {
  41  
  42      /* @var int Criteria type constant [COMPLETION_CRITERIA_TYPE_GRADE] */
  43      public $criteriatype = COMPLETION_CRITERIA_TYPE_GRADE;
  44  
  45      /**
  46       * Finds and returns a data_object instance based on params.
  47       *
  48       * @param array $params associative array varname => value of various
  49       * parameters used to fetch data_object
  50       * @return data_object data_object instance or false if none found.
  51       */
  52      public static function fetch($params) {
  53          $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_GRADE;
  54          return self::fetch_helper('course_completion_criteria', __CLASS__, $params);
  55      }
  56  
  57      /**
  58       * Add appropriate form elements to the critieria form
  59       *
  60       * @param moodle_form $mform Moodle forms object
  61       * @param stdClass $data containing default values to be set in the form
  62       */
  63      public function config_form_display(&$mform, $data = null) {
  64          $mform->addElement('checkbox', 'criteria_grade', get_string('enable'));
  65          $mform->addElement('text', 'criteria_grade_value', get_string('graderequired', 'completion'));
  66          $mform->disabledIf('criteria_grade_value', 'criteria_grade');
  67          $mform->setType('criteria_grade_value', PARAM_RAW); // Uses unformat_float.
  68          // Grades are stored in Moodle with 5 decimal points, make sure we do not accidentally round them
  69          // when setting the form value.
  70          $mform->setDefault('criteria_grade_value', format_float($data, 5));
  71  
  72          if ($this->id) {
  73              $mform->setDefault('criteria_grade', 1);
  74              $mform->setDefault('criteria_grade_value', format_float($this->gradepass, 5));
  75          }
  76      }
  77  
  78      /**
  79       * Update the criteria information stored in the database
  80       *
  81       * @param stdClass $data Form data
  82       */
  83      public function update_config(&$data) {
  84  
  85          if (!empty($data->criteria_grade)) {
  86              $formatedgrade = unformat_float($data->criteria_grade_value);
  87              // TODO validation
  88              if (!empty($formatedgrade) && is_numeric($formatedgrade)) {
  89                  $this->course = $data->id;
  90                  $this->gradepass = $formatedgrade;
  91                  $this->insert();
  92              }
  93          }
  94      }
  95  
  96      /**
  97       * Get user's course grade in this course
  98       *
  99       * @param completion_completion $completion an instance of completion_completion class
 100       * @return float
 101       */
 102      private function get_grade($completion) {
 103          $grade = grade_get_course_grade($completion->userid, $this->course);
 104          return $grade->grade;
 105      }
 106  
 107      /**
 108       * Review this criteria and decide if the user has completed
 109       *
 110       * @param completion_completion $completion The user's completion record
 111       * @param bool $mark Optionally set false to not save changes to database
 112       * @return bool
 113       */
 114      public function review($completion, $mark = true) {
 115          // Get user's course grade
 116          $grade = $this->get_grade($completion);
 117  
 118          // If user's current course grade is higher than the required pass grade
 119          if ($this->gradepass && $this->gradepass <= $grade) {
 120              if ($mark) {
 121                  $completion->gradefinal = $grade;
 122                  $completion->mark_complete();
 123              }
 124  
 125              return true;
 126          }
 127  
 128          return false;
 129      }
 130  
 131      /**
 132       * Return criteria title for display in reports
 133       *
 134       * @return  string
 135       */
 136      public function get_title() {
 137          return get_string('coursegrade', 'completion');
 138      }
 139  
 140      /**
 141       * Return a more detailed criteria title for display in reports
 142       *
 143       * @return string
 144       */
 145      public function get_title_detailed() {
 146          global $CFG;
 147          require_once($CFG->libdir . '/gradelib.php');
 148          $decimalpoints = grade_get_setting($this->course, 'decimalpoints', $CFG->grade_decimalpoints);
 149          $graderequired = format_float($this->gradepass, $decimalpoints);
 150          return get_string('gradexrequired', 'completion', $graderequired);
 151      }
 152  
 153      /**
 154       * Return criteria type title for display in reports
 155       *
 156       * @return string
 157       */
 158      public function get_type_title() {
 159          return get_string('gradenoun');
 160      }
 161  
 162      /**
 163       * Return criteria status text for display in reports
 164       *
 165       * @param completion_completion $completion The user's completion record
 166       * @return string
 167       */
 168      public function get_status($completion) {
 169          global $CFG;
 170          require_once($CFG->libdir . '/gradelib.php');
 171          $decimalpoints = grade_get_setting($this->course, 'decimalpoints', $CFG->grade_decimalpoints);
 172  
 173          $grade = $this->get_grade($completion);
 174          $graderequired = $this->get_title_detailed();
 175  
 176          if ($grade) {
 177              $grade = format_float($grade, $decimalpoints);
 178          } else {
 179              $grade = get_string('nograde');
 180          }
 181  
 182          return $grade.' ('.$graderequired.')';
 183      }
 184  
 185      /**
 186       * Find user's who have completed this criteria
 187       */
 188      public function cron() {
 189          global $DB;
 190  
 191          // Get all users who meet this criteria
 192          $sql = '
 193              SELECT DISTINCT
 194                  c.id AS course,
 195                  cr.id AS criteriaid,
 196                  ra.userid AS userid,
 197                  gg.finalgrade AS gradefinal,
 198                  gg.timemodified AS timecompleted
 199              FROM
 200                  {course_completion_criteria} cr
 201              INNER JOIN
 202                  {course} c
 203               ON cr.course = c.id
 204              INNER JOIN
 205                  {context} con
 206               ON con.instanceid = c.id
 207              INNER JOIN
 208                  {role_assignments} ra
 209                ON ra.contextid = con.id
 210              INNER JOIN
 211                  {grade_items} gi
 212               ON gi.courseid = c.id
 213              AND gi.itemtype = \'course\'
 214              INNER JOIN
 215                  {grade_grades} gg
 216               ON gg.itemid = gi.id
 217              AND gg.userid = ra.userid
 218              LEFT JOIN
 219                  {course_completion_crit_compl} cc
 220               ON cc.criteriaid = cr.id
 221              AND cc.userid = ra.userid
 222              WHERE
 223                  cr.criteriatype = '.COMPLETION_CRITERIA_TYPE_GRADE.'
 224              AND con.contextlevel = '.CONTEXT_COURSE.'
 225              AND c.enablecompletion = 1
 226              AND cc.id IS NULL
 227              AND gg.finalgrade >= cr.gradepass
 228          ';
 229  
 230          // Loop through completions, and mark as complete
 231          $rs = $DB->get_recordset_sql($sql);
 232          foreach ($rs as $record) {
 233              $completion = new completion_criteria_completion((array) $record, DATA_OBJECT_FETCH_BY_KEY);
 234              $completion->mark_complete($record->timecompleted);
 235          }
 236          $rs->close();
 237      }
 238  
 239      /**
 240       * Return criteria progress details for display in reports
 241       *
 242       * @param completion_completion $completion The user's completion record
 243       * @return array An array with the following keys:
 244       *     type, criteria, requirement, status
 245       */
 246      public function get_details($completion) {
 247          global $CFG;
 248          require_once($CFG->libdir . '/gradelib.php');
 249          $decimalpoints = grade_get_setting($this->course, 'decimalpoints', $CFG->grade_decimalpoints);
 250  
 251          $details = array();
 252          $details['type'] = get_string('coursegrade', 'completion');
 253          $details['criteria'] = get_string('graderequired', 'completion');
 254          $details['requirement'] = format_float($this->gradepass, $decimalpoints);
 255          $details['status'] = '';
 256  
 257          $grade = format_float($this->get_grade($completion), $decimalpoints);
 258          if ($grade) {
 259              $details['status'] = $grade;
 260          }
 261  
 262          return $details;
 263      }
 264  
 265      /**
 266       * Return pix_icon for display in reports.
 267       *
 268       * @param string $alt The alt text to use for the icon
 269       * @param array $attributes html attributes
 270       * @return pix_icon
 271       */
 272      public function get_icon($alt, array $attributes = null) {
 273          return new pix_icon('i/grades', $alt, 'moodle', $attributes);
 274      }
 275  }