mod/lti/lib.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 // 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
  33 // Contact info: Marc Alier Forment granludo @ gmail.com or marc.alier @ upc.edu
  34
  35 /**
  36  * This file contains a library of functions and constants for the lti module
  37  *
  38  * @package    mod
  39  * @subpackage lti
  40  * @copyright  2009 Marc Alier, Jordi Piguillem, Nikolas Galanis
  41  *  marc.alier@upc.edu
  42  * @copyright  2009 Universitat Politecnica de Catalunya http://www.upc.edu
  43  * @author     Marc Alier
  44  * @author     Jordi Piguillem
  45  * @author     Nikolas Galanis
  46  * @author     Chris Scribner
  47  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  48  */
  49
  50 defined('MOODLE_INTERNAL') || die;
  51
  52 /**
  53  * List of features supported in URL module
  54  * @param string $feature FEATURE_xx constant for requested feature
  55  * @return mixed True if module supports feature, false if not, null if doesn't know
  56  */
  57 function lti_supports($feature) {
  58     switch($feature) {
  59         case FEATURE_GROUPS:                  return false;
  60         case FEATURE_GROUPINGS:               return false;
  61         case FEATURE_GROUPMEMBERSONLY:        return true;
  62         case FEATURE_MOD_INTRO:               return true;
  63         case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
  64         case FEATURE_GRADE_HAS_GRADE:         return true;
  65         case FEATURE_GRADE_OUTCOMES:          return true;
  66         case FEATURE_BACKUP_MOODLE2:          return true;
  67         case FEATURE_SHOW_DESCRIPTION:        return true;
  68
  69         default: return null;
  70     }
  71 }
  72
  73 /**
  74  * Given an object containing all the necessary data,
  75  * (defined by the form in mod.html) this function
  76  * will create a new instance and return the id number
  77  * of the new instance.
  78  *
  79  * @param object $instance An object from the form in mod.html
  80  * @return int The id of the newly inserted basiclti record
  81  **/
  82 function lti_add_instance($lti, $mform) {
  83     global $DB, $CFG;
  84     require_once($CFG->dirroot.'/mod/lti/locallib.php');
  85
  86     $lti->timecreated = time();
  87     $lti->timemodified = $lti->timecreated;
  88     $lti->servicesalt = uniqid('', true);
  89
  90     if (!isset($lti->grade)) {
  91         $lti->grade = 100; // TODO: Why is this harcoded here and default @ DB
  92     }
  93
  94     $lti->id = $DB->insert_record('lti', $lti);
  95
  96     if ($lti->instructorchoiceacceptgrades == LTI_SETTING_ALWAYS) {
  97         if (!isset($lti->cmidnumber)) {
  98             $lti->cmidnumber = '';
  99         }
 100
 101         lti_grade_item_update($lti);
 102     }
 103
 104     return $lti->id;
 105 }
 106
 107 /**
 108  * Given an object containing all the necessary data,
 109  * (defined by the form in mod.html) this function
 110  * will update an existing instance with new data.
 111  *
 112  * @param object $instance An object from the form in mod.html
 113  * @return boolean Success/Fail
 114  **/
 115 function lti_update_instance($lti, $mform) {
 116     global $DB, $CFG;
 117     require_once($CFG->dirroot.'/mod/lti/locallib.php');
 118
 119     $lti->timemodified = time();
 120     $lti->id = $lti->instance;
 121
 122     if (!isset($lti->showtitlelaunch)) {
 123         $lti->showtitlelaunch = 0;
 124     }
 125
 126     if (!isset($lti->showdescriptionlaunch)) {
 127         $lti->showdescriptionlaunch = 0;
 128     }
 129
 130     if (!isset($lti->grade)) {
 131         $lti->grade = $DB->get_field('lti', 'grade', array('id' => $lti->id));
 132     }
 133
 134     if ($lti->instructorchoiceacceptgrades == LTI_SETTING_ALWAYS) {
 135         lti_grade_item_update($lti);
 136     } else {
 137         lti_grade_item_delete($lti);
 138     }
 139
 140     return $DB->update_record('lti', $lti);
 141 }
 142
 143 /**
 144  * Given an ID of an instance of this module,
 145  * this function will permanently delete the instance
 146  * and any data that depends on it.
 147  *
 148  * @param int $id Id of the module instance
 149  * @return boolean Success/Failure
 150  **/
 151 function lti_delete_instance($id) {
 152     global $DB;
 153
 154     if (! $basiclti = $DB->get_record("lti", array("id" => $id))) {
 155         return false;
 156     }
 157
 158     $result = true;
 159
 160     # Delete any dependent records here #
 161     lti_grade_item_delete($basiclti);
 162
 163     return $DB->delete_records("lti", array("id" => $basiclti->id));
 164 }
 165
 166 /**
 167  * Given a coursemodule object, this function returns the extra
 168  * information needed to print this activity in various places.
 169  * For this module we just need to support external urls as
 170  * activity icons
 171  *
 172  * @param cm_info $coursemodule
 173  * @return cached_cm_info info
 174  */
 175 function lti_get_coursemodule_info($coursemodule) {
 176     global $DB, $CFG;
 177     require_once($CFG->dirroot.'/mod/lti/locallib.php');
 178
 179     if (!$lti = $DB->get_record('lti', array('id' => $coursemodule->instance),
 180             'icon, secureicon, intro, introformat, name')) {
 181         return null;
 182     }
 183
 184     $info = new cached_cm_info();
 185
 186     // We want to use the right icon based on whether the
 187     // current page is being requested over http or https.
 188     if (lti_request_is_using_ssl() && !empty($lti->secureicon)) {
 189         $info->iconurl = new moodle_url($lti->secureicon);
 190     } else if (!empty($lti->icon)) {
 191         $info->iconurl = new moodle_url($lti->icon);
 192     }
 193
 194     if ($coursemodule->showdescription) {
 195         // Convert intro to html. Do not filter cached version, filters run at display time.
 196         $info->content = format_module_intro('lti', $lti, $coursemodule->id, false);
 197     }
 198
 199     $info->name = $lti->name;
 200
 201     return $info;
 202 }
 203
 204 /**
 205  * Return a small object with summary information about what a
 206  * user has done with a given particular instance of this module
 207  * Used for user activity reports.
 208  * $return->time = the time they did it
 209  * $return->info = a short text description
 210  *
 211  * @return null
 212  * @TODO: implement this moodle function (if needed)
 213  **/
 214 function lti_user_outline($course, $user, $mod, $basiclti) {
 215     return null;
 216 }
 217
 218 /**
 219  * Print a detailed representation of what a user has done with
 220  * a given particular instance of this module, for user activity reports.
 221  *
 222  * @return boolean
 223  * @TODO: implement this moodle function (if needed)
 224  **/
 225 function lti_user_complete($course, $user, $mod, $basiclti) {
 226     return true;
 227 }
 228
 229 /**
 230  * Given a course and a time, this module should find recent activity
 231  * that has occurred in basiclti activities and print it out.
 232  * Return true if there was output, or false is there was none.
 233  *
 234  * @uses $CFG
 235  * @return boolean
 236  * @TODO: implement this moodle function
 237  **/
 238 function lti_print_recent_activity($course, $isteacher, $timestart) {
 239     return false;  //  True if anything was printed, otherwise false
 240 }
 241
 242 /**
 243  * Function to be run periodically according to the moodle cron
 244  * This function searches for things that need to be done, such
 245  * as sending out mail, toggling flags etc ...
 246  *
 247  * @uses $CFG
 248  * @return boolean
 249  **/
 250 function lti_cron () {
 251     return true;
 252 }
 253
 254 /**
 255  * Must return an array of grades for a given instance of this module,
 256  * indexed by user.  It also returns a maximum allowed grade.
 257  *
 258  * Example:
 259  *    $return->grades = array of grades;
 260  *    $return->maxgrade = maximum allowed grade;
 261  *
 262  *    return $return;
 263  *
 264  * @param int $basicltiid ID of an instance of this module
 265  * @return mixed Null or object with an array of grades and with the maximum grade
 266  *
 267  * @TODO: implement this moodle function (if needed)
 268  **/
 269 function lti_grades($basicltiid) {
 270     return null;
 271 }
 272
 273 /**
 274  * This function returns if a scale is being used by one basiclti
 275  * it it has support for grading and scales. Commented code should be
 276  * modified if necessary. See forum, glossary or journal modules
 277  * as reference.
 278  *
 279  * @param int $basicltiid ID of an instance of this module
 280  * @return mixed
 281  *
 282  * @TODO: implement this moodle function (if needed)
 283  **/
 284 function lti_scale_used ($basicltiid, $scaleid) {
 285     $return = false;
 286
 287     //$rec = get_record("basiclti","id","$basicltiid","scale","-$scaleid");
 288     //
 289     //if (!empty($rec)  && !empty($scaleid)) {
 290     //    $return = true;
 291     //}
 292
 293     return $return;
 294 }
 295
 296 /**
 297  * Checks if scale is being used by any instance of basiclti.
 298  * This function was added in 1.9
 299  *
 300  * This is used to find out if scale used anywhere
 301  * @param $scaleid int
 302  * @return boolean True if the scale is used by any basiclti
 303  *
 304  */
 305 function lti_scale_used_anywhere($scaleid) {
 306     global $DB;
 307
 308     if ($scaleid and $DB->record_exists('lti', array('grade' => -$scaleid))) {
 309         return true;
 310     } else {
 311         return false;
 312     }
 313 }
 314
 315 /**
 316  * Execute post-install custom actions for the module
 317  * This function was added in 1.9
 318  *
 319  * @return boolean true if success, false on error
 320  */
 321 function lti_install() {
 322      return true;
 323 }
 324
 325 /**
 326  * Execute post-uninstall custom actions for the module
 327  * This function was added in 1.9
 328  *
 329  * @return boolean true if success, false on error
 330  */
 331 function lti_uninstall() {
 332     return true;
 333 }
 334
 335 /**
 336  * Returns available Basic LTI types
 337  *
 338  * @return array of basicLTI types
 339  */
 340 function lti_get_lti_types() {
 341     global $DB;
 342
 343     return $DB->get_records('lti_types');
 344 }
 345
 346 /**
 347  * Create grade item for given basiclti
 348  *
 349  * @category grade
 350  * @param object $basiclti object with extra cmidnumber
 351  * @param mixed optional array/object of grade(s); 'reset' means reset grades in gradebook
 352  * @return int 0 if ok, error code otherwise
 353  */
 354 function lti_grade_item_update($basiclti, $grades=null) {
 355     global $CFG;
 356     require_once($CFG->libdir.'/gradelib.php');
 357
 358     $params = array('itemname'=>$basiclti->name, 'idnumber'=>$basiclti->cmidnumber);
 359
 360     if ($basiclti->grade > 0) {
 361         $params['gradetype'] = GRADE_TYPE_VALUE;
 362         $params['grademax']  = $basiclti->grade;
 363         $params['grademin']  = 0;
 364
 365     } else if ($basiclti->grade < 0) {
 366         $params['gradetype'] = GRADE_TYPE_SCALE;
 367         $params['scaleid']   = -$basiclti->grade;
 368
 369     } else {
 370         $params['gradetype'] = GRADE_TYPE_TEXT; // allow text comments only
 371     }
 372
 373     if ($grades  === 'reset') {
 374         $params['reset'] = true;
 375         $grades = null;
 376     }
 377
 378     return grade_update('mod/lti', $basiclti->course, 'mod', 'lti', $basiclti->id, 0, $grades, $params);
 379 }
 380
 381 /**
 382  * Delete grade item for given basiclti
 383  *
 384  * @category grade
 385  * @param object $basiclti object
 386  * @return object basiclti
 387  */
 388 function lti_grade_item_delete($basiclti) {
 389     global $CFG;
 390     require_once($CFG->libdir.'/gradelib.php');
 391
 392     return grade_update('mod/lti', $basiclti->course, 'mod', 'lti', $basiclti->id, 0, null, array('deleted'=>1));
 393 }
 394
 395 function lti_extend_settings_navigation($settings, $parentnode) {
 396     global $PAGE;
 397
 398     if (has_capability('mod/lti:grade', context_module::instance($PAGE->cm->id))) {
 399         $keys = $parentnode->get_children_key_list();
 400
 401         $node = navigation_node::create('Submissions',
 402             new moodle_url('/mod/lti/grade.php', array('id'=>$PAGE->cm->id)),
 403             navigation_node::TYPE_SETTING, null, 'mod_lti_submissions');
 404
 405         $parentnode->add_node($node, $keys[1]);
 406     }
 407 }