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/>.
  16
  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  */
  26
  27 defined('MOODLE_INTERNAL') || die;
  28
  29 require_once($CFG->libdir . '/externallib.php');
  30 require_once($CFG->dirroot . '/mod/lesson/locallib.php');
  31
  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 {
  42
  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     }
  58
  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;
  69
  70         $warnings = array();
  71         $returnedlessons = array();
  72
  73         $params = array(
  74             'courseids' => $courseids,
  75         );
  76         $params = self::validate_parameters(self::get_lessons_by_courses_parameters(), $params);
  77
  78         $mycourses = array();
  79         if (empty($params['courseids'])) {
  80             $mycourses = enrol_get_my_courses();
  81             $params['courseids'] = array_keys($mycourses);
  82         }
  83
  84         // Ensure there are courseids to loop through.
  85         if (!empty($params['courseids'])) {
  86
  87             list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
  88
  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);
  94
  95                 $lesson = new lesson($lesson);
  96                 $lesson->update_effective_access($USER->id);
  97
  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);
 105
 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;
 109
 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);
 114
 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');
 122
 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                     }
 129
 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     }
 142
 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     }
 212 }