[Summary view]

Differences Between: [Versions 39 and 311] [Versions 39 and 400] [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   * Bulk activity completion manager class
  19   *
  20   * @package     core_completion
  21   * @category    completion
  22   * @copyright   2017 Adrian Greeve
  23   * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  namespace core_completion;
  27  
  28  use stdClass;
  29  use context_course;
  30  use cm_info;
  31  use tabobject;
  32  use lang_string;
  33  use moodle_url;
  34  defined('MOODLE_INTERNAL') || die;
  35  
  36  /**
  37   * Bulk activity completion manager class
  38   *
  39   * @package     core_completion
  40   * @category    completion
  41   * @copyright   2017 Adrian Greeve
  42   * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  43   */
  44  class manager {
  45  
  46      /**
  47       * @var int $courseid the course id.
  48       */
  49      protected $courseid;
  50  
  51      /**
  52       * manager constructor.
  53       * @param int $courseid the course id.
  54       */
  55      public function __construct($courseid) {
  56          $this->courseid = $courseid;
  57      }
  58  
  59      /**
  60       * Gets the data (context) to be used with the bulkactivitycompletion template.
  61       *
  62       * @return stdClass data for use with the bulkactivitycompletion template.
  63       */
  64      public function get_activities_and_headings() {
  65          global $OUTPUT;
  66          $moduleinfo = get_fast_modinfo($this->courseid);
  67          $sections = $moduleinfo->get_sections();
  68          $data = new stdClass;
  69          $data->courseid = $this->courseid;
  70          $data->sesskey = sesskey();
  71          $data->helpicon = $OUTPUT->help_icon('bulkcompletiontracking', 'core_completion');
  72          $data->sections = [];
  73          foreach ($sections as $sectionnumber => $section) {
  74              $sectioninfo = $moduleinfo->get_section_info($sectionnumber);
  75  
  76              $sectionobject = new stdClass();
  77              $sectionobject->sectionnumber = $sectionnumber;
  78              $sectionobject->name = get_section_name($this->courseid, $sectioninfo);
  79              $sectionobject->activities = $this->get_activities($section, true);
  80              $data->sections[] = $sectionobject;
  81          }
  82          return $data;
  83      }
  84  
  85      /**
  86       * Gets the data (context) to be used with the activityinstance template
  87       *
  88       * @param array $cmids list of course module ids
  89       * @param bool $withcompletiondetails include completion details
  90       * @return array
  91       */
  92      public function get_activities($cmids, $withcompletiondetails = false) {
  93          $moduleinfo = get_fast_modinfo($this->courseid);
  94          $activities = [];
  95          foreach ($cmids as $cmid) {
  96              $mod = $moduleinfo->get_cm($cmid);
  97              if (!$mod->uservisible) {
  98                  continue;
  99              }
 100              $moduleobject = new stdClass();
 101              $moduleobject->cmid = $cmid;
 102              $moduleobject->modname = $mod->get_formatted_name();
 103              $moduleobject->icon = $mod->get_icon_url()->out();
 104              $moduleobject->url = $mod->url;
 105              $moduleobject->canmanage = $withcompletiondetails && self::can_edit_bulk_completion($this->courseid, $mod);
 106  
 107              // Get activity completion information.
 108              if ($moduleobject->canmanage) {
 109                  $moduleobject->completionstatus = $this->get_completion_detail($mod);
 110              } else {
 111                  $moduleobject->completionstatus = ['icon' => null, 'string' => null];
 112              }
 113              if (self::can_edit_bulk_completion($this->courseid, $mod)) {
 114                  $activities[] = $moduleobject;
 115              }
 116          }
 117          return $activities;
 118      }
 119  
 120  
 121      /**
 122       * Get completion information on the selected module or module type
 123       *
 124       * @param cm_info|stdClass $mod either instance of cm_info (with 'customcompletionrules' in customdata) or
 125       *      object with fields ->completion, ->completionview, ->completionexpected, ->completionusegrade
 126       *      and ->customdata['customcompletionrules']
 127       * @return array
 128       */
 129      private function get_completion_detail($mod) {
 130          global $OUTPUT;
 131          $strings = [];
 132          switch ($mod->completion) {
 133              case COMPLETION_TRACKING_NONE:
 134                  $strings['string'] = get_string('none');
 135                  break;
 136  
 137              case COMPLETION_TRACKING_MANUAL:
 138                  $strings['string'] = get_string('manual', 'completion');
 139                  $strings['icon'] = $OUTPUT->pix_icon('i/completion-manual-y', get_string('completion_manual', 'completion'));
 140                  break;
 141  
 142              case COMPLETION_TRACKING_AUTOMATIC:
 143                  $strings['string'] = get_string('withconditions', 'completion');
 144                  $strings['icon'] = $OUTPUT->pix_icon('i/completion-auto-y', get_string('completion_automatic', 'completion'));
 145                  break;
 146  
 147              default:
 148                  $strings['string'] = get_string('none');
 149                  break;
 150          }
 151  
 152          // Get the descriptions for all the active completion rules for the module.
 153          if ($ruledescriptions = $this->get_completion_active_rule_descriptions($mod)) {
 154              foreach ($ruledescriptions as $ruledescription) {
 155                  $strings['string'] .= \html_writer::empty_tag('br') . $ruledescription;
 156              }
 157          }
 158          return $strings;
 159      }
 160  
 161      /**
 162       * Get the descriptions for all active conditional completion rules for the current module.
 163       *
 164       * @param cm_info|stdClass $moduledata either instance of cm_info (with 'customcompletionrules' in customdata) or
 165       *      object with fields ->completion, ->completionview, ->completionexpected, ->completionusegrade
 166       *      and ->customdata['customcompletionrules']
 167       * @return array $activeruledescriptions an array of strings describing the active completion rules.
 168       */
 169      protected function get_completion_active_rule_descriptions($moduledata) {
 170          $activeruledescriptions = [];
 171  
 172          if ($moduledata->completion == COMPLETION_TRACKING_AUTOMATIC) {
 173              // Generate the description strings for the core conditional completion rules (if set).
 174              if (!empty($moduledata->completionview)) {
 175                  $activeruledescriptions[] = get_string('completionview_desc', 'completion');
 176              }
 177              if ($moduledata instanceof cm_info && !is_null($moduledata->completiongradeitemnumber) ||
 178                  ($moduledata instanceof stdClass && !empty($moduledata->completionusegrade))) {
 179                  $activeruledescriptions[] = get_string('completionusegrade_desc', 'completion');
 180              }
 181  
 182              // Now, ask the module to provide descriptions for its custom conditional completion rules.
 183              if ($customruledescriptions = component_callback($moduledata->modname,
 184                  'get_completion_active_rule_descriptions', [$moduledata])) {
 185                  $activeruledescriptions = array_merge($activeruledescriptions, $customruledescriptions);
 186              }
 187          }
 188  
 189          if ($moduledata->completion != COMPLETION_TRACKING_NONE) {
 190              if (!empty($moduledata->completionexpected)) {
 191                  $activeruledescriptions[] = get_string('completionexpecteddesc', 'completion',
 192                      userdate($moduledata->completionexpected));
 193              }
 194          }
 195  
 196          return $activeruledescriptions;
 197      }
 198  
 199      /**
 200       * Gets the course modules for the current course.
 201       *
 202       * @return stdClass $data containing the modules
 203       */
 204      public function get_activities_and_resources() {
 205          global $DB, $OUTPUT, $CFG;
 206          require_once($CFG->dirroot.'/course/lib.php');
 207  
 208          // Get enabled activities and resources.
 209          $modules = $DB->get_records('modules', ['visible' => 1], 'name ASC');
 210          $data = new stdClass();
 211          $data->courseid = $this->courseid;
 212          $data->sesskey = sesskey();
 213          $data->helpicon = $OUTPUT->help_icon('bulkcompletiontracking', 'core_completion');
 214          // Add icon information.
 215          $data->modules = array_values($modules);
 216          $coursecontext = context_course::instance($this->courseid);
 217          $canmanage = has_capability('moodle/course:manageactivities', $coursecontext);
 218          $course = get_course($this->courseid);
 219          foreach ($data->modules as $module) {
 220              $module->icon = $OUTPUT->image_url('icon', $module->name)->out();
 221              $module->formattedname = format_string(get_string('modulenameplural', 'mod_' . $module->name),
 222                  true, ['context' => $coursecontext]);
 223              $module->canmanage = $canmanage && course_allowed_module($course, $module->name);
 224              $defaults = self::get_default_completion($course, $module, false);
 225              $defaults->modname = $module->name;
 226              $module->completionstatus = $this->get_completion_detail($defaults);
 227          }
 228  
 229          return $data;
 230      }
 231  
 232      /**
 233       * Checks if current user can edit activity completion
 234       *
 235       * @param int|stdClass $courseorid
 236       * @param \cm_info|null $cm if specified capability for a given coursemodule will be check,
 237       *     if not specified capability to edit at least one activity is checked.
 238       */
 239      public static function can_edit_bulk_completion($courseorid, $cm = null) {
 240          if ($cm) {
 241              return $cm->uservisible && has_capability('moodle/course:manageactivities', $cm->context);
 242          }
 243          $coursecontext = context_course::instance(is_object($courseorid) ? $courseorid->id : $courseorid);
 244          if (has_capability('moodle/course:manageactivities', $coursecontext)) {
 245              return true;
 246          }
 247          $modinfo = get_fast_modinfo($courseorid);
 248          foreach ($modinfo->cms as $mod) {
 249              if ($mod->uservisible && has_capability('moodle/course:manageactivities', $mod->context)) {
 250                  return true;
 251              }
 252          }
 253          return false;
 254      }
 255  
 256      /**
 257       * Gets the available completion tabs for the current course and user.
 258       *
 259       * @param stdClass|int $courseorid the course object or id.
 260       * @return tabobject[]
 261       */
 262      public static function get_available_completion_tabs($courseorid) {
 263          $tabs = [];
 264  
 265          $courseid = is_object($courseorid) ? $courseorid->id : $courseorid;
 266          $coursecontext = context_course::instance($courseid);
 267  
 268          if (has_capability('moodle/course:update', $coursecontext)) {
 269              $tabs[] = new tabobject(
 270                  'completion',
 271                  new moodle_url('/course/completion.php', ['id' => $courseid]),
 272                  new lang_string('coursecompletion', 'completion')
 273              );
 274          }
 275  
 276          if (has_capability('moodle/course:manageactivities', $coursecontext)) {
 277              $tabs[] = new tabobject(
 278                  'defaultcompletion',
 279                  new moodle_url('/course/defaultcompletion.php', ['id' => $courseid]),
 280                  new lang_string('defaultcompletion', 'completion')
 281              );
 282          }
 283  
 284          if (self::can_edit_bulk_completion($courseorid)) {
 285              $tabs[] = new tabobject(
 286                  'bulkcompletion',
 287                  new moodle_url('/course/bulkcompletion.php', ['id' => $courseid]),
 288                  new lang_string('bulkactivitycompletion', 'completion')
 289              );
 290          }
 291  
 292          return $tabs;
 293      }
 294  
 295      /**
 296       * Applies completion from the bulk edit form to all selected modules
 297       *
 298       * @param stdClass $data data received from the core_completion_bulkedit_form
 299       * @param bool $updateinstances if we need to update the instance tables of the module (i.e. 'assign', 'forum', etc.) -
 300       *      if no module-specific completion rules were added to the form, update of the module table is not needed.
 301       */
 302      public function apply_completion($data, $updateinstances) {
 303          $updated = false;
 304          $needreset = [];
 305          $modinfo = get_fast_modinfo($this->courseid);
 306  
 307          $cmids = $data->cmid;
 308  
 309          $data = (array)$data;
 310          unset($data['id']); // This is a course id, we don't want to confuse it with cmid or instance id.
 311          unset($data['cmid']);
 312          unset($data['submitbutton']);
 313  
 314          foreach ($cmids as $cmid) {
 315              $cm = $modinfo->get_cm($cmid);
 316              if (self::can_edit_bulk_completion($this->courseid, $cm) && $this->apply_completion_cm($cm, $data, $updateinstances)) {
 317                  $updated = true;
 318                  if ($cm->completion != COMPLETION_TRACKING_MANUAL || $data['completion'] != COMPLETION_TRACKING_MANUAL) {
 319                      // If completion was changed we will need to reset it's state. Exception is when completion was and remains as manual.
 320                      $needreset[] = $cm->id;
 321                  }
 322              }
 323              // Update completion calendar events.
 324              $completionexpected = ($data['completionexpected']) ? $data['completionexpected'] : null;
 325              \core_completion\api::update_completion_date_event($cm->id, $cm->modname, $cm->instance, $completionexpected);
 326          }
 327          if ($updated) {
 328              // Now that modules are fully updated, also update completion data if required.
 329              // This will wipe all user completion data and recalculate it.
 330              rebuild_course_cache($this->courseid, true);
 331              $modinfo = get_fast_modinfo($this->courseid);
 332              $completion = new \completion_info($modinfo->get_course());
 333              foreach ($needreset as $cmid) {
 334                  $completion->reset_all_state($modinfo->get_cm($cmid));
 335              }
 336  
 337              // And notify the user of the result.
 338              \core\notification::add(get_string('activitycompletionupdated', 'core_completion'), \core\notification::SUCCESS);
 339          }
 340      }
 341  
 342      /**
 343       * Applies new completion rules to one course module
 344       *
 345       * @param \cm_info $cm
 346       * @param array $data
 347       * @param bool $updateinstance if we need to update the instance table of the module (i.e. 'assign', 'forum', etc.) -
 348       *      if no module-specific completion rules were added to the form, update of the module table is not needed.
 349       * @return bool if module was updated
 350       */
 351      protected function apply_completion_cm(\cm_info $cm, $data, $updateinstance) {
 352          global $DB;
 353  
 354          $defaults = ['completion' => COMPLETION_DISABLED, 'completionview' => COMPLETION_VIEW_NOT_REQUIRED,
 355              'completionexpected' => 0, 'completiongradeitemnumber' => null];
 356  
 357          $data += ['completion' => $cm->completion,
 358              'completionexpected' => $cm->completionexpected,
 359              'completionview' => $cm->completionview];
 360  
 361          if ($cm->completion == $data['completion'] && $cm->completion == COMPLETION_TRACKING_NONE) {
 362              // If old and new completion are both "none" - no changes are needed.
 363              return false;
 364          }
 365  
 366          if ($cm->completion == $data['completion'] && $cm->completion == COMPLETION_TRACKING_NONE &&
 367                  $cm->completionexpected == $data['completionexpected']) {
 368              // If old and new completion are both "manual" and completion expected date is not changed - no changes are needed.
 369              return false;
 370          }
 371  
 372          if (array_key_exists('completionusegrade', $data)) {
 373              // Convert the 'use grade' checkbox into a grade-item number: 0 if checked, null if not.
 374              $data['completiongradeitemnumber'] = !empty($data['completionusegrade']) ? 0 : null;
 375              unset($data['completionusegrade']);
 376          } else {
 377              $data['completiongradeitemnumber'] = $cm->completiongradeitemnumber;
 378          }
 379  
 380          // Update module instance table.
 381          if ($updateinstance) {
 382              $moddata = ['id' => $cm->instance, 'timemodified' => time()] + array_diff_key($data, $defaults);
 383              $DB->update_record($cm->modname, $moddata);
 384          }
 385  
 386          // Update course modules table.
 387          $cmdata = ['id' => $cm->id, 'timemodified' => time()] + array_intersect_key($data, $defaults);
 388          $DB->update_record('course_modules', $cmdata);
 389  
 390          \core\event\course_module_updated::create_from_cm($cm, $cm->context)->trigger();
 391  
 392          // We need to reset completion data for this activity.
 393          return true;
 394      }
 395  
 396  
 397      /**
 398       * Saves default completion from edit form to all selected module types
 399       *
 400       * @param stdClass $data data received from the core_completion_bulkedit_form
 401       * @param bool $updatecustomrules if we need to update the custom rules of the module -
 402       *      if no module-specific completion rules were added to the form, update of the module table is not needed.
 403       */
 404      public function apply_default_completion($data, $updatecustomrules) {
 405          global $DB;
 406  
 407          $courseid = $data->id;
 408          $coursecontext = context_course::instance($courseid);
 409          if (!$modids = $data->modids) {
 410              return;
 411          }
 412          $defaults = [
 413              'completion' => COMPLETION_DISABLED,
 414              'completionview' => COMPLETION_VIEW_NOT_REQUIRED,
 415              'completionexpected' => 0,
 416              'completionusegrade' => 0
 417          ];
 418  
 419          $data = (array)$data;
 420  
 421          if ($updatecustomrules) {
 422              $customdata = array_diff_key($data, $defaults);
 423              $data['customrules'] = $customdata ? json_encode($customdata) : null;
 424              $defaults['customrules'] = null;
 425          }
 426          $data = array_intersect_key($data, $defaults);
 427  
 428          // Get names of the affected modules.
 429          list($modidssql, $params) = $DB->get_in_or_equal($modids);
 430          $params[] = 1;
 431          $modules = $DB->get_records_select_menu('modules', 'id ' . $modidssql . ' and visible = ?', $params, '', 'id, name');
 432  
 433          // Get an associative array of [module_id => course_completion_defaults_id].
 434          list($in, $params) = $DB->get_in_or_equal($modids);
 435          $params[] = $courseid;
 436          $defaultsids = $DB->get_records_select_menu('course_completion_defaults', 'module ' . $in . ' and course = ?', $params, '',
 437                                                        'module, id');
 438  
 439          foreach ($modids as $modid) {
 440              if (!array_key_exists($modid, $modules)) {
 441                  continue;
 442              }
 443              if (isset($defaultsids[$modid])) {
 444                  $DB->update_record('course_completion_defaults', $data + ['id' => $defaultsids[$modid]]);
 445              } else {
 446                  $defaultsids[$modid] = $DB->insert_record('course_completion_defaults', $data + ['course' => $courseid,
 447                                                                                                   'module' => $modid]);
 448              }
 449              // Trigger event.
 450              \core\event\completion_defaults_updated::create([
 451                  'objectid' => $defaultsids[$modid],
 452                  'context' => $coursecontext,
 453                  'other' => ['modulename' => $modules[$modid]],
 454              ])->trigger();
 455          }
 456  
 457          // Add notification.
 458          \core\notification::add(get_string('defaultcompletionupdated', 'completion'), \core\notification::SUCCESS);
 459      }
 460  
 461      /**
 462       * Returns default completion rules for given module type in the given course
 463       *
 464       * @param stdClass $course
 465       * @param stdClass $module
 466       * @param bool $flatten if true all module custom completion rules become properties of the same object,
 467       *   otherwise they can be found as array in ->customdata['customcompletionrules']
 468       * @return stdClass
 469       */
 470      public static function get_default_completion($course, $module, $flatten = true) {
 471          global $DB, $CFG;
 472          if ($data = $DB->get_record('course_completion_defaults', ['course' => $course->id, 'module' => $module->id],
 473              'completion, completionview, completionexpected, completionusegrade, customrules')) {
 474              if ($data->customrules && ($customrules = @json_decode($data->customrules, true))) {
 475                  if ($flatten) {
 476                      foreach ($customrules as $key => $value) {
 477                          $data->$key = $value;
 478                      }
 479                  } else {
 480                      $data->customdata['customcompletionrules'] = $customrules;
 481                  }
 482              }
 483              unset($data->customrules);
 484          } else {
 485              $data = new stdClass();
 486              $data->completion = COMPLETION_TRACKING_NONE;
 487              if ($CFG->completiondefault) {
 488                  $completion = new \completion_info(get_fast_modinfo($course->id)->get_course());
 489                  if ($completion->is_enabled() && plugin_supports('mod', $module->name, FEATURE_MODEDIT_DEFAULT_COMPLETION, true)) {
 490                      $data->completion = COMPLETION_TRACKING_MANUAL;
 491                      $data->completionview = 1;
 492                  }
 493              }
 494          }
 495          return $data;
 496      }
 497  }