Source for file lib.php

Documentation is available at lib.php

  1. <?php
  2.  
  3.     /**
  4.     * Sloodle module core library functionality.
  5.     *
  6.     * This script is required by Moodle to contain certain key functionality for the module.
  7.     *
  8.     * @package sloodle
  9.     * @copyright Copyright (c) 2007 Sloodle (various contributors)
  10.     * @license http://www.gnu.org/licenses/gpl-3.0.html GNU GPL v3
  11.     *
  12.     * @contributor Peter R. Bloomfield
  13.     *
  14.     */
  15.     
  16.     require_once($CFG->dirroot.'/mod/sloodle/sl_config.php');
  17.     require_once(SLOODLE_LIBROOT.'/general.php');
  18.     
  19.  
  20.     /**
  21.     * Processes the module configuration options prior to saving them.
  22.     * Only used when the "config.html" file is used for module configuration.
  23.     * Moodle 1.9 now prefers the "settings.php" file.
  24.     *
  25.     * @param object &$config Reference to an object containing the configuration settings (can be edited)
  26.     * @return void 
  27.     */
  28.     function sloodle_process_options(&$config)
  29.     {
  30.     }
  31.     
  32.  
  33.     /**
  34.      * Given an object containing all the necessary data,
  35.      * (defined by the form in mod.html) this function
  36.      * will create a new instance and return the id number
  37.      * of the new instance.
  38.      *
  39.      * @param object $instance An object from the form in mod.html
  40.      * @return int The id of the newly inserted sloodle record
  41.      ***/
  42.     function sloodle_add_instance($sloodle) {
  43.         global $CFG;
  44.  
  45.         // Set the creation and modification times
  46.         $sloodle->timecreated = time();
  47.         $sloodle->timemodified = time();
  48.         
  49.         // Prefix the full type name on the instance name
  50.         $sloodle->name = get_string("moduletype:{$sloodle->type}", 'sloodle') . ': ' . $sloodle->name;
  51.             
  52.         // Attempt to insert the new Sloodle record
  53.         if (!$sloodle->id = insert_record('sloodle', $sloodle)) {
  54.             error(get_string('failedaddinstance', 'sloodle'));
  55.         }
  56.         
  57.         // We need to create a new secondary table for this module
  58.         $sec_table = new stdClass();
  59.         $sec_table->sloodleid = $sloodle->id;
  60.         
  61.         // Check the type of this module
  62.         $result = FALSE;
  63.         $errormsg = '';
  64.         switch ($sloodle->type) {
  65.         case SLOODLE_TYPE_CTRL:
  66.             // Create a new controller record
  67.             if (isset($sloodle->controller_enabled) && $sloodle->controller_enabled) $sec_table->enabled = 1;
  68.             else $sec_table->enabled = 0;
  69.             $sec_table->password = $sloodle->controller_password;
  70.             
  71.             // Attempt to add it to the database
  72.             if (!insert_record('sloodle_controller', $sec_table)) {
  73.                 $errormsg = get_string('failedaddsecondarytable', 'sloodle');
  74.             } else {
  75.                 $result = TRUE;
  76.             }
  77.             break;
  78.             
  79.         case SLOODLE_TYPE_DISTRIB:
  80.             // Add in a default blank channel number and update time
  81.             $sec_table->channel = '';
  82.             $sec_table->timeupdated = 0;
  83.         
  84.             // Attempt to add it to the database
  85.             if (!insert_record('sloodle_distributor', $sec_table)) {
  86.                 $errormsg = get_string('failedaddsecondarytable', 'sloodle');
  87.             } else {
  88.                 $result = TRUE;
  89.             }        
  90.             break;
  91.             
  92.         // ADD FURTHER MODULE TYPES HERE!
  93.             
  94.         default:
  95.             // Type not recognised
  96.             $errormsg = error(get_string('moduletypeunknown', 'sloodle'));
  97.             break;
  98.         }
  99.         
  100.         // Was there a problem?
  101.         if (!$result) {
  102.             // Yes
  103.             // Delete the Sloodle instance
  104.             delete_records('sloodle', 'id', $sloodle->id);
  105.             
  106.             // Show the error message (if there was one)
  107.             if (!empty($errormsg)) error($errormsg);
  108.             return FALSE;
  109.         }
  110.         
  111.         // Success!
  112.         return $sloodle->id;
  113.     }
  114.  
  115.     /**
  116.      * Given an object containing all the necessary data,
  117.      * (defined by the form in mod.html) this function
  118.      * will update an existing instance with new data.
  119.      *
  120.      * @param object $instance An object from the form in mod.html
  121.      * @return boolean Success/Fail
  122.      ***/
  123.     function sloodle_update_instance($sloodle) {
  124.         global $CFG;
  125.  
  126.         // Update the modification time
  127.         $sloodle->timemodified = time();
  128.         // Make sure the ID is correct for update
  129.         $sloodle->id = $sloodle->instance;
  130.         
  131.         // Make sure the type is the same as the existing record
  132.         $existing_record = get_record('sloodle', 'id', $sloodle->id);
  133.         if (!$existing_record) error(get_string('modulenotfound', 'sloodle'));
  134.         if ($existing_record->type != $sloodle->type) error(get_string('moduletypemismatch', 'sloodle'));
  135.         
  136.         // Check the type of this module
  137.         switch ($sloodle->type) {
  138.         case SLOODLE_TYPE_CTRL:
  139.             // Attempt to fetch the controller record
  140.             $ctrl = get_record('sloodle_controller', 'sloodleid', $sloodle->id);
  141.             if (!$ctrl) error(get_string('secondarytablenotfound', 'sloodle'));
  142.             
  143.             // Add the updated 'enabled' value
  144.             if (isset($sloodle->controller_enabled) && $sloodle->controller_enabled) $ctrl->enabled = 1;
  145.             else $ctrl->enabled = 0;
  146.             // Add the updated password
  147.             $ctrl->password = $sloodle->controller_password;
  148.             
  149.             
  150.             // Update the database
  151.             update_record('sloodle_controller', $ctrl);
  152.             
  153.             break;
  154.             
  155.         case SLOODLE_TYPE_DISTRIB:
  156.             // Attempt to fetch the distributor record
  157.             $distrib = get_record('sloodle_distributor', 'sloodleid', $sloodle->id);
  158.             if (!$distrib) error(get_string('secondarytablenotfound', 'sloodle'));
  159.             
  160.             // Has a reset been requested?
  161.             if ($sloodle->distributor_reset) {
  162.                 // Yes - clear the distributor channel
  163.                 $distrib->channel = '';
  164.                 
  165.                 // Delete all objects associated with the Distributor
  166.                 delete_records('sloodle_distributor_entry', 'distributorid', $distrib->id);
  167.             }
  168.             
  169.             
  170.             // Update the database
  171.             update_record('sloodle_distributor', $distrib);
  172.             
  173.             break;
  174.             
  175.         // ADD FURTHER MODULE TYPES HERE!
  176.             
  177.         default:
  178.             // Type not recognised
  179.             error(get_string('moduletypeunknown', 'sloodle'));
  180.             break;
  181.         }
  182.  
  183.         // Attempt the update
  184.         return update_record('sloodle', $sloodle);
  185.     }
  186.  
  187.     /**
  188.      * Given an ID of an instance of this module,
  189.      * this function will permanently delete the instance
  190.      * and any data that depends on it.
  191.      *
  192.      * @param int $id Id of the module instance
  193.      * @return boolean Success/Failure
  194.      ***/
  195.     function sloodle_delete_instance($id) {
  196.  
  197.         // Determine our success or otherwise
  198.         $result = true;
  199.  
  200.         // Attempt to delete the main Sloodle instance
  201.         if (!delete_records('sloodle', 'id', $id)) {
  202.             $result = false;
  203.         }
  204.         
  205.         // Delete any secondary controller tables
  206.         delete_records('sloodle_controller', 'sloodleid', $id);
  207.         
  208.         // Attempt to get any secondary distributor tables
  209.         $distribs = get_records('sloodle_distributor', 'sloodleid', $id);
  210.         if (is_array($distribs) && count($distribs) > 0) {
  211.             // Go through each distributor
  212.             foreach ($distribs as $d) {
  213.                 // Delete any related distributor entries
  214.                 delete_records('sloodle_distributor_entry', 'distributorid', $d->id);
  215.             }
  216.         }
  217.         // Delete all the distributors
  218.         delete_records('sloodle_distributor', 'sloodleid', $id);
  219.         
  220.         
  221.         // ADD FURTHER MODULE TYPES HERE!
  222.         
  223.  
  224.         return $result;
  225.     }
  226.  
  227.     /**
  228.      * Return a small object with summary information about what a
  229.      * user has done with a given particular instance of this module
  230.      * Used for user activity reports.
  231.      * $return->time = the time they did it
  232.      * $return->info = a short text description
  233.      *
  234.      * @return null 
  235.      * @todo Do we need this function to do anything?
  236.      ***/
  237.     function sloodle_user_outline($course, $user, $mod, $sloodle) {
  238.         return NULL;
  239.     }
  240.  
  241.     /**
  242.      * Print a detailed representation of what a user has done with
  243.      * a given particular instance of this module, for user activity reports.
  244.      *
  245.      * @return boolean 
  246.      * @todo Do we need this function to do anything?
  247.      ***/
  248.     function sloodle_user_complete($course, $user, $mod, $sloodle) {
  249.         return true;
  250.     }
  251.  
  252.     /**
  253.      * Given a course and a time, this module should find recent activity
  254.      * that has occurred in sloodle activities and print it out.
  255.      * Return true if there was output, or false is there was none.
  256.      *
  257.      * @uses $CFG
  258.      * @return boolean 
  259.      * @todo Figure out if we need this function to do anything!
  260.      ***/
  261.     function sloodle_print_recent_activity($course, $isteacher, $timestart) {
  262.         global $CFG;
  263.  
  264.         return false;  //  True if anything was printed, otherwise false 
  265.     }
  266.  
  267.     /**
  268.      * Function to be run periodically according to the Moodle cron.
  269.      * Clears out expired pending user entries, session keys, etc.
  270.      *
  271.      * @return boolean 
  272.      * @todo Delete expired user entries
  273.      * @todo Use a custom delay for expiries of users/objects
  274.      ***/
  275.     function sloodle_cron () {
  276.         echo "\nProcessing Sloodle cron tasks:\n";
  277.         
  278.         // Delete any pending user entries which have expired (more than 30 minutes old)
  279.         $expirytime = time() - 1800;
  280.         echo "Removing expired pending avatar entries...\n";
  281.         delete_records_select('sloodle_pending_avatars', "timeupdated < $expirytime");
  282.         
  283.         // Delete any LoginZone allocations which have expired (more than 15 minutes old)
  284.         $expirytime = time() - 900;
  285.         echo "Removing expired LoginZone allocations...\n";
  286.         delete_records_select('sloodle_loginzone_allocation', "timecreated < $expirytime");
  287.         
  288.         // Fetch our configuration settings, if they exist
  289.         $active_object_days = 7; // Give active objects a week by default
  290.         if (!empty($CFG->sloodle_active_object_lifetime)) $active_object_days = $CFG->sloodle_active_object_lifetime;
  291.         $user_object_days = 21; // Give user objects 3 weeks by default
  292.         if (!empty($CFG->sloodle_user_object_lifetime)) $user_object_days = $CFG->sloodle_user_object_lifetime;
  293.         
  294.         // Delete any active objects and session keys which have expired
  295.         // Deletes any authorised objects which have not checked-in for more than X days (where X is specified in module config)
  296.         // Deletes any unauthorised objects which have not checked-in for more than 1 hour
  297.         $expirytime_auth = time() - (86400 * $active_object_days);
  298.         $expirytime_unauth = time() - 3600;
  299.         echo "Searching for expired active objects...\n";
  300.         $recs = get_records_select('sloodle_active_object', "(((controllerid = 0 AND userid = 0) OR type = '') AND timeupdated < $expirytime_unauth) OR timeupdated < $expirytime_auth");
  301.         if ($recs) {
  302.             // Go through each object
  303.             echo "Removing " . count($recs) . " expired active objects and associated configuration settings...\n";
  304.             foreach ($recs as $r) {
  305.                 delete_records('sloodle_object_config', 'object', $r->id);
  306.                 delete_records('sloodle_active_object', 'id', $r->id);
  307.             }            
  308.         }
  309.         
  310.         // Delete any user-authorised objects which have expired
  311.         // (will eventually use custom expiry times, chosen in the configuration)
  312.         // Deletes any authorised objects which have not checked-in for more than X days (where X is specified in module config)
  313.         // Deletes any unauthorised objects which have not checked-in for more than 1 hour
  314.         $expirytime_auth = time() - (86400 * $user_object_days);
  315.         $expirytime_unauth = time() - 3600;
  316.         echo "Deleting expired user objects...\n";
  317.         delete_records_select('sloodle_user_object', "(authorised = 0 AND timeupdated < $expirytime_unauth) OR timeupdated < $expirytime_auth");
  318.         
  319.         // More stuff?
  320.         //...
  321.         
  322.         // Email login details to auto-registered avatars in-world
  323.         echo "Sending out login notifications...\n";
  324.         sloodle_process_login_notifications();
  325.  
  326.         echo "Done processing Sloodle cron tasks.\n\n";
  327.         return true;
  328.     }
  329.  
  330.     /**
  331.      * Must return an array of grades for a given instance of this module,
  332.      * indexed by user.  It also returns a maximum allowed grade.
  333.      * 
  334.      * Example:
  335.      *    $return->grades = array of grades;
  336.      *    $return->maxgrade = maximum allowed grade;
  337.      *
  338.      *    return $return;
  339.      *
  340.      * @param int $sloodleid ID of an instance of this module
  341.      * @return mixed Null or object with an array of grades and with the maximum grade
  342.      ***/
  343.     function sloodle_grades($sloodleid) {
  344.        return NULL;
  345.     }
  346.  
  347.     /**
  348.      * Must return an array of user records (all data) who are participants
  349.      * for a given instance of sloodle. Must include every user involved
  350.      * in the instance, independient of his role (student, teacher, admin...)
  351.      * See other modules as example.
  352.      *
  353.      * @param int $sloodleid ID of an instance of this module
  354.      * @return mixed boolean/array of students
  355.      * @todo Possibly make it return a list of users registered via the Sloodle instance?
  356.      ***/
  357.     function sloodle_get_participants($sloodleid) {
  358.         return false;
  359.     }
  360.  
  361.     /**
  362.      * This function returns if a scale is being used by one sloodle
  363.      * it it has support for grading and scales. Commented code should be
  364.      * modified if necessary. See forum, glossary or journal modules
  365.      * as reference.
  366.      *
  367.      * @param int $sloodleid ID of an instance of this module
  368.      * @return mixed 
  369.      ***/
  370.     function sloodle_scale_used ($sloodleid,$scaleid) {
  371.         $return = false;
  372.        
  373.         return $return;
  374.     }
  375.  
  376.  
  377.     /**
  378.     * Gets the different sub-types of Sloodle module available as a list for the "Add Activity..." menu.
  379.     *
  380.     * $return array Entries for the "Add Activity..." sub-menu for Sloodle
  381.     */
  382.  
  383.     function sloodle_get_types() {
  384.         global $CFG, $SLOODLE_TYPES;
  385.         $types = array();
  386.  
  387.         // Start the group
  388.         $type = new object();
  389.         $type->modclass = MOD_CLASS_ACTIVITY;
  390.         $type->type = "sloodle_group_start";
  391.         $type->typestr = '--'.get_string('modulenameplural', 'sloodle');
  392.         $types[] = $type;
  393.          
  394.         // Go through each Sloodle module type, and add it
  395.         foreach ($SLOODLE_TYPES as $st) {
  396.             $type = new object();
  397.             $type->modclass = MOD_CLASS_ACTIVITY;
  398.             $type->type = "sloodle&amp;type=$st";
  399.             $type->typestr = get_string("moduletype:$st", 'sloodle');
  400.             $types[] = $type;
  401.         }
  402.  
  403.         // End the group
  404.         $type = new object();
  405.         $type->modclass = MOD_CLASS_ACTIVITY;
  406.         $type->type = "sloodle_group_end";
  407.         $type->typestr = '--';
  408.         $types[] = $type;
  409.  
  410.         return $types;
  411.     }
  412.  
  413.  
  414.  
  415. ?>

Documentation generated on Mon, 07 Jul 2008 12:32:36 +0100 by phpDocumentor 1.4.0