Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • Differences Between: [Versions 310 and 311] [Versions 37 and 311] [Versions 38 and 311] [Versions 39 and 311]

       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  }