diff --git a/lib/db/services.php b/lib/db/services.php index 0d279b05507..38ceaa325b8 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -1212,6 +1212,7 @@ $services = array( 'mod_scorm_insert_scorm_tracks', 'mod_scorm_get_scorm_sco_tracks', 'mod_scorm_get_scorm_attempt_count', + 'mod_scorm_get_scorms_by_courses', 'mod_page_view_page', 'mod_resource_view_resource', 'mod_folder_view_folder', diff --git a/mod/scorm/classes/external.php b/mod/scorm/classes/external.php index 026554d6f56..ef13478e482 100644 --- a/mod/scorm/classes/external.php +++ b/mod/scorm/classes/external.php @@ -593,4 +593,196 @@ class mod_scorm_external extends external_api { ) ); } + + /** + * Describes the parameters for get_scorms_by_courses. + * + * @return external_function_parameters + * @since Moodle 3.0 + */ + public static function get_scorms_by_courses_parameters() { + return new external_function_parameters ( + array( + 'courseids' => new external_multiple_structure( + new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array() + ), + ) + ); + } + + /** + * Returns a list of scorms in a provided list of courses, + * if no list is provided all scorms that the user can view will be returned. + * + * @param array $courseids the course ids + * @return array the scorm details + * @since Moodle 3.0 + */ + public static function get_scorms_by_courses($courseids = array()) { + global $CFG; + + $returnedscorms = array(); + $warnings = array(); + + $params = self::validate_parameters(self::get_scorms_by_courses_parameters(), array('courseids' => $courseids)); + + if (empty($params['courseids'])) { + $params['courseids'] = array_keys(enrol_get_my_courses()); + } + + // Ensure there are courseids to loop through. + if (!empty($params['courseids'])) { + + list($courses, $warnings) = external_util::validate_courses($params['courseids']); + + // Get the scorms in this course, this function checks users visibility permissions. + // We can avoid then additional validate_context calls. + $scorms = get_all_instances_in_courses("scorm", $courses); + + $fs = get_file_storage(); + foreach ($scorms as $scorm) { + + $context = context_module::instance($scorm->coursemodule); + + // Entry to return. + $module = array(); + + // First, we return information that any user can see in (or can deduce from) the web interface. + $module['id'] = $scorm->id; + $module['coursemodule'] = $scorm->coursemodule; + $module['course'] = $scorm->course; + $module['name'] = format_string($scorm->name, true, array('context' => $context)); + list($module['intro'], $module['introformat']) = + external_format_text($scorm->intro, $scorm->introformat, $context->id, 'mod_scorm', 'intro', $scorm->id); + + // Check if the SCORM open and return warnings if so. + list($open, $openwarnings) = scorm_get_availability_status($scorm, true, $context); + + if (!$open) { + foreach ($openwarnings as $warningkey => $warningdata) { + $warnings[] = array( + 'item' => 'scorm', + 'itemid' => $scorm->id, + 'warningcode' => $warningkey, + 'message' => get_string($warningkey, 'scorm', $warningdata) + ); + } + } else { + $module['packagesize'] = 0; + // SCORM size. + if ($scorm->scormtype === SCORM_TYPE_LOCAL or $scorm->scormtype === SCORM_TYPE_LOCALSYNC) { + if ($packagefile = $fs->get_file($context->id, 'mod_scorm', 'package', 0, '/', $scorm->reference)) { + $module['packagesize'] = $packagefile->get_filesize(); + // Download URL. + $module['packageurl'] = moodle_url::make_webservice_pluginfile_url( + $context->id, 'mod_scorm', 'package', 0, '/', $scorm->reference)->out(false); + } + } + + $viewablefields = array('version', 'maxgrade', 'grademethod', 'whatgrade', 'maxattempt', 'forcecompleted', + 'forcenewattempt', 'lastattemptlock', 'displayattemptstatus', 'displaycoursestructure', + 'sha1hash', 'md5hash', 'revision', 'launch', 'skipview', 'hidebrowse', 'hidetoc', 'nav', + 'navpositionleft', 'navpositiontop', 'auto', 'popup', 'width', 'height', 'timeopen', + 'timeclose', 'displayactivityname', 'scormtype', 'reference'); + + // Check additional permissions for returning optional private settings. + if (has_capability('moodle/course:manageactivities', $context)) { + + $additionalfields = array('updatefreq', 'options', 'completionstatusrequired', 'completionscorerequired', + 'autocommit', 'timemodified', 'section', 'visible', 'groupmode', 'groupingid'); + $viewablefields = array_merge($viewablefields, $additionalfields); + + } + + foreach ($viewablefields as $field) { + $module[$field] = $scorm->{$field}; + } + } + + $returnedscorms[] = $module; + } + } + + $result = array(); + $result['scorms'] = $returnedscorms; + $result['warnings'] = $warnings; + return $result; + } + + /** + * Describes the get_scorms_by_courses return value. + * + * @return external_single_structure + * @since Moodle 3.0 + */ + public static function get_scorms_by_courses_returns() { + + return new external_single_structure( + array( + 'scorms' => new external_multiple_structure( + new external_single_structure( + array( + 'id' => new external_value(PARAM_INT, 'SCORM id'), + 'coursemodule' => new external_value(PARAM_INT, 'Course module id'), + 'course' => new external_value(PARAM_INT, 'Course id'), + 'name' => new external_value(PARAM_TEXT, 'SCORM name'), + 'intro' => new external_value(PARAM_RAW, 'The SCORM intro'), + 'introformat' => new external_format_value('intro'), + 'packagesize' => new external_value(PARAM_INT, 'SCORM zip package size', VALUE_OPTIONAL), + 'packageurl' => new external_value(PARAM_URL, 'SCORM zip package URL', VALUE_OPTIONAL), + 'version' => new external_value(PARAM_NOTAGS, 'SCORM version (SCORM_12, SCORM_13, SCORM_AICC)', + VALUE_OPTIONAL), + 'maxgrade' => new external_value(PARAM_INT, 'Max grade', VALUE_OPTIONAL), + 'grademethod' => new external_value(PARAM_INT, 'Grade method', VALUE_OPTIONAL), + 'whatgrade' => new external_value(PARAM_INT, 'What grade', VALUE_OPTIONAL), + 'maxattempt' => new external_value(PARAM_INT, 'Maximum number of attemtps', VALUE_OPTIONAL), + 'forcecompleted' => new external_value(PARAM_BOOL, 'Status current attempt is forced to "completed"', + VALUE_OPTIONAL), + 'forcenewattempt' => new external_value(PARAM_BOOL, 'Hides the "Start new attempt" checkbox', + VALUE_OPTIONAL), + 'lastattemptlock' => new external_value(PARAM_BOOL, 'Prevents to launch new attempts once finished', + VALUE_OPTIONAL), + 'displayattemptstatus' => new external_value(PARAM_BOOL, 'Display attempts status', VALUE_OPTIONAL), + 'displaycoursestructure' => new external_value(PARAM_BOOL, 'Display contents structure', + VALUE_OPTIONAL), + 'sha1hash' => new external_value(PARAM_NOTAGS, 'Package content or ext path hash', VALUE_OPTIONAL), + 'md5hash' => new external_value(PARAM_NOTAGS, 'MD5 Hash of package file', VALUE_OPTIONAL), + 'revision' => new external_value(PARAM_INT, 'Revison number', VALUE_OPTIONAL), + 'launch' => new external_value(PARAM_INT, 'First content to launch', VALUE_OPTIONAL), + 'skipview' => new external_value(PARAM_BOOL, 'Skip or not content structure page', VALUE_OPTIONAL), + 'hidebrowse' => new external_value(PARAM_BOOL, 'Disable preview mode?', VALUE_OPTIONAL), + 'hidetoc' => new external_value(PARAM_BOOL, 'Display or not course structure in player', + VALUE_OPTIONAL), + 'nav' => new external_value(PARAM_INT, 'Show navigation buttons', VALUE_OPTIONAL), + 'navpositionleft' => new external_value(PARAM_INT, 'Navigation position left', VALUE_OPTIONAL), + 'navpositiontop' => new external_value(PARAM_INT, 'Navigation position top', VALUE_OPTIONAL), + 'auto' => new external_value(PARAM_BOOL, 'Auto continue?', VALUE_OPTIONAL), + 'popup' => new external_value(PARAM_INT, 'Display in current or new window', VALUE_OPTIONAL), + 'width' => new external_value(PARAM_INT, 'Frame width', VALUE_OPTIONAL), + 'height' => new external_value(PARAM_INT, 'Frame height', VALUE_OPTIONAL), + 'timeopen' => new external_value(PARAM_INT, 'Available from', VALUE_OPTIONAL), + 'timeclose' => new external_value(PARAM_INT, 'Available to', VALUE_OPTIONAL), + 'displayactivityname' => new external_value(PARAM_BOOL, 'Display the activity name above the player?', + VALUE_OPTIONAL), + 'scormtype' => new external_value(PARAM_ALPHA, 'SCORM type', VALUE_OPTIONAL), + 'reference' => new external_value(PARAM_NOTAGS, 'Reference to the package', VALUE_OPTIONAL), + 'updatefreq' => new external_value(PARAM_INT, 'Auto-update frequency for remote packages', + VALUE_OPTIONAL), + 'options' => new external_value(PARAM_RAW, 'Additional options', VALUE_OPTIONAL), + 'completionstatusrequired' => new external_value(PARAM_INT, 'Status passed/completed required?', + VALUE_OPTIONAL), + 'completionscorerequired' => new external_value(PARAM_INT, 'Minimum score required', VALUE_OPTIONAL), + 'autocommit' => new external_value(PARAM_BOOL, 'Save track data automatically?', VALUE_OPTIONAL), + 'timemodified' => new external_value(PARAM_INT, 'Time of last modification', VALUE_OPTIONAL), + 'section' => new external_value(PARAM_INT, 'Course section id', VALUE_OPTIONAL), + 'visible' => new external_value(PARAM_BOOL, 'Visible', VALUE_OPTIONAL), + 'groupmode' => new external_value(PARAM_INT, 'Group mode', VALUE_OPTIONAL), + 'groupingid' => new external_value(PARAM_INT, 'Group id', VALUE_OPTIONAL), + ), 'SCORM' + ) + ), + 'warnings' => new external_warnings(), + ) + ); + } } diff --git a/mod/scorm/db/services.php b/mod/scorm/db/services.php index 929f649b903..4042a0c2c97 100644 --- a/mod/scorm/db/services.php +++ b/mod/scorm/db/services.php @@ -76,4 +76,13 @@ $functions = array( 'type' => 'read', 'capabilities' => '' ), + + 'mod_scorm_get_scorms_by_courses' => array( + 'classname' => 'mod_scorm_external', + 'methodname' => 'get_scorms_by_courses', + 'description' => 'Returns a list of scorm instances in a provided set of courses, if + no courses are provided then all the scorm instances the user has access to will be returned.', + 'type' => 'read', + 'capabilities' => '' + ) ); diff --git a/mod/scorm/tests/externallib_test.php b/mod/scorm/tests/externallib_test.php index 93b555484e8..6f59c8b536a 100644 --- a/mod/scorm/tests/externallib_test.php +++ b/mod/scorm/tests/externallib_test.php @@ -519,4 +519,210 @@ class mod_scorm_external_testcase extends externallib_advanced_testcase { $this->assertEquals('invaliduser', $e->errorcode); } } + + /* + * Test get scorms by courses + */ + public function test_mod_scorm_get_scorms_by_courses() { + global $DB; + + $this->resetAfterTest(true); + + // Create users. + $student = self::getDataGenerator()->create_user(); + $teacher = self::getDataGenerator()->create_user(); + + // Set to the student user. + self::setUser($student); + + // Create courses to add the modules. + $course1 = self::getDataGenerator()->create_course(); + $course2 = self::getDataGenerator()->create_course(); + + // First scorm. + $record = new stdClass(); + $record->introformat = FORMAT_HTML; + $record->course = $course1->id; + $scorm1 = self::getDataGenerator()->create_module('scorm', $record); + + // Second scorm. + $record = new stdClass(); + $record->introformat = FORMAT_HTML; + $record->course = $course2->id; + $scorm2 = self::getDataGenerator()->create_module('scorm', $record); + + $studentrole = $DB->get_record('role', array('shortname' => 'student')); + $teacherrole = $DB->get_record('role', array('shortname' => 'editingteacher')); + + // Users enrolments. + $this->getDataGenerator()->enrol_user($student->id, $course1->id, $studentrole->id, 'manual'); + $this->getDataGenerator()->enrol_user($teacher->id, $course1->id, $teacherrole->id, 'manual'); + + // Execute real Moodle enrolment as we'll call unenrol() method on the instance later. + $enrol = enrol_get_plugin('manual'); + $enrolinstances = enrol_get_instances($course2->id, true); + foreach ($enrolinstances as $courseenrolinstance) { + if ($courseenrolinstance->enrol == "manual") { + $instance2 = $courseenrolinstance; + break; + } + } + $enrol->enrol_user($instance2, $student->id, $studentrole->id); + + $returndescription = mod_scorm_external::get_scorms_by_courses_returns(); + + // Test open/close dates. + + $timenow = time(); + $scorm1->timeopen = $timenow - DAYSECS; + $scorm1->timeclose = $timenow - HOURSECS; + $DB->update_record('scorm', $scorm1); + + $result = mod_scorm_external::get_scorms_by_courses(array($course1->id)); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertCount(1, $result['warnings']); + // Only 'id', 'coursemodule', 'course', 'name', 'intro', 'introformat'. + $this->assertCount(6, $result['scorms'][0]); + $this->assertEquals('expired', $result['warnings'][0]['warningcode']); + + $scorm1->timeopen = $timenow + DAYSECS; + $scorm1->timeclose = $scorm1->timeopen + DAYSECS; + $DB->update_record('scorm', $scorm1); + + $result = mod_scorm_external::get_scorms_by_courses(array($course1->id)); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertCount(1, $result['warnings']); + // Only 'id', 'coursemodule', 'course', 'name', 'intro', 'introformat'. + $this->assertCount(6, $result['scorms'][0]); + $this->assertEquals('notopenyet', $result['warnings'][0]['warningcode']); + + // Reset times. + $scorm1->timeopen = 0; + $scorm1->timeclose = 0; + $DB->update_record('scorm', $scorm1); + + // Create what we expect to be returned when querying the two courses. + // First for the student user. + $expectedfields = array('id', 'coursemodule', 'course', 'name', 'intro', 'introformat', 'version', 'maxgrade', + 'grademethod', 'whatgrade', 'maxattempt', 'forcecompleted', 'forcenewattempt', 'lastattemptlock', + 'displayattemptstatus', 'displaycoursestructure', 'sha1hash', 'md5hash', 'revision', 'launch', + 'skipview', 'hidebrowse', 'hidetoc', 'nav', 'navpositionleft', 'navpositiontop', 'auto', + 'popup', 'width', 'height', 'timeopen', 'timeclose', 'displayactivityname', 'packagesize', + 'packageurl', 'scormtype', 'reference'); + + // Add expected coursemodule and data. + $scorm1->coursemodule = $scorm1->cmid; + $scorm1->section = 0; + $scorm1->visible = true; + $scorm1->groupmode = 0; + $scorm1->groupingid = 0; + + $scorm2->coursemodule = $scorm2->cmid; + $scorm2->section = 0; + $scorm2->visible = true; + $scorm2->groupmode = 0; + $scorm2->groupingid = 0; + + // SCORM size. The same package is used in both SCORMs. + $scormcontext1 = context_module::instance($scorm1->cmid); + $scormcontext2 = context_module::instance($scorm2->cmid); + $fs = get_file_storage(); + $packagefile = $fs->get_file($scormcontext1->id, 'mod_scorm', 'package', 0, '/', $scorm1->reference); + $packagesize = $packagefile->get_filesize(); + + $packageurl1 = moodle_url::make_webservice_pluginfile_url( + $scormcontext1->id, 'mod_scorm', 'package', 0, '/', $scorm1->reference)->out(false); + $packageurl2 = moodle_url::make_webservice_pluginfile_url( + $scormcontext2->id, 'mod_scorm', 'package', 0, '/', $scorm2->reference)->out(false); + + $scorm1->packagesize = $packagesize; + $scorm1->packageurl = $packageurl1; + $scorm2->packagesize = $packagesize; + $scorm2->packageurl = $packageurl2; + + $expected1 = array(); + $expected2 = array(); + foreach ($expectedfields as $field) { + + // Since we return the fields used as boolean as PARAM_BOOL instead PARAM_INT we need to force casting here. + // From the returned fields definition we obtain the type expected for the field. + $fieldtype = $returndescription->keys['scorms']->content->keys[$field]->type; + if ($fieldtype == PARAM_BOOL) { + $expected1[$field] = (bool) $scorm1->{$field}; + $expected2[$field] = (bool) $scorm2->{$field}; + } else { + $expected1[$field] = $scorm1->{$field}; + $expected2[$field] = $scorm2->{$field}; + } + } + + $expectedscorms = array(); + $expectedscorms[] = $expected2; + $expectedscorms[] = $expected1; + + // Call the external function passing course ids. + $result = mod_scorm_external::get_scorms_by_courses(array($course2->id, $course1->id)); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertEquals($expectedscorms, $result['scorms']); + + // Call the external function without passing course id. + $result = mod_scorm_external::get_scorms_by_courses(); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertEquals($expectedscorms, $result['scorms']); + + // Unenrol user from second course and alter expected scorms. + $enrol->unenrol_user($instance2, $student->id); + array_shift($expectedscorms); + + // Call the external function without passing course id. + $result = mod_scorm_external::get_scorms_by_courses(); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertEquals($expectedscorms, $result['scorms']); + + // Call for the second course we unenrolled the user from, expected warning. + $result = mod_scorm_external::get_scorms_by_courses(array($course2->id)); + $this->assertCount(1, $result['warnings']); + $this->assertEquals('1', $result['warnings'][0]['warningcode']); + $this->assertEquals($course2->id, $result['warnings'][0]['itemid']); + + // Now, try as a teacher for getting all the additional fields. + self::setUser($teacher); + + $additionalfields = array('updatefreq', 'timemodified', 'options', + 'completionstatusrequired', 'completionscorerequired', 'autocommit', + 'section', 'visible', 'groupmode', 'groupingid'); + + foreach ($additionalfields as $field) { + $fieldtype = $returndescription->keys['scorms']->content->keys[$field]->type; + + if ($fieldtype == PARAM_BOOL) { + $expectedscorms[0][$field] = (bool) $scorm1->{$field}; + } else { + $expectedscorms[0][$field] = $scorm1->{$field}; + } + } + + $result = mod_scorm_external::get_scorms_by_courses(); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertEquals($expectedscorms, $result['scorms']); + + // Even with the SCORM closed in time teacher should retrieve the info. + $scorm1->timeopen = $timenow - DAYSECS; + $scorm1->timeclose = $timenow - HOURSECS; + $DB->update_record('scorm', $scorm1); + + $expectedscorms[0]['timeopen'] = $scorm1->timeopen; + $expectedscorms[0]['timeclose'] = $scorm1->timeclose; + + $result = mod_scorm_external::get_scorms_by_courses(); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertEquals($expectedscorms, $result['scorms']); + + // Admin also should get all the information. + self::setAdminUser(); + + $result = mod_scorm_external::get_scorms_by_courses(array($course1->id)); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertEquals($expectedscorms, $result['scorms']); + } }