MDL-51624 mod_lti: New Web Service mod_lti_view_lti
[moodle.git] / mod / lti / classes / external.php
CommitLineData
ae67efa8
JL
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 * External tool module external API
19 *
20 * @package mod_lti
21 * @category external
22 * @copyright 2015 Juan Leyva <juan@moodle.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 * @since Moodle 3.0
25 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once($CFG->libdir . '/externallib.php');
30require_once($CFG->dirroot . '/mod/lti/lib.php');
31require_once($CFG->dirroot . '/mod/lti/locallib.php');
32
33/**
34 * External tool module external functions
35 *
36 * @package mod_lti
37 * @category external
38 * @copyright 2015 Juan Leyva <juan@moodle.com>
39 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40 * @since Moodle 3.0
41 */
42class mod_lti_external extends external_api {
43
44 /**
45 * Returns description of method parameters
46 *
47 * @return external_function_parameters
48 * @since Moodle 3.0
49 */
50 public static function get_tool_launch_data_parameters() {
51 return new external_function_parameters(
52 array(
53 'toolid' => new external_value(PARAM_INT, 'external tool instance id')
54 )
55 );
56 }
57
58 /**
59 * Return the launch data for a given external tool.
60 *
61 * @param int $toolid the external tool instance id
62 * @return array of warnings and launch data
63 * @since Moodle 3.0
64 * @throws moodle_exception
65 */
66 public static function get_tool_launch_data($toolid) {
67 global $DB, $CFG;
68 require_once($CFG->dirroot . '/mod/lti/lib.php');
69
70 $params = self::validate_parameters(self::get_tool_launch_data_parameters(),
71 array(
72 'toolid' => $toolid
73 ));
74 $warnings = array();
75
76 // Request and permission validation.
77 $lti = $DB->get_record('lti', array('id' => $params['toolid']), '*', MUST_EXIST);
78 list($course, $cm) = get_course_and_cm_from_instance($lti, 'lti');
79
80 $context = context_module::instance($cm->id);
81 self::validate_context($context);
82
83 require_capability('mod/lti:view', $context);
84
85 $lti->cmid = $cm->id;
86 list($endpoint, $parms) = lti_get_launch_data($lti);
87
88 $parameters = array();
89 foreach ($parms as $name => $value) {
90 $parameters[] = array(
91 'name' => $name,
92 'value' => $value
93 );
94 }
95
96 $result = array();
97 $result['endpoint'] = $endpoint;
98 $result['parameters'] = $parameters;
99 $result['warnings'] = $warnings;
100 return $result;
101 }
102
103 /**
104 * Returns description of method result value
105 *
106 * @return external_description
107 * @since Moodle 3.0
108 */
109 public static function get_tool_launch_data_returns() {
110 return new external_single_structure(
111 array(
112 'endpoint' => new external_value(PARAM_RAW, 'Endpoint URL'), // Using PARAM_RAW as is defined in the module.
113 'parameters' => new external_multiple_structure(
114 new external_single_structure(
115 array(
116 'name' => new external_value(PARAM_NOTAGS, 'Parameter name'),
117 'value' => new external_value(PARAM_RAW, 'Parameter value')
118 )
119 )
120 ),
121 'warnings' => new external_warnings()
122 )
123 );
124 }
dfcdec12
JL
125
126 /**
127 * Describes the parameters for get_ltis_by_courses.
128 *
129 * @return external_function_parameters
130 * @since Moodle 3.0
131 */
132 public static function get_ltis_by_courses_parameters() {
133 return new external_function_parameters (
134 array(
135 'courseids' => new external_multiple_structure(
136 new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array()
137 ),
138 )
139 );
140 }
141
142 /**
143 * Returns a list of external tools in a provided list of courses,
144 * if no list is provided all external tools that the user can view will be returned.
145 *
146 * @param array $courseids the course ids
147 * @return array the lti details
148 * @since Moodle 3.0
149 */
150 public static function get_ltis_by_courses($courseids = array()) {
151 global $CFG;
152
153 $returnedltis = array();
154 $warnings = array();
155
156 $params = self::validate_parameters(self::get_ltis_by_courses_parameters(), array('courseids' => $courseids));
157
158 if (empty($params['courseids'])) {
159 $params['courseids'] = array_keys(enrol_get_my_courses());
160 }
161
162 // Ensure there are courseids to loop through.
163 if (!empty($params['courseids'])) {
164
165 list($courses, $warnings) = external_util::validate_courses($params['courseids']);
166
167 // Get the ltis in this course, this function checks users visibility permissions.
168 // We can avoid then additional validate_context calls.
169 $ltis = get_all_instances_in_courses("lti", $courses);
170
171 foreach ($ltis as $lti) {
172
173 $context = context_module::instance($lti->coursemodule);
174
175 // Entry to return.
176 $module = array();
177
178 // First, we return information that any user can see in (or can deduce from) the web interface.
179 $module['id'] = $lti->id;
180 $module['coursemodule'] = $lti->coursemodule;
181 $module['course'] = $lti->course;
182 $module['name'] = external_format_string($lti->name, $context->id);
183
184 $viewablefields = [];
185 if (has_capability('mod/lti:view', $context)) {
186 list($module['intro'], $module['introformat']) =
187 external_format_text($lti->intro, $lti->introformat, $context->id, 'mod_lti', 'intro', $lti->id);
188
189 $viewablefields = array('launchcontainer', 'showtitlelaunch', 'showdescriptionlaunch', 'icon', 'secureicon');
190 }
191
192 // Check additional permissions for returning optional private settings.
193 if (has_capability('moodle/course:manageactivities', $context)) {
194
195 $additionalfields = array('timecreated', 'timemodified', 'typeid', 'toolurl', 'securetoolurl',
196 'instructorchoicesendname', 'instructorchoicesendemailaddr', 'instructorchoiceallowroster',
197 'instructorchoiceallowsetting', 'instructorcustomparameters', 'instructorchoiceacceptgrades', 'grade',
198 'resourcekey', 'password', 'debuglaunch', 'servicesalt', 'visible', 'groupmode', 'groupingid');
199 $viewablefields = array_merge($viewablefields, $additionalfields);
200
201 }
202
203 foreach ($viewablefields as $field) {
204 $module[$field] = $lti->{$field};
205 }
206
207 $returnedltis[] = $module;
208 }
209 }
210
211 $result = array();
212 $result['ltis'] = $returnedltis;
213 $result['warnings'] = $warnings;
214 return $result;
215 }
216
217 /**
218 * Describes the get_ltis_by_courses return value.
219 *
220 * @return external_single_structure
221 * @since Moodle 3.0
222 */
223 public static function get_ltis_by_courses_returns() {
224
225 return new external_single_structure(
226 array(
227 'ltis' => new external_multiple_structure(
228 new external_single_structure(
229 array(
230 'id' => new external_value(PARAM_INT, 'External tool id'),
231 'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
232 'course' => new external_value(PARAM_INT, 'Course id'),
233 'name' => new external_value(PARAM_RAW, 'LTI name'),
234 'intro' => new external_value(PARAM_RAW, 'The LTI intro', VALUE_OPTIONAL),
235 'introformat' => new external_format_value('intro', VALUE_OPTIONAL),
236 'timecreated' => new external_value(PARAM_INT, 'Time of creation', VALUE_OPTIONAL),
237 'timemodified' => new external_value(PARAM_INT, 'Time of last modification', VALUE_OPTIONAL),
238 'typeid' => new external_value(PARAM_INT, 'Type id', VALUE_OPTIONAL),
239 'toolurl' => new external_value(PARAM_URL, 'Tool url', VALUE_OPTIONAL),
240 'securetoolurl' => new external_value(PARAM_RAW, 'Secure tool url', VALUE_OPTIONAL),
241 'instructorchoicesendname' => new external_value(PARAM_TEXT, 'Instructor choice send name',
242 VALUE_OPTIONAL),
243 'instructorchoicesendemailaddr' => new external_value(PARAM_INT, 'instructor choice send mail address',
244 VALUE_OPTIONAL),
245 'instructorchoiceallowroster' => new external_value(PARAM_INT, 'Instructor choice allow roster',
246 VALUE_OPTIONAL),
247 'instructorchoiceallowsetting' => new external_value(PARAM_INT, 'Instructor choice allow setting',
248 VALUE_OPTIONAL),
249 'instructorcustomparameters' => new external_value(PARAM_RAW, 'instructor custom parameters',
250 VALUE_OPTIONAL),
251 'instructorchoiceacceptgrades' => new external_value(PARAM_INT, 'instructor choice accept grades',
252 VALUE_OPTIONAL),
253 'grade' => new external_value(PARAM_INT, 'Enable grades', VALUE_OPTIONAL),
254 'launchcontainer' => new external_value(PARAM_INT, 'Launch container mode', VALUE_OPTIONAL),
255 'resourcekey' => new external_value(PARAM_RAW, 'Resource key', VALUE_OPTIONAL),
256 'password' => new external_value(PARAM_RAW, 'Shared secret', VALUE_OPTIONAL),
257 'debuglaunch' => new external_value(PARAM_INT, 'Debug launch', VALUE_OPTIONAL),
258 'showtitlelaunch' => new external_value(PARAM_INT, 'Show title launch', VALUE_OPTIONAL),
259 'showdescriptionlaunch' => new external_value(PARAM_INT, 'Show description launch', VALUE_OPTIONAL),
260 'servicesalt' => new external_value(PARAM_RAW, 'Service salt', VALUE_OPTIONAL),
261 'icon' => new external_value(PARAM_URL, 'Alternative icon URL', VALUE_OPTIONAL),
262 'secureicon' => new external_value(PARAM_URL, 'Secure icon URL', VALUE_OPTIONAL),
263 'section' => new external_value(PARAM_INT, 'course section id', VALUE_OPTIONAL),
264 'visible' => new external_value(PARAM_INT, 'visible', VALUE_OPTIONAL),
265 'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL),
266 'groupingid' => new external_value(PARAM_INT, 'group id', VALUE_OPTIONAL),
267 ), 'Tool'
268 )
269 ),
270 'warnings' => new external_warnings(),
271 )
272 );
273 }
4bed1682
JL
274
275 /**
276 * Returns description of method parameters
277 *
278 * @return external_function_parameters
279 * @since Moodle 3.0
280 */
281 public static function view_lti_parameters() {
282 return new external_function_parameters(
283 array(
284 'ltiid' => new external_value(PARAM_INT, 'lti instance id')
285 )
286 );
287 }
288
289 /**
290 * Trigger the course module viewed event and update the module completion status.
291 *
292 * @param int $ltiid the lti instance id
293 * @return array of warnings and status result
294 * @since Moodle 3.0
295 * @throws moodle_exception
296 */
297 public static function view_lti($ltiid) {
298 global $DB;
299
300 $params = self::validate_parameters(self::view_lti_parameters(),
301 array(
302 'ltiid' => $ltiid
303 ));
304 $warnings = array();
305
306 // Request and permission validation.
307 $lti = $DB->get_record('lti', array('id' => $params['ltiid']), '*', MUST_EXIST);
308 list($course, $cm) = get_course_and_cm_from_instance($lti, 'lti');
309
310 $context = context_module::instance($cm->id);
311 self::validate_context($context);
312 require_capability('mod/lti:view', $context);
313
314 // Trigger course_module_viewed event and completion.
315 lti_view($lti, $course, $cm, $context);
316
317 $result = array();
318 $result['status'] = true;
319 $result['warnings'] = $warnings;
320 return $result;
321 }
322
323 /**
324 * Returns description of method result value
325 *
326 * @return external_description
327 * @since Moodle 3.0
328 */
329 public static function view_lti_returns() {
330 return new external_single_structure(
331 array(
332 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
333 'warnings' => new external_warnings()
334 )
335 );
336 }
ae67efa8 337}