05f4ca102a7d04d72ba028e04ac5fc78043a0b7f
[moodle.git] / mod / lesson / classes / external.php
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/>.
17 /**
18  * Lesson external API
19  *
20  * @package    mod_lesson
21  * @category   external
22  * @copyright  2017 Juan Leyva <juan@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  * @since      Moodle 3.3
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once($CFG->libdir . '/externallib.php');
30 require_once($CFG->dirroot . '/mod/lesson/locallib.php');
32 /**
33  * Lesson external functions
34  *
35  * @package    mod_lesson
36  * @category   external
37  * @copyright  2017 Juan Leyva <juan@moodle.com>
38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  * @since      Moodle 3.3
40  */
41 class mod_lesson_external extends external_api {
43     /**
44      * Describes the parameters for get_lessons_by_courses.
45      *
46      * @return external_function_parameters
47      * @since Moodle 3.3
48      */
49     public static function get_lessons_by_courses_parameters() {
50         return new external_function_parameters (
51             array(
52                 'courseids' => new external_multiple_structure(
53                     new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array()
54                 ),
55             )
56         );
57     }
59     /**
60      * Returns a list of lessons in a provided list of courses,
61      * if no list is provided all lessons that the user can view will be returned.
62      *
63      * @param array $courseids Array of course ids
64      * @return array of lessons details
65      * @since Moodle 3.3
66      */
67     public static function get_lessons_by_courses($courseids = array()) {
68         global $USER;
70         $warnings = array();
71         $returnedlessons = array();
73         $params = array(
74             'courseids' => $courseids,
75         );
76         $params = self::validate_parameters(self::get_lessons_by_courses_parameters(), $params);
78         $mycourses = array();
79         if (empty($params['courseids'])) {
80             $mycourses = enrol_get_my_courses();
81             $params['courseids'] = array_keys($mycourses);
82         }
84         // Ensure there are courseids to loop through.
85         if (!empty($params['courseids'])) {
87             list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
89             // Get the lessons in this course, this function checks users visibility permissions.
90             // We can avoid then additional validate_context calls.
91             $lessons = get_all_instances_in_courses("lesson", $courses);
92             foreach ($lessons as $lesson) {
93                 $context = context_module::instance($lesson->coursemodule);
95                 $lesson = new lesson($lesson);
96                 $lesson->update_effective_access($USER->id);
98                 // Entry to return.
99                 $lessondetails = array();
100                 // First, we return information that any user can see in the web interface.
101                 $lessondetails['id'] = $lesson->id;
102                 $lessondetails['coursemodule']      = $lesson->coursemodule;
103                 $lessondetails['course']            = $lesson->course;
104                 $lessondetails['name']              = external_format_string($lesson->name, $context->id);
106                 $lessonavailable = $lesson->get_time_restriction_status() === false;
107                 $lessonavailable = $lessonavailable && $lesson->get_password_restriction_status('') === false;
108                 $lessonavailable = $lessonavailable && $lesson->get_dependencies_restriction_status() === false;
110                 if ($lessonavailable) {
111                     // Format intro.
112                     list($lessondetails['intro'], $lessondetails['introformat']) = external_format_text($lesson->intro,
113                                                                     $lesson->introformat, $context->id, 'mod_lesson', 'intro', null);
115                     $lessondetails['introfiles'] = external_util::get_area_files($context->id, 'mod_lesson', 'intro', false, false);
116                     $lessondetails['mediafiles'] = external_util::get_area_files($context->id, 'mod_lesson', 'mediafile', 0);
117                     $viewablefields = array('practice', 'modattempts', 'usepassword', 'grade', 'custom', 'ongoing', 'usemaxgrade',
118                                             'maxanswers', 'maxattempts', 'review', 'nextpagedefault', 'feedback', 'minquestions',
119                                             'maxpages', 'timelimit', 'retake', 'mediafile', 'mediaheight', 'mediawidth',
120                                             'mediaclose', 'slideshow', 'width', 'height', 'bgcolor', 'displayleft', 'displayleftif',
121                                             'progressbar');
123                     // Fields only for managers.
124                     if ($lesson->can_manage()) {
125                         $additionalfields = array('password', 'dependency', 'conditions', 'activitylink', 'available', 'deadline',
126                                                   'timemodified', 'completionendreached', 'completiontimespent');
127                         $viewablefields = array_merge($viewablefields, $additionalfields);
128                     }
130                     foreach ($viewablefields as $field) {
131                         $lessondetails[$field] = $lesson->{$field};
132                     }
133                 }
134                 $returnedlessons[] = $lessondetails;
135             }
136         }
137         $result = array();
138         $result['lessons'] = $returnedlessons;
139         $result['warnings'] = $warnings;
140         return $result;
141     }
143     /**
144      * Describes the get_lessons_by_courses return value.
145      *
146      * @return external_single_structure
147      * @since Moodle 3.3
148      */
149     public static function get_lessons_by_courses_returns() {
150         return new external_single_structure(
151             array(
152                 'lessons' => new external_multiple_structure(
153                     new external_single_structure(
154                         array(
155                             'id' => new external_value(PARAM_INT, 'Standard Moodle primary key.'),
156                             'course' => new external_value(PARAM_INT, 'Foreign key reference to the course this lesson is part of.'),
157                             'coursemodule' => new external_value(PARAM_INT, 'Course module id.'),
158                             'name' => new external_value(PARAM_RAW, 'Lesson name.'),
159                             'intro' => new external_value(PARAM_RAW, 'Lesson introduction text.', VALUE_OPTIONAL),
160                             'introformat' => new external_format_value('intro', VALUE_OPTIONAL),
161                             'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
162                             'practice' => new external_value(PARAM_INT, 'Practice lesson?', VALUE_OPTIONAL),
163                             'modattempts' => new external_value(PARAM_INT, 'Allow student review?', VALUE_OPTIONAL),
164                             'usepassword' => new external_value(PARAM_INT, 'Password protected lesson?', VALUE_OPTIONAL),
165                             'password' => new external_value(PARAM_RAW, 'Password', VALUE_OPTIONAL),
166                             'dependency' => new external_value(PARAM_INT, 'Dependent on (another lesson id)', VALUE_OPTIONAL),
167                             'conditions' => new external_value(PARAM_RAW, 'Conditions to enable the lesson', VALUE_OPTIONAL),
168                             'grade' => new external_value(PARAM_INT, 'The total that the grade is scaled to be out of',
169                                                             VALUE_OPTIONAL),
170                             'custom' => new external_value(PARAM_INT, 'Custom scoring?', VALUE_OPTIONAL),
171                             'ongoing' => new external_value(PARAM_INT, 'Display ongoing score?', VALUE_OPTIONAL),
172                             'usemaxgrade' => new external_value(PARAM_INT, 'How to calculate the final grade', VALUE_OPTIONAL),
173                             'maxanswers' => new external_value(PARAM_INT, 'Maximum answers per page', VALUE_OPTIONAL),
174                             'maxattempts' => new external_value(PARAM_INT, 'Maximum attempts', VALUE_OPTIONAL),
175                             'review' => new external_value(PARAM_INT, 'Provide option to try a question again', VALUE_OPTIONAL),
176                             'nextpagedefault' => new external_value(PARAM_INT, 'Action for a correct answer', VALUE_OPTIONAL),
177                             'feedback' => new external_value(PARAM_INT, 'Display default feedback', VALUE_OPTIONAL),
178                             'minquestions' => new external_value(PARAM_INT, 'Minimum number of questions', VALUE_OPTIONAL),
179                             'maxpages' => new external_value(PARAM_INT, 'Number of pages to show', VALUE_OPTIONAL),
180                             'timelimit' => new external_value(PARAM_INT, 'Time limit', VALUE_OPTIONAL),
181                             'retake' => new external_value(PARAM_INT, 'Re-takes allowed', VALUE_OPTIONAL),
182                             'activitylink' => new external_value(PARAM_INT, 'Link to next activity', VALUE_OPTIONAL),
183                             'mediafile' => new external_value(PARAM_RAW, 'Local file path or full external URL', VALUE_OPTIONAL),
184                             'mediafiles' => new external_files('Media files', VALUE_OPTIONAL),
185                             'mediaheight' => new external_value(PARAM_INT, 'Popup for media file height', VALUE_OPTIONAL),
186                             'mediawidth' => new external_value(PARAM_INT, 'Popup for media with', VALUE_OPTIONAL),
187                             'mediaclose' => new external_value(PARAM_INT, 'Display a close button in the popup?', VALUE_OPTIONAL),
188                             'slideshow' => new external_value(PARAM_INT, 'Display lesson as slideshow', VALUE_OPTIONAL),
189                             'width' => new external_value(PARAM_INT, 'Slideshow width', VALUE_OPTIONAL),
190                             'height' => new external_value(PARAM_INT, 'Slideshow height', VALUE_OPTIONAL),
191                             'bgcolor' => new external_value(PARAM_TEXT, 'Slideshow bgcolor', VALUE_OPTIONAL),
192                             'displayleft' => new external_value(PARAM_INT, 'Display left pages menu?', VALUE_OPTIONAL),
193                             'displayleftif' => new external_value(PARAM_INT, 'Minimum grade to display menu', VALUE_OPTIONAL),
194                             'progressbar' => new external_value(PARAM_INT, 'Display progress bar?', VALUE_OPTIONAL),
195                             'available' => new external_value(PARAM_INT, 'Available from', VALUE_OPTIONAL),
196                             'deadline' => new external_value(PARAM_INT, 'Available until', VALUE_OPTIONAL),
197                             'timemodified' => new external_value(PARAM_INT, 'Last time settings were updated', VALUE_OPTIONAL),
198                             'completionendreached' => new external_value(PARAM_INT, 'Require end reached for completion?',
199                                                                             VALUE_OPTIONAL),
200                             'completiontimespent' => new external_value(PARAM_INT, 'Student must do this activity at least for',
201                                                                         VALUE_OPTIONAL),
202                             'visible' => new external_value(PARAM_INT, 'Visible?', VALUE_OPTIONAL),
203                             'groupmode' => new external_value(PARAM_INT, 'Group mode', VALUE_OPTIONAL),
204                             'groupingid' => new external_value(PARAM_INT, 'Grouping id', VALUE_OPTIONAL),
205                         )
206                     )
207                 ),
208                 'warnings' => new external_warnings(),
209             )
210         );
211     }
213     /**
214      * Utility function for validating a lesson.
215      *
216      * @param int $lessonid lesson instance id
217      * @return array array containing the lesson, course, context and course module objects
218      * @since  Moodle 3.3
219      */
220     protected static function validate_lesson($lessonid) {
221         global $DB, $USER;
223         // Request and permission validation.
224         $lesson = $DB->get_record('lesson', array('id' => $lessonid), '*', MUST_EXIST);
225         list($course, $cm) = get_course_and_cm_from_instance($lesson, 'lesson');
227         $lesson = new lesson($lesson, $cm, $course);
228         $lesson->update_effective_access($USER->id);
230         $context = $lesson->context;
231         self::validate_context($context);
233         return array($lesson, $course, $cm, $context);
234     }
236     /**
237      * Validates a new attempt.
238      *
239      * @param  lesson  $lesson lesson instance
240      * @param  array   $params request parameters
241      * @param  boolean $return whether to return the errors or throw exceptions
242      * @return array          the errors (if return set to true)
243      * @since  Moodle 3.3
244      */
245     protected static function validate_attempt(lesson $lesson, $params, $return = false) {
246         global $USER;
248         $errors = array();
250         // Avoid checkings for managers.
251         if ($lesson->can_manage()) {
252             return [];
253         }
255         // Dead line.
256         if ($timerestriction = $lesson->get_time_restriction_status()) {
257             $error = ["$timerestriction->reason" => userdate($timerestriction->time)];
258             if (!$return) {
259                 throw new moodle_exception(key($error), 'lesson', '', current($error));
260             }
261             $errors[key($error)] = current($error);
262         }
264         // Password protected lesson code.
265         if ($passwordrestriction = $lesson->get_password_restriction_status($params['password'])) {
266             $error = ["passwordprotectedlesson" => external_format_string($lesson->name, $lesson->context->id)];
267             if (!$return) {
268                 throw new moodle_exception(key($error), 'lesson', '', current($error));
269             }
270             $errors[key($error)] = current($error);
271         }
273         // Check for dependencies.
274         if ($dependenciesrestriction = $lesson->get_dependencies_restriction_status()) {
275             $errorhtmllist = implode(get_string('and', 'lesson') . ', ', $dependenciesrestriction->errors);
276             $error = ["completethefollowingconditions" => $dependenciesrestriction->dependentlesson->name . $errorhtmllist];
277             if (!$return) {
278                 throw new moodle_exception(key($error), 'lesson', '', current($error));
279             }
280             $errors[key($error)] = current($error);
281         }
283         // To check only when no page is set (starting or continuing a lesson).
284         if (empty($params['pageid'])) {
285             // To avoid multiple calls, store the magic property firstpage.
286             $lessonfirstpage = $lesson->firstpage;
287             $lessonfirstpageid = $lessonfirstpage ? $lessonfirstpage->id : false;
289             // Check if the lesson does not have pages.
290             if (!$lessonfirstpageid) {
291                 $error = ["lessonnotready2" => null];
292                 if (!$return) {
293                     throw new moodle_exception(key($error), 'lesson');
294                 }
295                 $errors[key($error)] = current($error);
296             }
298             // Get the number of retries (also referenced as attempts), and the last page seen.
299             $attemptscount = $lesson->count_user_retries($USER->id);
300             $lastpageseen = $lesson->get_last_page_seen($attemptscount);
302             // Check if the user left a timed session with no retakes.
303             if ($lastpageseen !== false && $lastpageseen != LESSON_EOL) {
304                 if ($lesson->left_during_timed_session($attemptscount) && $lesson->timelimit && !$lesson->retake) {
305                     $error = ["leftduringtimednoretake" => null];
306                     if (!$return) {
307                         throw new moodle_exception(key($error), 'lesson');
308                     }
309                     $errors[key($error)] = current($error);
310                 }
311             } else if ($attemptscount > 0 && !$lesson->retake) {
312                 // The user finished the lesson and no retakes are allowed.
313                 $error = ["noretake" => null];
314                 if (!$return) {
315                     throw new moodle_exception(key($error), 'lesson');
316                 }
317                 $errors[key($error)] = current($error);
318             }
319         }
321         return $errors;
322     }
324     /**
325      * Describes the parameters for get_lesson_access_information.
326      *
327      * @return external_external_function_parameters
328      * @since Moodle 3.3
329      */
330     public static function get_lesson_access_information_parameters() {
331         return new external_function_parameters (
332             array(
333                 'lessonid' => new external_value(PARAM_INT, 'lesson instance id')
334             )
335         );
336     }
338     /**
339      * Return access information for a given lesson.
340      *
341      * @param int $lessonid lesson instance id
342      * @return array of warnings and the access information
343      * @since Moodle 3.3
344      * @throws  moodle_exception
345      */
346     public static function get_lesson_access_information($lessonid) {
347         global $DB, $USER;
349         $warnings = array();
351         $params = array(
352             'lessonid' => $lessonid
353         );
354         $params = self::validate_parameters(self::get_lesson_access_information_parameters(), $params);
356         list($lesson, $course, $cm, $context) = self::validate_lesson($params['lessonid']);
358         $result = array();
359         // Capabilities first.
360         $result['canmanage'] = $lesson->can_manage();
361         $result['cangrade'] = has_capability('mod/lesson:grade', $context);
362         $result['canviewreports'] = has_capability('mod/lesson:viewreports', $context);
364         // Status information.
365         $result['reviewmode'] = $lesson->is_in_review_mode();
366         $result['attemptscount'] = $lesson->count_user_retries($USER->id);
367         $lastpageseen = $lesson->get_last_page_seen($result['attemptscount']);
368         $result['lastpageseen'] = ($lastpageseen !== false) ? $lastpageseen : 0;
369         $result['leftduringtimedsession'] = $lesson->left_during_timed_session($result['attemptscount']);
370         // To avoid multiple calls, store the magic property firstpage.
371         $lessonfirstpage = $lesson->firstpage;
372         $result['firstpageid'] = $lessonfirstpage ? $lessonfirstpage->id : 0;
374         // Access restrictions now, we emulate a new attempt access to get the possible warnings.
375         $result['preventaccessreasons'] = [];
376         $validationerrors = self::validate_attempt($lesson, ['password' => ''], true);
377         foreach ($validationerrors as $reason => $data) {
378             $result['preventaccessreasons'][] = [
379                 'reason' => $reason,
380                 'data' => $data,
381                 'message' => get_string($reason, 'lesson', $data),
382             ];
383         }
384         $result['warnings'] = $warnings;
385         return $result;
386     }
388     /**
389      * Describes the get_lesson_access_information return value.
390      *
391      * @return external_single_structure
392      * @since Moodle 3.3
393      */
394     public static function get_lesson_access_information_returns() {
395         return new external_single_structure(
396             array(
397                 'canmanage' => new external_value(PARAM_BOOL, 'Whether the user can manage the lesson or not.'),
398                 'cangrade' => new external_value(PARAM_BOOL, 'Whether the user can grade the lesson or not.'),
399                 'canviewreports' => new external_value(PARAM_BOOL, 'Whether the user can view the lesson reports or not.'),
400                 'reviewmode' => new external_value(PARAM_BOOL, 'Whether the lesson is in review mode for the current user.'),
401                 'attemptscount' => new external_value(PARAM_INT, 'The number of attempts done by the user.'),
402                 'lastpageseen' => new external_value(PARAM_INT, 'The last page seen id.'),
403                 'leftduringtimedsession' => new external_value(PARAM_BOOL, 'Whether the user left during a timed session.'),
404                 'firstpageid' => new external_value(PARAM_INT, 'The lesson first page id.'),
405                 'preventaccessreasons' => new external_multiple_structure(
406                     new external_single_structure(
407                         array(
408                             'reason' => new external_value(PARAM_ALPHANUMEXT, 'Reason lang string code'),
409                             'data' => new external_value(PARAM_RAW, 'Additional data'),
410                             'message' => new external_value(PARAM_RAW, 'Complete html message'),
411                         ),
412                         'The reasons why the user cannot attempt the lesson'
413                     )
414                 ),
415                 'warnings' => new external_warnings(),
416             )
417         );
418     }
420     /**
421      * Describes the parameters for view_lesson.
422      *
423      * @return external_external_function_parameters
424      * @since Moodle 3.3
425      */
426     public static function view_lesson_parameters() {
427         return new external_function_parameters (
428             array(
429                 'lessonid' => new external_value(PARAM_INT, 'lesson instance id'),
430                 'password' => new external_value(PARAM_RAW, 'lesson password', VALUE_DEFAULT, ''),
431             )
432         );
433     }
435     /**
436      * Trigger the course module viewed event and update the module completion status.
437      *
438      * @param int $lessonid lesson instance id
439      * @param str $password optional password (the lesson may be protected)
440      * @return array of warnings and status result
441      * @since Moodle 3.3
442      * @throws moodle_exception
443      */
444     public static function view_lesson($lessonid, $password = '') {
445         global $DB;
447         $params = array('lessonid' => $lessonid, 'password' => $password);
448         $params = self::validate_parameters(self::view_lesson_parameters(), $params);
449         $warnings = array();
451         list($lesson, $course, $cm, $context) = self::validate_lesson($params['lessonid']);
452         self::validate_attempt($lesson, $params);
454         $lesson->set_module_viewed();
456         $result = array();
457         $result['status'] = true;
458         $result['warnings'] = $warnings;
459         return $result;
460     }
462     /**
463      * Describes the view_lesson return value.
464      *
465      * @return external_single_structure
466      * @since Moodle 3.3
467      */
468     public static function view_lesson_returns() {
469         return new external_single_structure(
470             array(
471                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
472                 'warnings' => new external_warnings(),
473             )
474         );
475     }
477     /**
478      * Check if the current user can retrieve lesson information (grades, attempts) about the given user.
479      *
480      * @param int $userid the user to check
481      * @param stdClass $course course object
482      * @param stdClass $cm cm object
483      * @param stdClass $context context object
484      * @throws moodle_exception
485      * @since Moodle 3.3
486      */
487     protected static function check_can_view_user_data($userid, $course, $cm, $context) {
488         $user = core_user::get_user($userid, '*', MUST_EXIST);
489         core_user::require_active_user($user);
490         // Check permissions and that if users share group (if groups enabled).
491         require_capability('mod/lesson:viewreports', $context);
492         if (!groups_user_groups_visible($course, $user->id, $cm)) {
493             throw new moodle_exception('notingroup');
494         }
495     }
497     /**
498      * Describes the parameters for get_questions_attempts.
499      *
500      * @return external_external_function_parameters
501      * @since Moodle 3.3
502      */
503     public static function get_questions_attempts_parameters() {
504         return new external_function_parameters (
505             array(
506                 'lessonid' => new external_value(PARAM_INT, 'lesson instance id'),
507                 'attempt' => new external_value(PARAM_INT, 'lesson attempt number'),
508                 'correct' => new external_value(PARAM_BOOL, 'only fetch correct attempts', VALUE_DEFAULT, false),
509                 'pageid' => new external_value(PARAM_INT, 'only fetch attempts at the given page', VALUE_DEFAULT, null),
510                 'userid' => new external_value(PARAM_INT, 'only fetch attempts of the given user', VALUE_DEFAULT, null),
511             )
512         );
513     }
515     /**
516      * Return the list of page question attempts in a given lesson.
517      *
518      * @param int $lessonid lesson instance id
519      * @param int $attempt the lesson attempt number
520      * @param bool $correct only fetch correct attempts
521      * @param int $pageid only fetch attempts at the given page
522      * @param int $userid only fetch attempts of the given user
523      * @return array of warnings and page attempts
524      * @since Moodle 3.3
525      * @throws moodle_exception
526      */
527     public static function get_questions_attempts($lessonid, $attempt, $correct = false, $pageid = null, $userid = null) {
528         global $DB, $USER;
530         $params = array(
531             'lessonid' => $lessonid,
532             'attempt' => $attempt,
533             'correct' => $correct,
534             'pageid' => $pageid,
535             'userid' => $userid,
536         );
537         $params = self::validate_parameters(self::get_questions_attempts_parameters(), $params);
538         $warnings = array();
540         list($lesson, $course, $cm, $context) = self::validate_lesson($params['lessonid']);
542         // Default value for userid.
543         if (empty($params['userid'])) {
544             $params['userid'] = $USER->id;
545         }
547         // Extra checks so only users with permissions can view other users attempts.
548         if ($USER->id != $params['userid']) {
549             self::check_can_view_user_data($params['userid'], $course, $cm, $context);
550         }
552         $result = array();
553         $result['attempts'] = $lesson->get_attempts($params['attempt'], $params['correct'], $params['pageid'], $params['userid']);
554         $result['warnings'] = $warnings;
555         return $result;
556     }
558     /**
559      * Describes the get_questions_attempts return value.
560      *
561      * @return external_single_structure
562      * @since Moodle 3.3
563      */
564     public static function get_questions_attempts_returns() {
565         return new external_single_structure(
566             array(
567                 'attempts' => new external_multiple_structure(
568                     new external_single_structure(
569                         array(
570                             'id' => new external_value(PARAM_INT, 'The attempt id'),
571                             'lessonid' => new external_value(PARAM_INT, 'The attempt lessonid'),
572                             'pageid' => new external_value(PARAM_INT, 'The attempt pageid'),
573                             'userid' => new external_value(PARAM_INT, 'The user who did the attempt'),
574                             'answerid' => new external_value(PARAM_INT, 'The attempt answerid'),
575                             'retry' => new external_value(PARAM_INT, 'The lesson attempt number'),
576                             'correct' => new external_value(PARAM_INT, 'If it was the correct answer'),
577                             'useranswer' => new external_value(PARAM_RAW, 'The complete user answer'),
578                             'timeseen' => new external_value(PARAM_INT, 'The time the question was seen'),
579                         ),
580                         'The question page attempts'
581                     )
582                 ),
583                 'warnings' => new external_warnings(),
584             )
585         );
586     }
588     /**
589      * Describes the parameters for get_user_grade.
590      *
591      * @return external_external_function_parameters
592      * @since Moodle 3.3
593      */
594     public static function get_user_grade_parameters() {
595         return new external_function_parameters (
596             array(
597                 'lessonid' => new external_value(PARAM_INT, 'lesson instance id'),
598                 'userid' => new external_value(PARAM_INT, 'the user id (empty for current user)', VALUE_DEFAULT, null),
599             )
600         );
601     }
603     /**
604      * Return the final grade in the lesson for the given user.
605      *
606      * @param int $lessonid lesson instance id
607      * @param int $userid only fetch grades of this user
608      * @return array of warnings and page attempts
609      * @since Moodle 3.3
610      * @throws moodle_exception
611      */
612     public static function get_user_grade($lessonid, $userid = null) {
613         global $CFG, $USER;
614         require_once($CFG->libdir . '/gradelib.php');
616         $params = array(
617             'lessonid' => $lessonid,
618             'userid' => $userid,
619         );
620         $params = self::validate_parameters(self::get_user_grade_parameters(), $params);
621         $warnings = array();
623         list($lesson, $course, $cm, $context) = self::validate_lesson($params['lessonid']);
625         // Default value for userid.
626         if (empty($params['userid'])) {
627             $params['userid'] = $USER->id;
628         }
630         // Extra checks so only users with permissions can view other users attempts.
631         if ($USER->id != $params['userid']) {
632             self::check_can_view_user_data($params['userid'], $course, $cm, $context);
633         }
635         $grade = null;
636         $formattedgrade = null;
637         $grades = lesson_get_user_grades($lesson, $params['userid']);
638         if (!empty($grades)) {
639             $grade = $grades[$params['userid']]->rawgrade;
640             $params = array(
641                 'itemtype' => 'mod',
642                 'itemmodule' => 'lesson',
643                 'iteminstance' => $lesson->id,
644                 'courseid' => $course->id,
645                 'itemnumber' => 0
646             );
647             $gradeitem = grade_item::fetch($params);
648             $formattedgrade = grade_format_gradevalue($grade, $gradeitem);
649         }
651         $result = array();
652         $result['grade'] = $grade;
653         $result['formattedgrade'] = $formattedgrade;
654         $result['warnings'] = $warnings;
655         return $result;
656     }
658     /**
659      * Describes the get_user_grade return value.
660      *
661      * @return external_single_structure
662      * @since Moodle 3.3
663      */
664     public static function get_user_grade_returns() {
665         return new external_single_structure(
666             array(
667                 'grade' => new external_value(PARAM_FLOAT, 'The lesson final raw grade'),
668                 'formattedgrade' => new external_value(PARAM_RAW, 'The lesson final grade formatted'),
669                 'warnings' => new external_warnings(),
670             )
671         );
672     }
674     /**
675      * Describes the parameters for get_user_attempt_grade.
676      *
677      * @return external_external_function_parameters
678      * @since Moodle 3.3
679      */
680     public static function get_user_attempt_grade_parameters() {
681         return new external_function_parameters (
682             array(
683                 'lessonid' => new external_value(PARAM_INT, 'lesson instance id'),
684                 'lessonattempt' => new external_value(PARAM_INT, 'lesson attempt number'),
685                 'userid' => new external_value(PARAM_INT, 'the user id (empty for current user)', VALUE_DEFAULT, null),
686             )
687         );
688     }
690     /**
691      * Return grade information in the attempt for a given user.
692      *
693      * @param int $lessonid lesson instance id
694      * @param int $lessonattempt lesson attempt number
695      * @param int $userid only fetch attempts of the given user
696      * @return array of warnings and page attempts
697      * @since Moodle 3.3
698      * @throws moodle_exception
699      */
700     public static function get_user_attempt_grade($lessonid, $lessonattempt, $userid = null) {
701         global $CFG, $USER;
702         require_once($CFG->libdir . '/gradelib.php');
704         $params = array(
705             'lessonid' => $lessonid,
706             'lessonattempt' => $lessonattempt,
707             'userid' => $userid,
708         );
709         $params = self::validate_parameters(self::get_user_attempt_grade_parameters(), $params);
710         $warnings = array();
712         list($lesson, $course, $cm, $context) = self::validate_lesson($params['lessonid']);
714         // Default value for userid.
715         if (empty($params['userid'])) {
716             $params['userid'] = $USER->id;
717         }
719         // Extra checks so only users with permissions can view other users attempts.
720         if ($USER->id != $params['userid']) {
721             self::check_can_view_user_data($params['userid'], $course, $cm, $context);
722         }
724         $result = (array) lesson_grade($lesson, $params['lessonattempt'], $params['userid']);
725         $result['warnings'] = $warnings;
726         return $result;
727     }
729     /**
730      * Describes the get_user_attempt_grade return value.
731      *
732      * @return external_single_structure
733      * @since Moodle 3.3
734      */
735     public static function get_user_attempt_grade_returns() {
736         return new external_single_structure(
737             array(
738                 'nquestions' => new external_value(PARAM_INT, 'Number of questions answered'),
739                 'attempts' => new external_value(PARAM_INT, 'Number of question attempts'),
740                 'total' => new external_value(PARAM_FLOAT, 'Max points possible'),
741                 'earned' => new external_value(PARAM_FLOAT, 'Points earned by student'),
742                 'grade' => new external_value(PARAM_FLOAT, 'Calculated percentage grade'),
743                 'nmanual' => new external_value(PARAM_INT, 'Number of manually graded questions'),
744                 'manualpoints' => new external_value(PARAM_FLOAT, 'Point value for manually graded questions'),
745                 'warnings' => new external_warnings(),
746             )
747         );
748     }
750     /**
751      * Describes the parameters for get_content_pages_viewed.
752      *
753      * @return external_external_function_parameters
754      * @since Moodle 3.3
755      */
756     public static function get_content_pages_viewed_parameters() {
757         return new external_function_parameters (
758             array(
759                 'lessonid' => new external_value(PARAM_INT, 'lesson instance id'),
760                 'lessonattempt' => new external_value(PARAM_INT, 'lesson attempt number'),
761                 'userid' => new external_value(PARAM_INT, 'the user id (empty for current user)', VALUE_DEFAULT, null),
762             )
763         );
764     }
766     /**
767      * Return the list of content pages viewed by a user during a lesson attempt.
768      *
769      * @param int $lessonid lesson instance id
770      * @param int $lessonattempt lesson attempt number
771      * @param int $userid only fetch attempts of the given user
772      * @return array of warnings and page attempts
773      * @since Moodle 3.3
774      * @throws moodle_exception
775      */
776     public static function get_content_pages_viewed($lessonid, $lessonattempt, $userid = null) {
777         global $USER;
779         $params = array(
780             'lessonid' => $lessonid,
781             'lessonattempt' => $lessonattempt,
782             'userid' => $userid,
783         );
784         $params = self::validate_parameters(self::get_content_pages_viewed_parameters(), $params);
785         $warnings = array();
787         list($lesson, $course, $cm, $context) = self::validate_lesson($params['lessonid']);
789         // Default value for userid.
790         if (empty($params['userid'])) {
791             $params['userid'] = $USER->id;
792         }
794         // Extra checks so only users with permissions can view other users attempts.
795         if ($USER->id != $params['userid']) {
796             self::check_can_view_user_data($params['userid'], $course, $cm, $context);
797         }
799         $pages = $lesson->get_content_pages_viewed($params['lessonattempt'], $params['userid']);
801         $result = array();
802         $result['pages'] = $pages;
803         $result['warnings'] = $warnings;
804         return $result;
805     }
807     /**
808      * Describes the get_content_pages_viewed return value.
809      *
810      * @return external_single_structure
811      * @since Moodle 3.3
812      */
813     public static function get_content_pages_viewed_returns() {
814         return new external_single_structure(
815             array(
816                 'pages' => new external_multiple_structure(
817                     new external_single_structure(
818                         array(
819                             'id' => new external_value(PARAM_INT, 'The attempt id.'),
820                             'lessonid' => new external_value(PARAM_INT, 'The lesson id.'),
821                             'pageid' => new external_value(PARAM_INT, 'The page id.'),
822                             'userid' => new external_value(PARAM_INT, 'The user who viewed the page.'),
823                             'retry' => new external_value(PARAM_INT, 'The lesson attempt number.'),
824                             'flag' => new external_value(PARAM_INT, '1 if the next page was calculated randomly.'),
825                             'timeseen' => new external_value(PARAM_INT, 'The time the page was seen.'),
826                             'nextpageid' => new external_value(PARAM_INT, 'The next page chosen id.'),
827                         ),
828                         'The content pages viewed.'
829                     )
830                 ),
831                 'warnings' => new external_warnings(),
832             )
833         );
834     }