MDL-51624 mod_lti: New Web Service mod_lti_view_lti
[moodle.git] / mod / lti / lib.php
CommitLineData
aa6eca66 1<?php
61eb12d4
CS
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//
aa6eca66
CS
17// This file is part of BasicLTI4Moodle
18//
19// BasicLTI4Moodle is an IMS BasicLTI (Basic Learning Tools for Interoperability)
20// consumer for Moodle 1.9 and Moodle 2.0. BasicLTI is a IMS Standard that allows web
21// based learning tools to be easily integrated in LMS as native ones. The IMS BasicLTI
22// specification is part of the IMS standard Common Cartridge 1.1 Sakai and other main LMS
23// are already supporting or going to support BasicLTI. This project Implements the consumer
24// for Moodle. Moodle is a Free Open source Learning Management System by Martin Dougiamas.
25// BasicLTI4Moodle is a project iniciated and leaded by Ludo(Marc Alier) and Jordi Piguillem
26// at the GESSI research group at UPC.
27// SimpleLTI consumer for Moodle is an implementation of the early specification of LTI
28// by Charles Severance (Dr Chuck) htp://dr-chuck.com , developed by Jordi Piguillem in a
29// Google Summer of Code 2008 project co-mentored by Charles Severance and Marc Alier.
30//
31// BasicLTI4Moodle is copyright 2009 by Marc Alier Forment, Jordi Piguillem and Nikolas Galanis
32// of the Universitat Politecnica de Catalunya http://www.upc.edu
e3f69b58 33// Contact info: Marc Alier Forment granludo @ gmail.com or marc.alier @ upc.edu.
aa6eca66
CS
34
35/**
61eb12d4 36 * This file contains a library of functions and constants for the lti module
aa6eca66 37 *
2b17ec3d 38 * @package mod_lti
61eb12d4 39 * @copyright 2009 Marc Alier, Jordi Piguillem, Nikolas Galanis
aa6eca66 40 * marc.alier@upc.edu
61eb12d4
CS
41 * @copyright 2009 Universitat Politecnica de Catalunya http://www.upc.edu
42 * @author Marc Alier
43 * @author Jordi Piguillem
44 * @author Nikolas Galanis
8f45215d 45 * @author Chris Scribner
61eb12d4 46 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
aa6eca66
CS
47 */
48
49defined('MOODLE_INTERNAL') || die;
50
06ca6cc9
TH
51/**
52 * Returns all other caps used in module.
53 *
54 * @return array
55 */
56function lti_get_extra_capabilities() {
57 return array('moodle/site:accessallgroups');
58}
59
aa6eca66
CS
60/**
61 * List of features supported in URL module
62 * @param string $feature FEATURE_xx constant for requested feature
63 * @return mixed True if module supports feature, false if not, null if doesn't know
64 */
65function lti_supports($feature) {
e3f69b58 66 switch ($feature) {
67 case FEATURE_GROUPS:
68 case FEATURE_GROUPINGS:
69 return false;
70 case FEATURE_MOD_INTRO:
71 case FEATURE_COMPLETION_TRACKS_VIEWS:
72 case FEATURE_GRADE_HAS_GRADE:
73 case FEATURE_GRADE_OUTCOMES:
74 case FEATURE_BACKUP_MOODLE2:
75 case FEATURE_SHOW_DESCRIPTION:
76 return true;
77
78 default:
79 return null;
aa6eca66
CS
80 }
81}
82
83/**
84 * Given an object containing all the necessary data,
85 * (defined by the form in mod.html) this function
86 * will create a new instance and return the id number
87 * of the new instance.
88 *
89 * @param object $instance An object from the form in mod.html
90 * @return int The id of the newly inserted basiclti record
91 **/
c69bd1af 92function lti_add_instance($lti, $mform) {
42a2c7f1
CS
93 global $DB, $CFG;
94 require_once($CFG->dirroot.'/mod/lti/locallib.php');
e27cb316 95
e3f69b58 96 if (!isset($lti->toolurl)) {
97 $lti->toolurl = '';
98 }
99
c69bd1af
EL
100 $lti->timecreated = time();
101 $lti->timemodified = $lti->timecreated;
102 $lti->servicesalt = uniqid('', true);
e27cb316 103
8fa50fdd
MN
104 lti_force_type_config_settings($lti, lti_get_type_config_by_instance($lti));
105
5582fe49 106 if (empty($lti->typeid) && isset($lti->urlmatchedtypeid)) {
ea5d0515
AF
107 $lti->typeid = $lti->urlmatchedtypeid;
108 }
109
8fa50fdd
MN
110 if (!isset($lti->instructorchoiceacceptgrades) || $lti->instructorchoiceacceptgrades != LTI_SETTING_ALWAYS) {
111 // The instance does not accept grades back from the provider, so set to "No grade" value 0.
112 $lti->grade = 0;
c69bd1af 113 }
aa6eca66 114
c69bd1af 115 $lti->id = $DB->insert_record('lti', $lti);
e27cb316 116
8fa50fdd 117 if (isset($lti->instructorchoiceacceptgrades) && $lti->instructorchoiceacceptgrades == LTI_SETTING_ALWAYS) {
c69bd1af
EL
118 if (!isset($lti->cmidnumber)) {
119 $lti->cmidnumber = '';
32c079dc 120 }
e27cb316 121
c69bd1af 122 lti_grade_item_update($lti);
aa6eca66
CS
123 }
124
c69bd1af 125 return $lti->id;
aa6eca66
CS
126}
127
128/**
129 * Given an object containing all the necessary data,
130 * (defined by the form in mod.html) this function
131 * will update an existing instance with new data.
132 *
133 * @param object $instance An object from the form in mod.html
134 * @return boolean Success/Fail
135 **/
c69bd1af 136function lti_update_instance($lti, $mform) {
42a2c7f1
CS
137 global $DB, $CFG;
138 require_once($CFG->dirroot.'/mod/lti/locallib.php');
aa6eca66 139
c69bd1af
EL
140 $lti->timemodified = time();
141 $lti->id = $lti->instance;
aa6eca66 142
b07878ec
CS
143 if (!isset($lti->showtitlelaunch)) {
144 $lti->showtitlelaunch = 0;
aa6eca66 145 }
e27cb316 146
b07878ec
CS
147 if (!isset($lti->showdescriptionlaunch)) {
148 $lti->showdescriptionlaunch = 0;
aa6eca66 149 }
e27cb316 150
8fa50fdd 151 lti_force_type_config_settings($lti, lti_get_type_config_by_instance($lti));
e27cb316 152
8fa50fdd 153 if (isset($lti->instructorchoiceacceptgrades) && $lti->instructorchoiceacceptgrades == LTI_SETTING_ALWAYS) {
c69bd1af 154 lti_grade_item_update($lti);
aa6eca66 155 } else {
8fa50fdd
MN
156 // Instance is no longer accepting grades from Provider, set grade to "No grade" value 0.
157 $lti->grade = 0;
158 $lti->instructorchoiceacceptgrades = 0;
159
c69bd1af 160 lti_grade_item_delete($lti);
aa6eca66
CS
161 }
162
ea5d0515
AF
163 if ($lti->typeid == 0 && isset($lti->urlmatchedtypeid)) {
164 $lti->typeid = $lti->urlmatchedtypeid;
165 }
166
c69bd1af 167 return $DB->update_record('lti', $lti);
aa6eca66
CS
168}
169
170/**
171 * Given an ID of an instance of this module,
172 * this function will permanently delete the instance
173 * and any data that depends on it.
174 *
175 * @param int $id Id of the module instance
176 * @return boolean Success/Failure
177 **/
178function lti_delete_instance($id) {
179 global $DB;
180
181 if (! $basiclti = $DB->get_record("lti", array("id" => $id))) {
182 return false;
183 }
184
185 $result = true;
186
e3f69b58 187 // Delete any dependent records here.
aa6eca66
CS
188 lti_grade_item_delete($basiclti);
189
e3f69b58 190 $ltitype = $DB->get_record('lti_types', array('id' => $basiclti->typeid));
191 $DB->delete_records('lti_tool_settings',
192 array('toolproxyid' => $ltitype->toolproxyid, 'course' => $basiclti->course, 'coursemoduleid' => $id));
193
aa6eca66
CS
194 return $DB->delete_records("lti", array("id" => $basiclti->id));
195}
196
976b5bca 197function lti_get_types() {
8cf7670e 198 global $OUTPUT;
976b5bca 199
8cf7670e 200 $subtypes = array();
976b5bca
CS
201 foreach (get_plugin_list('ltisource') as $name => $dir) {
202 if ($moretypes = component_callback("ltisource_$name", 'get_types')) {
8cf7670e 203 $subtypes = array_merge($subtypes, $moretypes);
976b5bca
CS
204 }
205 }
8cf7670e
MN
206 if (empty($subtypes)) {
207 return MOD_SUBTYPE_NO_CHILDREN;
208 }
209
210 $types = array();
211
212 $type = new stdClass();
213 $type->modclass = MOD_CLASS_ACTIVITY;
214 $type->type = 'lti_group_start';
215 $type->typestr = '--'.get_string('modulenameplural', 'mod_lti');
216 $types[] = $type;
217
218 $link = get_string('modulename_link', 'mod_lti');
219 $linktext = get_string('morehelp');
220 $help = get_string('modulename_help', 'mod_lti');
221 $help .= html_writer::tag('div', $OUTPUT->doc_link($link, $linktext, true), array('class' => 'helpdoclink'));
222
223 $type = new stdClass();
224 $type->modclass = MOD_CLASS_ACTIVITY;
24fc6dee 225 $type->type = '';
8cf7670e
MN
226 $type->typestr = get_string('generaltool', 'mod_lti');
227 $type->help = $help;
228 $types[] = $type;
229
230 $types = array_merge($types, $subtypes);
231
232 $type = new stdClass();
233 $type->modclass = MOD_CLASS_ACTIVITY;
234 $type->type = 'lti_group_end';
235 $type->typestr = '--';
236 $types[] = $type;
237
976b5bca
CS
238 return $types;
239}
240
6c64e8ac
EL
241/**
242 * Given a coursemodule object, this function returns the extra
243 * information needed to print this activity in various places.
244 * For this module we just need to support external urls as
245 * activity icons
246 *
3de55d24 247 * @param stdClass $coursemodule
6c64e8ac
EL
248 * @return cached_cm_info info
249 */
ea04a9f9 250function lti_get_coursemodule_info($coursemodule) {
42a2c7f1
CS
251 global $DB, $CFG;
252 require_once($CFG->dirroot.'/mod/lti/locallib.php');
e27cb316 253
6c64e8ac 254 if (!$lti = $DB->get_record('lti', array('id' => $coursemodule->instance),
3f358828 255 'icon, secureicon, intro, introformat, name, typeid, toolurl, launchcontainer')) {
6c64e8ac
EL
256 return null;
257 }
c07aec16 258
6c64e8ac 259 $info = new cached_cm_info();
e27cb316 260
b07878ec
CS
261 if ($coursemodule->showdescription) {
262 // Convert intro to html. Do not filter cached version, filters run at display time.
263 $info->content = format_module_intro('lti', $lti, $coursemodule->id, false);
264 }
e27cb316 265
3f358828 266 if (!empty($lti->typeid)) {
267 $toolconfig = lti_get_type_config($lti->typeid);
268 } else if ($tool = lti_get_tool_by_url_match($lti->toolurl)) {
3de55d24
TH
269 $toolconfig = lti_get_type_config($tool->id);
270 } else {
271 $toolconfig = array();
272 }
3f358828 273
274 // We want to use the right icon based on whether the
275 // current page is being requested over http or https.
276 if (lti_request_is_using_ssl() &&
277 (!empty($lti->secureicon) || (isset($toolconfig['secureicon']) && !empty($toolconfig['secureicon'])))) {
278 if (!empty($lti->secureicon)) {
279 $info->iconurl = new moodle_url($lti->secureicon);
280 } else {
281 $info->iconurl = new moodle_url($toolconfig['secureicon']);
282 }
283 } else if (!empty($lti->icon)) {
284 $info->iconurl = new moodle_url($lti->icon);
285 } else if (isset($toolconfig['icon']) && !empty($toolconfig['icon'])) {
286 $info->iconurl = new moodle_url($toolconfig['icon']);
287 }
288
289 // Does the link open in a new window?
3de55d24
TH
290 $launchcontainer = lti_get_launch_container($lti, $toolconfig);
291 if ($launchcontainer == LTI_LAUNCH_CONTAINER_WINDOW) {
292 $launchurl = new moodle_url('/mod/lti/launch.php', array('id' => $coursemodule->id));
293 $info->onclick = "window.open('" . $launchurl->out(false) . "', 'lti'); return false;";
294 }
295
b07878ec 296 $info->name = $lti->name;
194f2c60 297
c07aec16
CS
298 return $info;
299}
300
aa6eca66
CS
301/**
302 * Return a small object with summary information about what a
303 * user has done with a given particular instance of this module
304 * Used for user activity reports.
305 * $return->time = the time they did it
306 * $return->info = a short text description
307 *
308 * @return null
309 * @TODO: implement this moodle function (if needed)
310 **/
311function lti_user_outline($course, $user, $mod, $basiclti) {
64ce589b 312 return null;
aa6eca66
CS
313}
314
315/**
316 * Print a detailed representation of what a user has done with
317 * a given particular instance of this module, for user activity reports.
318 *
319 * @return boolean
320 * @TODO: implement this moodle function (if needed)
321 **/
322function lti_user_complete($course, $user, $mod, $basiclti) {
323 return true;
324}
325
326/**
327 * Given a course and a time, this module should find recent activity
328 * that has occurred in basiclti activities and print it out.
329 * Return true if there was output, or false is there was none.
330 *
331 * @uses $CFG
332 * @return boolean
333 * @TODO: implement this moodle function
334 **/
335function lti_print_recent_activity($course, $isteacher, $timestart) {
e3f69b58 336 return false; // True if anything was printed, otherwise false.
aa6eca66
CS
337}
338
339/**
340 * Function to be run periodically according to the moodle cron
341 * This function searches for things that need to be done, such
342 * as sending out mail, toggling flags etc ...
343 *
344 * @uses $CFG
345 * @return boolean
346 **/
347function lti_cron () {
348 return true;
349}
350
351/**
352 * Must return an array of grades for a given instance of this module,
353 * indexed by user. It also returns a maximum allowed grade.
354 *
355 * Example:
356 * $return->grades = array of grades;
357 * $return->maxgrade = maximum allowed grade;
358 *
359 * return $return;
360 *
361 * @param int $basicltiid ID of an instance of this module
362 * @return mixed Null or object with an array of grades and with the maximum grade
363 *
364 * @TODO: implement this moodle function (if needed)
365 **/
366function lti_grades($basicltiid) {
367 return null;
368}
369
aa6eca66
CS
370/**
371 * This function returns if a scale is being used by one basiclti
372 * it it has support for grading and scales. Commented code should be
373 * modified if necessary. See forum, glossary or journal modules
374 * as reference.
375 *
376 * @param int $basicltiid ID of an instance of this module
377 * @return mixed
378 *
379 * @TODO: implement this moodle function (if needed)
380 **/
381function lti_scale_used ($basicltiid, $scaleid) {
382 $return = false;
383
e3f69b58 384 // $rec = get_record("basiclti","id","$basicltiid","scale","-$scaleid");
aa6eca66 385 //
e3f69b58 386 // if (!empty($rec) && !empty($scaleid)) {
387 // $return = true;
388 // }
aa6eca66
CS
389
390 return $return;
391}
392
393/**
394 * Checks if scale is being used by any instance of basiclti.
395 * This function was added in 1.9
396 *
397 * This is used to find out if scale used anywhere
398 * @param $scaleid int
399 * @return boolean True if the scale is used by any basiclti
400 *
401 */
402function lti_scale_used_anywhere($scaleid) {
403 global $DB;
404
405 if ($scaleid and $DB->record_exists('lti', array('grade' => -$scaleid))) {
406 return true;
407 } else {
408 return false;
409 }
410}
411
412/**
413 * Execute post-install custom actions for the module
414 * This function was added in 1.9
415 *
416 * @return boolean true if success, false on error
417 */
418function lti_install() {
419 return true;
420}
421
422/**
423 * Execute post-uninstall custom actions for the module
424 * This function was added in 1.9
425 *
426 * @return boolean true if success, false on error
427 */
428function lti_uninstall() {
429 return true;
430}
431
432/**
433 * Returns available Basic LTI types
434 *
435 * @return array of basicLTI types
436 */
437function lti_get_lti_types() {
438 global $DB;
439
440 return $DB->get_records('lti_types');
441}
442
aa6eca66
CS
443/**
444 * Create grade item for given basiclti
445 *
a153c9f2 446 * @category grade
aa6eca66
CS
447 * @param object $basiclti object with extra cmidnumber
448 * @param mixed optional array/object of grade(s); 'reset' means reset grades in gradebook
449 * @return int 0 if ok, error code otherwise
450 */
e3f69b58 451function lti_grade_item_update($basiclti, $grades = null) {
aa6eca66
CS
452 global $CFG;
453 require_once($CFG->libdir.'/gradelib.php');
454
e3f69b58 455 $params = array('itemname' => $basiclti->name, 'idnumber' => $basiclti->cmidnumber);
aa6eca66
CS
456
457 if ($basiclti->grade > 0) {
458 $params['gradetype'] = GRADE_TYPE_VALUE;
459 $params['grademax'] = $basiclti->grade;
460 $params['grademin'] = 0;
461
462 } else if ($basiclti->grade < 0) {
463 $params['gradetype'] = GRADE_TYPE_SCALE;
464 $params['scaleid'] = -$basiclti->grade;
465
466 } else {
e3f69b58 467 $params['gradetype'] = GRADE_TYPE_TEXT; // Allow text comments only.
aa6eca66
CS
468 }
469
e3f69b58 470 if ($grades === 'reset') {
aa6eca66
CS
471 $params['reset'] = true;
472 $grades = null;
473 }
474
475 return grade_update('mod/lti', $basiclti->course, 'mod', 'lti', $basiclti->id, 0, $grades, $params);
476}
477
478/**
479 * Delete grade item for given basiclti
480 *
a153c9f2 481 * @category grade
aa6eca66
CS
482 * @param object $basiclti object
483 * @return object basiclti
484 */
485function lti_grade_item_delete($basiclti) {
486 global $CFG;
487 require_once($CFG->libdir.'/gradelib.php');
488
e3f69b58 489 return grade_update('mod/lti', $basiclti->course, 'mod', 'lti', $basiclti->id, 0, null, array('deleted' => 1));
aa6eca66
CS
490}
491
8fa50fdd
MN
492/**
493 * Log post actions
494 *
495 * @return array
496 */
497function lti_get_post_actions() {
498 return array();
499}
500
501/**
502 * Log view actions
503 *
504 * @return array
505 */
506function lti_get_view_actions() {
507 return array('view all', 'view');
508}
4bed1682
JL
509
510/**
511 * Mark the activity completed (if required) and trigger the course_module_viewed event.
512 *
513 * @param stdClass $lti lti object
514 * @param stdClass $course course object
515 * @param stdClass $cm course module object
516 * @param stdClass $context context object
517 * @since Moodle 3.0
518 */
519function lti_view($lti, $course, $cm, $context) {
520
521 // Trigger course_module_viewed event.
522 $params = array(
523 'context' => $context,
524 'objectid' => $lti->id
525 );
526
527 $event = \mod_lti\event\course_module_viewed::create($params);
528 $event->add_record_snapshot('course_modules', $cm);
529 $event->add_record_snapshot('course', $course);
530 $event->add_record_snapshot('lti', $lti);
531 $event->trigger();
532
533 // Completion.
534 $completion = new completion_info($course);
535 $completion->set_module_viewed($cm);
536}