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