diff --git a/mod/workshop/classes/external.php b/mod/workshop/classes/external.php new file mode 100644 index 00000000000..caaf27d88c1 --- /dev/null +++ b/mod/workshop/classes/external.php @@ -0,0 +1,129 @@ +. + +/** + * Workshop external API + * + * @package mod_workshop + * @category external + * @copyright 2017 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.4 + */ + +defined('MOODLE_INTERNAL') || die; + +require_once("$CFG->libdir/externallib.php"); + +use mod_workshop\external\workshop_summary_exporter; + +/** + * Workshop external functions + * + * @package mod_workshop + * @category external + * @copyright 2017 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.4 + */ +class mod_workshop_external extends external_api { + + /** + * Describes the parameters for get_workshops_by_courses. + * + * @return external_function_parameters + * @since Moodle 3.4 + */ + public static function get_workshops_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 workshops in a provided list of courses. + * If no list is provided all workshops that the user can view will be returned. + * + * @param array $courseids course ids + * @return array of warnings and workshops + * @since Moodle 3.4 + */ + public static function get_workshops_by_courses($courseids = array()) { + global $PAGE; + + $warnings = array(); + $returnedworkshops = array(); + + $params = array( + 'courseids' => $courseids, + ); + $params = self::validate_parameters(self::get_workshops_by_courses_parameters(), $params); + + $mycourses = array(); + if (empty($params['courseids'])) { + $mycourses = enrol_get_my_courses(); + $params['courseids'] = array_keys($mycourses); + } + + // Ensure there are courseids to loop through. + if (!empty($params['courseids'])) { + + list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses); + $output = $PAGE->get_renderer('core'); + + // Get the workshops in this course, this function checks users visibility permissions. + // We can avoid then additional validate_context calls. + $workshops = get_all_instances_in_courses("workshop", $courses); + foreach ($workshops as $workshop) { + + $context = context_module::instance($workshop->coursemodule); + // Remove fields that are not from the workshop (added by get_all_instances_in_courses). + unset($workshop->coursemodule, $workshop->context, $workshop->visible, $workshop->section, $workshop->groupmode, + $workshop->groupingid); + + $exporter = new workshop_summary_exporter($workshop, array('context' => $context)); + $returnedworkshops[] = $exporter->export($output); + } + } + + $result = array( + 'workshops' => $returnedworkshops, + 'warnings' => $warnings + ); + return $result; + } + + /** + * Describes the get_workshops_by_courses return value. + * + * @return external_single_structure + * @since Moodle 3.4 + */ + public static function get_workshops_by_courses_returns() { + return new external_single_structure( + array( + 'workshops' => new external_multiple_structure( + workshop_summary_exporter::get_read_structure() + ), + 'warnings' => new external_warnings(), + ) + ); + } +} diff --git a/mod/workshop/classes/external/workshop_summary_exporter.php b/mod/workshop/classes/external/workshop_summary_exporter.php new file mode 100644 index 00000000000..bbacd5cf172 --- /dev/null +++ b/mod/workshop/classes/external/workshop_summary_exporter.php @@ -0,0 +1,355 @@ +. + +/** + * Class for exporting partial workshop data. + * + * @package mod_workshop + * @copyright 2017 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +namespace mod_workshop\external; +defined('MOODLE_INTERNAL') || die(); + +use core\external\exporter; +use renderer_base; +use external_util; +use external_files; + +/** + * Class for exporting partial workshop data (some fields are only viewable by admins). + * + * @copyright 2017 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +class workshop_summary_exporter extends exporter { + + protected static function define_properties() { + + return array( + 'id' => array( + 'type' => PARAM_INT, + 'description' => 'The primary key of the record.', + ), + 'course' => array( + 'type' => PARAM_INT, + 'description' => 'Course id this workshop is part of.', + ), + 'name' => array( + 'type' => PARAM_TEXT, + 'description' => 'Workshop name.', + ), + 'intro' => array( + 'default' => '', + 'type' => PARAM_RAW, + 'description' => 'Workshop introduction text.', + 'null' => NULL_ALLOWED, + ), + 'introformat' => array( + 'choices' => array(FORMAT_HTML, FORMAT_MOODLE, FORMAT_PLAIN, FORMAT_MARKDOWN), + 'type' => PARAM_INT, + 'default' => FORMAT_MOODLE, + 'description' => 'Workshop intro text format.', + ), + 'instructauthors' => array( + 'type' => PARAM_RAW, + 'description' => 'Instructions for the submission phase.', + 'optional' => true, + 'null' => NULL_ALLOWED, + ), + 'instructauthorsformat' => array( + 'choices' => array(FORMAT_HTML, FORMAT_MOODLE, FORMAT_PLAIN, FORMAT_MARKDOWN), + 'type' => PARAM_INT, + 'default' => FORMAT_MOODLE, + 'description' => 'Instructions text format.', + ), + 'instructreviewers' => array( + 'type' => PARAM_RAW, + 'description' => 'Instructions for the assessment phase.', + 'optional' => true, + 'null' => NULL_ALLOWED, + ), + 'instructreviewersformat' => array( + 'choices' => array(FORMAT_HTML, FORMAT_MOODLE, FORMAT_PLAIN, FORMAT_MARKDOWN), + 'type' => PARAM_INT, + 'default' => FORMAT_MOODLE, + 'description' => 'Instructions text format.', + ), + 'timemodified' => array( + 'type' => PARAM_INT, + 'description' => 'The timestamp when the module was modified.', + 'optional' => true, + ), + 'phase' => array( + 'type' => PARAM_INT, + 'default' => 0, + 'description' => 'The current phase of workshop (0 = not available, 1 = submission, 2 = assessment, 3 = closed).', + 'optional' => true, + ), + 'useexamples' => array( + 'type' => PARAM_BOOL, + 'default' => false, + 'description' => 'Optional feature: students practise evaluating on example submissions from teacher.', + 'optional' => true, + ), + 'usepeerassessment' => array( + 'type' => PARAM_BOOL, + 'default' => false, + 'description' => 'Optional feature: students perform peer assessment of others\' work.', + 'optional' => true, + ), + 'useselfassessment' => array( + 'type' => PARAM_BOOL, + 'default' => false, + 'description' => 'Optional feature: students perform self assessment of their own work.', + 'optional' => true, + ), + 'grade' => array( + 'type' => PARAM_FLOAT, + 'default' => 80, + 'description' => 'The maximum grade for submission.', + 'optional' => true, + ), + 'gradinggrade' => array( + 'type' => PARAM_FLOAT, + 'default' => 20, + 'description' => 'The maximum grade for assessment.', + 'optional' => true, + ), + 'strategy' => array( + 'type' => PARAM_PLUGIN, + 'description' => 'The type of the current grading strategy used in this workshop.', + 'optional' => true, + ), + 'evaluation' => array( + 'type' => PARAM_PLUGIN, + 'description' => 'The recently used grading evaluation method.', + 'optional' => true, + ), + 'gradedecimals' => array( + 'type' => PARAM_INT, + 'default' => 0, + 'description' => 'Number of digits that should be shown after the decimal point when displaying grades.', + 'optional' => true, + ), + 'nattachments' => array( + 'type' => PARAM_INT, + 'default' => 0, + 'description' => 'Number of required submission attachments.', + 'optional' => true, + ), + 'submissionfiletypes' => array( + 'type' => PARAM_RAW, + 'description' => 'Comma separated list of file extensions.', + 'optional' => true, + 'null' => NULL_ALLOWED, + ), + 'latesubmissions' => array( + 'type' => PARAM_BOOL, + 'default' => false, + 'description' => 'Allow submitting the work after the deadline.', + 'optional' => true, + ), + 'maxbytes' => array( + 'type' => PARAM_INT, + 'default' => 100000, + 'description' => 'Maximum size of the one attached file.', + 'optional' => true, + ), + 'examplesmode' => array( + 'type' => PARAM_INT, + 'default' => 0, + 'description' => '0 = example assessments are voluntary, 1 = examples must be assessed before submission, + 2 = examples are available after own submission and must be assessed before peer/self assessment phase.', + 'optional' => true, + ), + 'submissionstart' => array( + 'type' => PARAM_INT, + 'default' => 0, + 'description' => '0 = will be started manually, greater than 0 the timestamp of the start of the submission phase.', + 'optional' => true, + ), + 'submissionend' => array( + 'type' => PARAM_INT, + 'default' => 0, + 'description' => '0 = will be closed manually, greater than 0 the timestamp of the end of the submission phase.', + 'optional' => true, + ), + 'assessmentstart' => array( + 'type' => PARAM_INT, + 'default' => 0, + 'description' => '0 = will be started manually, greater than 0 the timestamp of the start of the assessment phase.', + 'optional' => true, + ), + 'assessmentend' => array( + 'type' => PARAM_INT, + 'default' => 0, + 'description' => '0 = will be closed manually, greater than 0 the timestamp of the end of the assessment phase.', + 'optional' => true, + ), + 'phaseswitchassessment' => array( + 'type' => PARAM_BOOL, + 'default' => false, + 'description' => 'Automatically switch to the assessment phase after the submissions deadline.', + 'optional' => true, + ), + 'conclusion' => array( + 'type' => PARAM_RAW, + 'description' => 'A text to be displayed at the end of the workshop.', + 'optional' => true, + 'null' => NULL_ALLOWED, + ), + 'conclusionformat' => array( + 'choices' => array(FORMAT_HTML, FORMAT_MOODLE, FORMAT_PLAIN, FORMAT_MARKDOWN), + 'type' => PARAM_INT, + 'default' => FORMAT_MOODLE, + 'description' => 'Workshop conclusion text format.', + ), + 'overallfeedbackmode' => array( + 'type' => PARAM_INT, + 'default' => 1, + 'description' => 'Mode of the overall feedback support.', + 'optional' => true, + ), + 'overallfeedbackfiles' => array( + 'type' => PARAM_INT, + 'default' => 0, + 'description' => 'Number of allowed attachments to the overall feedback.', + 'optional' => true, + ), + 'overallfeedbackfiletypes' => array( + 'type' => PARAM_RAW, + 'description' => 'Comma separated list of file extensions.', + 'optional' => true, + 'null' => NULL_ALLOWED, + ), + 'overallfeedbackmaxbytes' => array( + 'type' => PARAM_INT, + 'default' => 100000, + 'description' => 'Maximum size of one file attached to the overall feedback.', + 'optional' => true, + ), + ); + } + + protected static function define_related() { + return array( + 'context' => 'context' + ); + } + + protected static function define_other_properties() { + return array( + 'coursemodule' => array( + 'type' => PARAM_INT + ), + 'introfiles' => array( + 'type' => external_files::get_properties_for_exporter(), + 'multiple' => true + ), + 'instructauthorsfiles' => array( + 'type' => external_files::get_properties_for_exporter(), + 'multiple' => true, + 'optional' => true + ), + 'instructreviewersfiles' => array( + 'type' => external_files::get_properties_for_exporter(), + 'multiple' => true, + 'optional' => true + ), + 'conclusionfiles' => array( + 'type' => external_files::get_properties_for_exporter(), + 'multiple' => true, + 'optional' => true + ), + ); + } + + protected function get_other_values(renderer_base $output) { + $context = $this->related['context']; + + $values = array( + 'coursemodule' => $context->instanceid, + ); + + $values['introfiles'] = external_util::get_area_files($context->id, 'mod_workshop', 'intro', false, false); + + if (!empty($this->data->instructauthors)) { + $values['instructauthorsfiles'] = external_util::get_area_files($context->id, 'mod_workshop', 'instructauthors'); + } + + if (!empty($this->data->instructreviewers)) { + $values['instructreviewersfiles'] = external_util::get_area_files($context->id, 'mod_workshop', 'instructreviewers'); + } + + if (!empty($this->data->conclusion)) { + $values['conclusionfiles'] = external_util::get_area_files($context->id, 'mod_workshop', 'conclusion'); + } + + return $values; + } + + /** + * Get the formatting parameters for the intro. + * + * @return array with the formatting parameters + */ + protected function get_format_parameters_for_intro() { + return [ + 'component' => 'mod_workshop', + 'filearea' => 'intro', + ]; + } + + /** + * Get the formatting parameters for the instructauthors. + * + * @return array with the formatting parameters + */ + protected function get_format_parameters_for_instructauthors() { + return [ + 'component' => 'mod_workshop', + 'filearea' => 'instructauthors', + 'itemid' => 0 + ]; + } + + /** + * Get the formatting parameters for the instructreviewers. + * + * @return array with the formatting parameters + */ + protected function get_format_parameters_for_instructreviewers() { + return [ + 'component' => 'mod_workshop', + 'filearea' => 'instructreviewers', + 'itemid' => 0 + ]; + } + + /** + * Get the formatting parameters for the conclusion. + * + * @return array with the formatting parameters + */ + protected function get_format_parameters_for_conclusion() { + return [ + 'component' => 'mod_workshop', + 'filearea' => 'conclusion', + 'itemid' => 0 + ]; + } +} diff --git a/mod/workshop/db/install.xml b/mod/workshop/db/install.xml index 3dc972f4583..5884eb91394 100644 --- a/mod/workshop/db/install.xml +++ b/mod/workshop/db/install.xml @@ -39,7 +39,7 @@ - + diff --git a/mod/workshop/db/services.php b/mod/workshop/db/services.php new file mode 100644 index 00000000000..e44e7cb7c95 --- /dev/null +++ b/mod/workshop/db/services.php @@ -0,0 +1,40 @@ +. + +/** + * Workshop external functions and service definitions. + * + * @package mod_workshop + * @category external + * @copyright 2017 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.4 + */ + +defined('MOODLE_INTERNAL') || die; + +$functions = array( + + 'mod_workshop_get_workshops_by_courses' => array( + 'classname' => 'mod_workshop_external', + 'methodname' => 'get_workshops_by_courses', + 'description' => 'Returns a list of workshops in a provided list of courses, if no list is provided all workshops that + the user can view will be returned.', + 'type' => 'read', + 'capabilities' => 'mod/workshop:view', + 'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE), + ), +); diff --git a/mod/workshop/tests/external_test.php b/mod/workshop/tests/external_test.php new file mode 100644 index 00000000000..63e8fd0d66a --- /dev/null +++ b/mod/workshop/tests/external_test.php @@ -0,0 +1,183 @@ +. + +/** + * Workshop module external functions tests + * + * @package mod_workshop + * @category external + * @copyright 2017 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.4 + */ + +defined('MOODLE_INTERNAL') || die(); + +global $CFG; + +require_once($CFG->dirroot . '/webservice/tests/helpers.php'); +require_once($CFG->dirroot . '/mod/workshop/lib.php'); + +use mod_workshop\external\workshop_summary_exporter; + +/** + * Workshop module external functions tests + * + * @package mod_workshop + * @category external + * @copyright 2017 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.4 + */ +class mod_workshop_external_testcase extends externallib_advanced_testcase { + + /** @var stdClass course object */ + private $course; + /** @var stdClass workshop object */ + private $workshop; + /** @var stdClass context object */ + private $context; + /** @var stdClass cm object */ + private $cm; + /** @var stdClass student object */ + private $student; + /** @var stdClass teacher object */ + private $teacher; + /** @var stdClass student role object */ + private $studentrole; + /** @var stdClass teacher role object */ + private $teacherrole; + + /** + * Set up for every test + */ + public function setUp() { + global $DB; + $this->resetAfterTest(); + $this->setAdminUser(); + + // Setup test data. + $this->course = $this->getDataGenerator()->create_course(); + $this->workshop = $this->getDataGenerator()->create_module('workshop', array('course' => $this->course->id)); + $this->context = context_module::instance($this->workshop->cmid); + $this->cm = get_coursemodule_from_instance('workshop', $this->workshop->id); + + // Create users. + $this->student = self::getDataGenerator()->create_user(); + $this->teacher = self::getDataGenerator()->create_user(); + + // Users enrolments. + $this->studentrole = $DB->get_record('role', array('shortname' => 'student')); + $this->teacherrole = $DB->get_record('role', array('shortname' => 'editingteacher')); + $this->getDataGenerator()->enrol_user($this->student->id, $this->course->id, $this->studentrole->id, 'manual'); + $this->getDataGenerator()->enrol_user($this->teacher->id, $this->course->id, $this->teacherrole->id, 'manual'); + } + + /** + * Test test_mod_workshop_get_workshops_by_courses + */ + public function test_mod_workshop_get_workshops_by_courses() { + global $DB; + + // Create additional course. + $course2 = self::getDataGenerator()->create_course(); + + // Second workshop. + $record = new stdClass(); + $record->course = $course2->id; + $workshop2 = self::getDataGenerator()->create_module('workshop', $record); + + // 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, $this->student->id, $this->studentrole->id); + + self::setUser($this->student); + + $returndescription = mod_workshop_external::get_workshops_by_courses_returns(); + + // Create what we expect to be returned when querying the two courses. + $properties = workshop_summary_exporter::read_properties_definition(); + $expectedfields = array_keys($properties); + + // Add expected coursemodule and data. + $workshop1 = $this->workshop; + $workshop1->coursemodule = $workshop1->cmid; + $workshop1->introformat = 1; + $workshop1->introfiles = []; + $workshop1->instructauthorsfiles = []; + $workshop1->instructauthorsformat = 1; + $workshop1->instructreviewersfiles = []; + $workshop1->instructreviewersformat = 1; + $workshop1->conclusionfiles = []; + $workshop1->conclusionformat = 1; + + $workshop2->coursemodule = $workshop2->cmid; + $workshop2->introformat = 1; + $workshop2->introfiles = []; + $workshop2->instructauthorsfiles = []; + $workshop2->instructauthorsformat = 1; + $workshop2->instructreviewersfiles = []; + $workshop2->instructreviewersformat = 1; + $workshop2->conclusionfiles = []; + $workshop2->conclusionformat = 1; + + foreach ($expectedfields as $field) { + if (!empty($properties[$field]) && $properties[$field]['type'] == PARAM_BOOL) { + $workshop1->{$field} = (bool) $workshop1->{$field}; + $workshop2->{$field} = (bool) $workshop2->{$field}; + } + $expected1[$field] = $workshop1->{$field}; + $expected2[$field] = $workshop2->{$field}; + } + + $expectedworkshops = array($expected2, $expected1); + + // Call the external function passing course ids. + $result = mod_workshop_external::get_workshops_by_courses(array($course2->id, $this->course->id)); + $result = external_api::clean_returnvalue($returndescription, $result); + + $this->assertEquals($expectedworkshops, $result['workshops']); + $this->assertCount(0, $result['warnings']); + + // Call the external function without passing course id. + $result = mod_workshop_external::get_workshops_by_courses(); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertEquals($expectedworkshops, $result['workshops']); + $this->assertCount(0, $result['warnings']); + + // Unenrol user from second course and alter expected workshops. + $enrol->unenrol_user($instance2, $this->student->id); + array_shift($expectedworkshops); + + // Call the external function without passing course id. + $result = mod_workshop_external::get_workshops_by_courses(); + $result = external_api::clean_returnvalue($returndescription, $result); + $this->assertEquals($expectedworkshops, $result['workshops']); + + // Call for the second course we unenrolled the user from, expected warning. + $result = mod_workshop_external::get_workshops_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']); + } +} diff --git a/mod/workshop/version.php b/mod/workshop/version.php index 4290f51744b..b35c6fdf53c 100644 --- a/mod/workshop/version.php +++ b/mod/workshop/version.php @@ -24,7 +24,7 @@ defined('MOODLE_INTERNAL') || die(); -$plugin->version = 2017051500; // The current module version (YYYYMMDDXX) +$plugin->version = 2017051501; // The current module version (YYYYMMDDXX) $plugin->requires = 2017050500; // Requires this Moodle version. $plugin->component = 'mod_workshop'; $plugin->cron = 60; // Give as a chance every minute.