MDL-50349 scorm: New WS mod_scorm_get_scorms_by_courses
authorJuan Leyva <juanleyvadelgado@gmail.com>
Mon, 1 Jun 2015 11:35:18 +0000 (13:35 +0200)
committerJuan Leyva <juanleyvadelgado@gmail.com>
Thu, 17 Sep 2015 16:16:22 +0000 (18:16 +0200)
lib/db/services.php
mod/scorm/classes/external.php
mod/scorm/db/services.php
mod/scorm/tests/externallib_test.php

index 0d279b0..38ceaa3 100644 (file)
@@ -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',
index 026554d..ef13478 100644 (file)
@@ -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(),
+            )
+        );
+    }
 }
index 929f649..4042a0c 100644 (file)
@@ -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'  => ''
+    )
 );
index 93b5554..6f59c8b 100644 (file)
@@ -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']);
+    }
 }