[Summary view]

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 401 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  
 180                  $description = 'completionusegrade_desc';
 181                  if (!empty($moduledata->completionpassgrade)) {
 182                      $description = 'completionpassgrade_desc';
 183                  }
 184  
 185                  $activeruledescriptions[] = get_string($description, 'completion');
 186              }
 187  
 188              // Now, ask the module to provide descriptions for its custom conditional completion rules.
 189              if ($customruledescriptions = component_callback($moduledata->modname,
 190                  'get_completion_active_rule_descriptions', [$moduledata])) {
 191                  $activeruledescriptions = array_merge($activeruledescriptions, $customruledescriptions);
 192              }
 193          }
 194  
 195          if ($moduledata->completion != COMPLETION_TRACKING_NONE) {
 196              if (!empty($moduledata->completionexpected)) {
 197                  $activeruledescriptions[] = get_string('completionexpecteddesc', 'completion',
 198                      userdate($moduledata->completionexpected));
 199              }
 200          }
 201  
 202          return $activeruledescriptions;
 203      }
 204  
 205      /**
 206       * Gets the course modules for the current course.
 207       *
 208       * @return stdClass $data containing the modules
 209       */
 210      public function get_activities_and_resources() {
 211          global $DB, $OUTPUT, $CFG;
 212          require_once($CFG->dirroot.'/course/lib.php');
 213  
 214          // Get enabled activities and resources.
 215          $modules = $DB->get_records('modules', ['visible' => 1], 'name ASC');
 216          $data = new stdClass();
 217          $data->courseid = $this->courseid;
 218          $data->sesskey = sesskey();
 219          $data->helpicon = $OUTPUT->help_icon('bulkcompletiontracking', 'core_completion');
 220          // Add icon information.
 221          $data->modules = array_values($modules);
 222          $coursecontext = context_course::instance($this->courseid);
 223          $canmanage = has_capability('moodle/course:manageactivities', $coursecontext);
 224          $course = get_course($this->courseid);
 225          foreach ($data->modules as $module) {
 226              $module->icon = $OUTPUT->image_url('monologo', $module->name)->out();
 227              $module->formattedname = format_string(get_string('modulenameplural', 'mod_' . $module->name),
 228                  true, ['context' => $coursecontext]);
 229              $module->canmanage = $canmanage && course_allowed_module($course, $module->name);
 230              $defaults = self::get_default_completion($course, $module, false);
 231              $defaults->modname = $module->name;
 232              $module->completionstatus = $this->get_completion_detail($defaults);
 233          }
 234  
 235          return $data;
 236      }
 237  
 238      /**
 239       * Checks if current user can edit activity completion
 240       *
 241       * @param int|stdClass $courseorid
 242       * @param \cm_info|null $cm if specified capability for a given coursemodule will be check,
 243       *     if not specified capability to edit at least one activity is checked.
 244       */
 245      public static function can_edit_bulk_completion($courseorid, $cm = null) {
 246          if ($cm) {
 247              return $cm->uservisible && has_capability('moodle/course:manageactivities', $cm->context);
 248          }
 249          $coursecontext = context_course::instance(is_object($courseorid) ? $courseorid->id : $courseorid);
 250          if (has_capability('moodle/course:manageactivities', $coursecontext)) {
 251              return true;
 252          }
 253          $modinfo = get_fast_modinfo($courseorid);
 254          foreach ($modinfo->cms as $mod) {
 255              if ($mod->uservisible && has_capability('moodle/course:manageactivities', $mod->context)) {
 256                  return true;
 257              }
 258          }
 259          return false;
 260      }
 261  
 262      /**
 263       * Gets the available completion tabs for the current course and user.
 264       *
 265       * @deprecated since Moodle 4.0
 266       * @param stdClass|int $courseorid the course object or id.
 267       * @return tabobject[]
 268       */
 269      public static function get_available_completion_tabs($courseorid) {
 270          debugging('get_available_completion_tabs() has been deprecated. Please use ' .
 271              'core_completion\manager::get_available_completion_options() instead.', DEBUG_DEVELOPER);
 272  
 273          $tabs = [];
 274  
 275          $courseid = is_object($courseorid) ? $courseorid->id : $courseorid;
 276          $coursecontext = context_course::instance($courseid);
 277  
 278          if (has_capability('moodle/course:update', $coursecontext)) {
 279              $tabs[] = new tabobject(
 280                  'completion',
 281                  new moodle_url('/course/completion.php', ['id' => $courseid]),
 282                  new lang_string('coursecompletion', 'completion')
 283              );
 284          }
 285  
 286          if (has_capability('moodle/course:manageactivities', $coursecontext)) {
 287              $tabs[] = new tabobject(
 288                  'defaultcompletion',
 289                  new moodle_url('/course/defaultcompletion.php', ['id' => $courseid]),
 290                  new lang_string('defaultcompletion', 'completion')
 291              );
 292          }
 293  
 294          if (self::can_edit_bulk_completion($courseorid)) {
 295              $tabs[] = new tabobject(
 296                  'bulkcompletion',
 297                  new moodle_url('/course/bulkcompletion.php', ['id' => $courseid]),
 298                  new lang_string('bulkactivitycompletion', 'completion')
 299              );
 300          }
 301  
 302          return $tabs;
 303      }
 304  
 305      /**
 306       * Returns an array with the available completion options (url => name) for the current course and user.
 307       *
 308       * @param int $courseid The course id.
 309       * @return array
 310       */
 311      public static function get_available_completion_options(int $courseid): array {
 312          $coursecontext = context_course::instance($courseid);
 313          $options = [];
 314  
 315          if (has_capability('moodle/course:update', $coursecontext)) {
 316              $completionlink = new moodle_url('/course/completion.php', ['id' => $courseid]);
 317              $options[$completionlink->out(false)] = get_string('coursecompletion', 'completion');
 318          }
 319  
 320          if (has_capability('moodle/course:manageactivities', $coursecontext)) {
 321              $defaultcompletionlink = new moodle_url('/course/defaultcompletion.php', ['id' => $courseid]);
 322              $options[$defaultcompletionlink->out(false)] = get_string('defaultcompletion', 'completion');
 323          }
 324  
 325          if (self::can_edit_bulk_completion($courseid)) {
 326              $bulkcompletionlink = new moodle_url('/course/bulkcompletion.php', ['id' => $courseid]);
 327              $options[$bulkcompletionlink->out(false)] = get_string('bulkactivitycompletion', 'completion');
 328          }
 329  
 330          return $options;
 331      }
 332  
 333      /**
 334       * Applies completion from the bulk edit form to all selected modules
 335       *
 336       * @param stdClass $data data received from the core_completion_bulkedit_form
 337       * @param bool $updateinstances if we need to update the instance tables of the module (i.e. 'assign', 'forum', etc.) -
 338       *      if no module-specific completion rules were added to the form, update of the module table is not needed.
 339       */
 340      public function apply_completion($data, $updateinstances) {
 341          $updated = false;
 342          $needreset = [];
 343          $modinfo = get_fast_modinfo($this->courseid);
 344  
 345          $cmids = $data->cmid;
 346  
 347          $data = (array)$data;
 348          unset($data['id']); // This is a course id, we don't want to confuse it with cmid or instance id.
 349          unset($data['cmid']);
 350          unset($data['submitbutton']);
 351  
 352          foreach ($cmids as $cmid) {
 353              $cm = $modinfo->get_cm($cmid);
 354              if (self::can_edit_bulk_completion($this->courseid, $cm) && $this->apply_completion_cm($cm, $data, $updateinstances)) {
 355                  $updated = true;
 356                  if ($cm->completion != COMPLETION_TRACKING_MANUAL || $data['completion'] != COMPLETION_TRACKING_MANUAL) {
 357                      // If completion was changed we will need to reset it's state. Exception is when completion was and remains as manual.
 358                      $needreset[] = $cm->id;
 359                  }
 360              }
 361              // Update completion calendar events.
 362              $completionexpected = ($data['completionexpected']) ? $data['completionexpected'] : null;
 363              \core_completion\api::update_completion_date_event($cm->id, $cm->modname, $cm->instance, $completionexpected);
 364          }
 365          if ($updated) {
 366              // Now that modules are fully updated, also update completion data if required.
 367              // This will wipe all user completion data and recalculate it.
 368              rebuild_course_cache($this->courseid, true);
 369              $modinfo = get_fast_modinfo($this->courseid);
 370              $completion = new \completion_info($modinfo->get_course());
 371              foreach ($needreset as $cmid) {
 372                  $completion->reset_all_state($modinfo->get_cm($cmid));
 373              }
 374  
 375              // And notify the user of the result.
 376              \core\notification::add(get_string('activitycompletionupdated', 'core_completion'), \core\notification::SUCCESS);
 377          }
 378      }
 379  
 380      /**
 381       * Applies new completion rules to one course module
 382       *
 383       * @param \cm_info $cm
 384       * @param array $data
 385       * @param bool $updateinstance if we need to update the instance table of the module (i.e. 'assign', 'forum', etc.) -
 386       *      if no module-specific completion rules were added to the form, update of the module table is not needed.
 387       * @return bool if module was updated
 388       */
 389      protected function apply_completion_cm(\cm_info $cm, $data, $updateinstance) {
 390          global $DB;
 391  
 392          $defaults = [
 393              'completion' => COMPLETION_DISABLED, 'completionview' => COMPLETION_VIEW_NOT_REQUIRED,
 394              'completionexpected' => 0, 'completiongradeitemnumber' => null,
 395              'completionpassgrade' => 0
 396          ];
 397  
 398          $data += ['completion' => $cm->completion,
 399              'completionexpected' => $cm->completionexpected,
 400              'completionview' => $cm->completionview];
 401  
 402          if ($cm->completion == $data['completion'] && $cm->completion == COMPLETION_TRACKING_NONE) {
 403              // If old and new completion are both "none" - no changes are needed.
 404              return false;
 405          }
 406  
 407          if ($cm->completion == $data['completion'] && $cm->completion == COMPLETION_TRACKING_NONE &&
 408                  $cm->completionexpected == $data['completionexpected']) {
 409              // If old and new completion are both "manual" and completion expected date is not changed - no changes are needed.
 410              return false;
 411          }
 412  
 413          if (array_key_exists('completionusegrade', $data)) {
 414              // Convert the 'use grade' checkbox into a grade-item number: 0 if checked, null if not.
 415              $data['completiongradeitemnumber'] = !empty($data['completionusegrade']) ? 0 : null;
 416              unset($data['completionusegrade']);
 417          } else {
 418              // Completion grade item number is classified in mod_edit forms as 'use grade'.
 419              $data['completionusegrade'] = is_null($cm->completiongradeitemnumber) ? 0 : 1;
 420              $data['completiongradeitemnumber'] = $cm->completiongradeitemnumber;
 421          }
 422  
 423          // Update module instance table.
 424          if ($updateinstance) {
 425              $moddata = ['id' => $cm->instance, 'timemodified' => time()] + array_diff_key($data, $defaults);
 426              $DB->update_record($cm->modname, $moddata);
 427          }
 428  
 429          // Update course modules table.
 430          $cmdata = ['id' => $cm->id, 'timemodified' => time()] + array_intersect_key($data, $defaults);
 431          $DB->update_record('course_modules', $cmdata);
 432  
 433          \core\event\course_module_updated::create_from_cm($cm, $cm->context)->trigger();
 434  
 435          // We need to reset completion data for this activity.
 436          return true;
 437      }
 438  
 439  
 440      /**
 441       * Saves default completion from edit form to all selected module types
 442       *
 443       * @param stdClass $data data received from the core_completion_bulkedit_form
 444       * @param bool $updatecustomrules if we need to update the custom rules of the module -
 445       *      if no module-specific completion rules were added to the form, update of the module table is not needed.
 446       */
 447      public function apply_default_completion($data, $updatecustomrules) {
 448          global $DB;
 449  
 450          $courseid = $data->id;
 451          // MDL-72375 Unset the id here, it should not be stored in customrules.
 452          unset($data->id);
 453          $coursecontext = context_course::instance($courseid);
 454          if (!$modids = $data->modids) {
 455              return;
 456          }
 457          $defaults = [
 458              'completion' => COMPLETION_DISABLED,
 459              'completionview' => COMPLETION_VIEW_NOT_REQUIRED,
 460              'completionexpected' => 0,
 461              'completionusegrade' => 0,
 462              'completionpassgrade' => 0
 463          ];
 464  
 465          $data = (array)$data;
 466  
 467          if ($updatecustomrules) {
 468              $customdata = array_diff_key($data, $defaults);
 469              $data['customrules'] = $customdata ? json_encode($customdata) : null;
 470              $defaults['customrules'] = null;
 471          }
 472          $data = array_intersect_key($data, $defaults);
 473  
 474          // Get names of the affected modules.
 475          list($modidssql, $params) = $DB->get_in_or_equal($modids);
 476          $params[] = 1;
 477          $modules = $DB->get_records_select_menu('modules', 'id ' . $modidssql . ' and visible = ?', $params, '', 'id, name');
 478  
 479          // Get an associative array of [module_id => course_completion_defaults_id].
 480          list($in, $params) = $DB->get_in_or_equal($modids);
 481          $params[] = $courseid;
 482          $defaultsids = $DB->get_records_select_menu('course_completion_defaults', 'module ' . $in . ' and course = ?', $params, '',
 483                                                        'module, id');
 484  
 485          foreach ($modids as $modid) {
 486              if (!array_key_exists($modid, $modules)) {
 487                  continue;
 488              }
 489              if (isset($defaultsids[$modid])) {
 490                  $DB->update_record('course_completion_defaults', $data + ['id' => $defaultsids[$modid]]);
 491              } else {
 492                  $defaultsids[$modid] = $DB->insert_record('course_completion_defaults', $data + ['course' => $courseid,
 493                                                                                                   'module' => $modid]);
 494              }
 495              // Trigger event.
 496              \core\event\completion_defaults_updated::create([
 497                  'objectid' => $defaultsids[$modid],
 498                  'context' => $coursecontext,
 499                  'other' => ['modulename' => $modules[$modid]],
 500              ])->trigger();
 501          }
 502  
 503          // Add notification.
 504          \core\notification::add(get_string('defaultcompletionupdated', 'completion'), \core\notification::SUCCESS);
 505      }
 506  
 507      /**
 508       * Returns default completion rules for given module type in the given course
 509       *
 510       * @param stdClass $course
 511       * @param stdClass $module
 512       * @param bool $flatten if true all module custom completion rules become properties of the same object,
 513       *   otherwise they can be found as array in ->customdata['customcompletionrules']
 514       * @return stdClass
 515       */
 516      public static function get_default_completion($course, $module, $flatten = true) {
 517          global $DB, $CFG;
 518          if ($data = $DB->get_record('course_completion_defaults', ['course' => $course->id, 'module' => $module->id],
 519              'completion, completionview, completionexpected, completionusegrade, completionpassgrade, customrules')) {
 520              if ($data->customrules && ($customrules = @json_decode($data->customrules, true))) {
 521                  // MDL-72375 This will override activity id for new mods. Skip this field, it is already exposed as courseid.
 522                  unset($customrules['id']);
 523  
 524                  if ($flatten) {
 525                      foreach ($customrules as $key => $value) {
 526                          $data->$key = $value;
 527                      }
 528                  } else {
 529                      $data->customdata['customcompletionrules'] = $customrules;
 530                  }
 531              }
 532              unset($data->customrules);
 533          } else {
 534              $data = new stdClass();
 535              $data->completion = COMPLETION_TRACKING_NONE;
 536              if ($CFG->completiondefault) {
 537                  $completion = new \completion_info(get_fast_modinfo($course->id)->get_course());
 538                  if ($completion->is_enabled() && plugin_supports('mod', $module->name, FEATURE_MODEDIT_DEFAULT_COMPLETION, true)) {
 539                      $data->completion = COMPLETION_TRACKING_MANUAL;
 540                      $data->completionview = 1;
 541                  }
 542              }
 543          }
 544          return $data;
 545      }
 546  }