Source for file course.php

Documentation is available at course.php

  1. <?php
  2.     // This file is part of the Sloodle project (www.sloodle.org)
  3.     
  4.     /**
  5.     * This file defines a structure for Sloodle data about a particular Moodle course.
  6.     *
  7.     * @package sloodle
  8.     * @copyright Copyright (c) 2008 Sloodle (various contributors)
  9.     * @license http://www.gnu.org/licenses/gpl-3.0.html GNU GPL v3
  10.     *
  11.     * @contributor Peter R. Bloomfield
  12.     */
  13.     
  14.     
  15.     /** Include the general Sloodle library. */
  16.     require_once(SLOODLE_LIBROOT.'/general.php');
  17.     /** Include the Sloodle controller structure. */
  18.     require_once(SLOODLE_LIBROOT.'/controller.php');
  19.     /** Include the layout profile management stuff. */
  20.     require_once(SLOODLE_LIBROOT.'/layout_profile.php');
  21.     
  22.     
  23.     /**
  24.     * The Sloodle course data class
  25.     * @package sloodle
  26.     */
  27.     class SloodleCourse
  28.     {
  29.     // DATA //
  30.     
  31.         /**
  32.         * The database object of the course to which this object relates.
  33.         * Corresponds to the "course" table in Moodle.
  34.         * Is null if not yet set
  35.         * @var object 
  36.         * @access private
  37.         */
  38.         var $course_object = null;
  39.     
  40.         /**
  41.         * The Sloodle course data object, if it exists.
  42.         * Is null if not yet set.
  43.         * @var object 
  44.         * @var private 
  45.         */
  46.         var $sloodle_course_data = null;
  47.         
  48.         /**
  49.         * The {@link SloodleController} object being used to access this course, if available.
  50.         * @var SloodleController 
  51.         * @var public 
  52.         */
  53.         var $controller = null;
  54.         
  55.         
  56.     // FUNCTIONS //
  57.     
  58.         /**
  59.         * Constructor
  60.         */
  61.         function SloodleCourse()
  62.         {
  63.             $this->controller = new SloodleController();
  64.         }
  65.         
  66.         /**
  67.         * Determines whether or not course data has been loaded.
  68.         * @return bool 
  69.         */
  70.         function is_loaded()
  71.         {
  72.             if (empty($this->course_object) || empty($this->sloodle_course_data)) return false;
  73.             return true;
  74.         }
  75.         
  76.         /**
  77.         * Gets the identifier of the course in the VLE.
  78.         * @return mixed Course identifier. Type depends on VLE. (In Moodle, it will be an integer).
  79.         */
  80.         function get_course_id()
  81.         {
  82.             return (int)$this->course_object->id;
  83.         }
  84.         
  85.         /**
  86.         * Gets the VLE course object.
  87.         * WARNING: this should only be used when ABSOLUTELY necessary.
  88.         * The contents are specific to the VLE.
  89.         * @return mixed Type and content depends upon VLE. In Moodle, it is an object representing a record from the 'course' table.
  90.         */
  91.         function get_course_object()
  92.         {
  93.             return $this->course_object;
  94.         }
  95.         
  96.         
  97.         /**
  98.         * Gets the short name of this course in the VLE.
  99.         * @return string Shortname of this course.
  100.         */
  101.         function get_short_name()
  102.         {
  103.             return $this->course_object->shortname;
  104.         }
  105.         
  106.         /**
  107.         * Gets the full name of this course in the VLE.
  108.         * @return string Fullname of this course.
  109.         */
  110.         function get_full_name()
  111.         {
  112.             return $this->course_object->fullname;
  113.         }
  114.         
  115.         /**
  116.         * Is auto registration permitted on this site AND course?
  117.         * Takes into account the site-wide setting as well.
  118.         * @return bool 
  119.         */
  120.         function check_autoreg()
  121.         {
  122.             // Check the site *and* the course value
  123.             return ((bool)sloodle_autoreg_enabled_site() && (bool)$this->get_autoreg());
  124.         }
  125.         
  126.         /**
  127.         * Gets the autoregistration value for this course only.
  128.         * (Ignores the site setting).
  129.         * @return bool 
  130.         */
  131.         function get_autoreg()
  132.         {
  133.             return (!empty($this->sloodle_course_data->autoreg));
  134.         }
  135.         
  136.         /**
  137.         * Enables auto-registration for this course.
  138.         * NOTE: it may still be disabled at site-level.
  139.         * @return void 
  140.         */
  141.         function enable_autoreg()
  142.         {
  143.             $this->sloodle_course_data->autoreg = 1;
  144.         }
  145.         
  146.         /**
  147.         * Disables auto-registration for this course.
  148.         * NOTE: does not affect the site setting.
  149.         * @return void 
  150.         */
  151.         function disable_autoreg()
  152.         {
  153.             $this->sloodle_course_data->autoreg = 0;
  154.         }
  155.         
  156.         
  157.         
  158.         /**
  159.         * Is auto enrolment permitted on this site AND course?
  160.         * Takes into account the site-wide setting as well.
  161.         * @return bool 
  162.         */
  163.         function check_autoenrol()
  164.         {
  165.             // Check the site *and* the course value
  166.             return ((bool)sloodle_autoenrol_enabled_site() && $this->get_autoenrol());
  167.         }
  168.         
  169.         /**
  170.         * Gets the auto enrolment value for this course only.
  171.         * (Ignores the site setting).
  172.         * @return bool 
  173.         */
  174.         function get_autoenrol()
  175.         {
  176.             return (!empty($this->sloodle_course_data->autoenrol));
  177.         }
  178.         
  179.         /**
  180.         * Enables auto-enrolment for this course.
  181.         * NOTE: it may still be disabled at site-level.
  182.         * @return void 
  183.         */
  184.         function enable_autoenrol()
  185.         {
  186.             $this->sloodle_course_data->autoenrol = 1;
  187.         }
  188.         
  189.         /**
  190.         * Disables auto-enrolment for this course.
  191.         * NOTE: does not affect the site setting.
  192.         * @return void 
  193.         */
  194.         function disable_autoenrol()
  195.         {
  196.             $this->sloodle_course_data->autoenrol = 0;
  197.         }
  198.         
  199.         
  200.         
  201.         /**
  202.         * Determines whether or not the course is available.
  203.         * Checks that the course has not been disabled or hidden etc..
  204.         * @return bool True if the course is available
  205.         */
  206.         function is_available()
  207.         {
  208.             // Check visbility
  209.             if (empty($this->course_object->visible)) return false;
  210.             
  211.             return true;
  212.         }
  213.         
  214.         
  215.         /**
  216.         * Gets the position of the loginzone as a string vector <x,y,z>
  217.         * @return string 
  218.         */
  219.         function get_loginzone_position()
  220.         {
  221.             if (isset($this->sloodle_course_data->loginzonepos)) return $this->sloodle_course_data->loginzonepos;
  222.             return '';
  223.         }
  224.         
  225.         /**
  226.         * Sets the position of the loginzone as a string vector <x,y,z>
  227.         * @param string $pos A string position vector <x,y,z>
  228.         * @return void 
  229.         * @todo Update to handle arrays as well
  230.         */
  231.         function set_loginzone_position($pos)
  232.         {
  233.             $this->sloodle_course_data->loginzonepos = $pos;
  234.         }
  235.         
  236.         /**
  237.         * Sets the position of the loginzone as a set of components
  238.         * @param float $x 
  239.         * @param float $y 
  240.         * @param float $z 
  241.         * @return void 
  242.         */
  243.         function set_loginzone_position_xyz($x, $y, $z)
  244.         {
  245.             $this->sloodle_course_data->loginzonepos = "<$x,$y,$z>";
  246.         }
  247.         
  248.         
  249.         /**
  250.         * Gets the size of the loginzone as a string vector <x,y,z>
  251.         * @return string 
  252.         */
  253.         function get_loginzone_size()
  254.         {
  255.             if (isset($this->sloodle_course_data->loginzonesize)) return $this->sloodle_course_data->loginzonesize;
  256.             return '';
  257.         }
  258.         
  259.         /**
  260.         * Sets the size of the loginzone as a string vector <x,y,z>
  261.         * @param string $size A string size vector <x,y,z>
  262.         * @return void 
  263.         * @todo Update to handle arrays as well
  264.         */
  265.         function set_loginzone_size($size)
  266.         {
  267.             $this->sloodle_course_data->loginzonesize = $size;
  268.         }
  269.         
  270.         /**
  271.         * Sets the size of the loginzone as a set of components
  272.         * @param float $x 
  273.         * @param float $y 
  274.         * @param float $z 
  275.         * @return void 
  276.         */
  277.         function set_loginzone_size_xyz($x, $y, $z)
  278.         {
  279.             $this->sloodle_course_data->loginzonesize = "<$x,$y,$z>";
  280.         }
  281.         
  282.         
  283.         /**
  284.         * Gets the region of the loginzone
  285.         * @return string 
  286.         */
  287.         function get_loginzone_region()
  288.         {
  289.             if (isset($this->sloodle_course_data->loginzoneregion)) return $this->sloodle_course_data->loginzoneregion;
  290.             return '';
  291.         }
  292.         
  293.         /**
  294.         * Sets the region of the loginzone
  295.         * @param string $region A string naming a region
  296.         * @return void 
  297.         */
  298.         function set_loginzone_region($region)
  299.         {
  300.             $this->sloodle_course_data->loginzoneregion = $region;
  301.         }
  302.         
  303.         
  304.         /**
  305.         * Gets the timestamp of the last time the loginzone was updated
  306.         * @return int 
  307.         */
  308.         function get_loginzone_time_updated()
  309.         {
  310.             if (isset($this->sloodle_course_data->loginzoneupdated)) return $this->sloodle_course_data->loginzoneupdated;
  311.             return 0;
  312.         }
  313.         
  314.         /**
  315.         * Sets the timestamp of the last time the loginzone was updated
  316.         * @param int $timestamp A unix timestamp. If null, the current timestamp is used
  317.         * @return void 
  318.         */
  319.         function set_loginzone_time_updated($timestamp = null)
  320.         {
  321.             if ($timestamp == null) $timestamp = time();
  322.             $this->sloodle_course_data->loginzoneupdated = $timestamp;
  323.         }
  324.  
  325.  
  326.         /**
  327.         * Generates a new LoginZone allocation for the specified user.
  328.         * @param SloodleUser $user The user for whom this allocation should be made
  329.         * @return string|falseA SLurl for the allocation, or false if it was unsuccessful
  330.         */
  331.         function generate_loginzone_allocation($user)
  332.         {
  333.             // Make sure the necessary data is available
  334.             if (!(isset($this->sloodle_course_data->loginzonepos) && isset($this->sloodle_course_data->loginzonesize) && isset($this->sloodle_course_data->loginzoneregion))) return false;
  335.             // Delete any existing LoginZone allocation for this user
  336.             delete_records('sloodle_loginzone_allocation', 'userid', $user->get_user_id());
  337.             
  338.             // We will try up to 10 times to find a new available position
  339.             $loginzonesize = sloodle_vector_to_array($this->sloodle_course_data->loginzonesize);
  340.             $maxtries = 10;
  341.             $success = false;
  342.             for ($i = 0; $i < $maxtries && $success == false; $i++) {
  343.                 // Generate a new random position
  344.                 $rndpos_arr = sloodle_random_position_in_zone($loginzonesize);
  345.                 $rndpos_str = sloodle_array_to_vector($rndpos_arr);
  346.                 // Is the position already taken?
  347.                 if (!get_record('sloodle_loginzone_allocation', 'course', $this->get_course_id(), 'position', $rndpos_str)) {
  348.                     // Nobody has the position
  349.                     $success = true;
  350.                 }
  351.             }
  352.             // Did we succeed in generating it?
  353.             if (!$success) return false;
  354.             
  355.             // Create a new one
  356.             $alloc = new stdClass();
  357.             $alloc->course = $this->get_course_id();
  358.             $alloc->userid = $user->get_user_id();
  359.             $alloc->position = $rndpos_str;
  360.             $alloc->timecreated = time();
  361.             // Attempt to insert it into the database
  362.             if (!insert_record('sloodle_loginzone_allocation', $alloc)) return false;
  363.             return true;
  364.         }
  365.         
  366.         /**
  367.         * Gets the SLurl for the specified user's loginzone alloation
  368.         * @param SloodleUser $user The user whose allocation is to be retrieved
  369.         * @return string|boolThe SLurl string if successful, or false if the user has no allocation or the loginzone does not exist
  370.         */
  371.         function get_loginzone_allocation($user)
  372.         {
  373.             // Make sure the necessary data is available
  374.             if (!(isset($this->sloodle_course_data->loginzonepos) && isset($this->sloodle_course_data->loginzonesize) && isset($this->sloodle_course_data->loginzoneregion))) return false;
  375.             // Attempt to fetch the data
  376.             $alloc = get_record('sloodle_loginzone_allocation', 'course', $this->get_course_id(), 'userid', $user->get_user_id());
  377.             if (!$alloc) return false;
  378.             $relpos = sloodle_vector_to_array($alloc->position);
  379.             // Calculate the absolute position of the allocation
  380.             $loginzonepos= sloodle_vector_to_array($this->sloodle_course_data->loginzonepos);
  381.             $abspos = array('x'=>$loginzonepos['x'] + $relpos['x'], 'y'=>$loginzonepos['y'] + $relpos['y'], 'z'=>$loginzonepos['z'] + $relpos['z']);
  382.             
  383.             // Construct and return the SLurl
  384.             return "secondlife://{$this->sloodle_course_data->loginzoneregion}/{$abspos['x']}/{$abspos['y']}/{$abspos['z']}";
  385.         }
  386.         
  387.         /**
  388.         * Finds the user identified by LoginZone allocation, and loads it into the given user object.
  389.         * Note: does not delete the allocation.
  390.         * @param string $pos Absolute position vector (relative to sim, not to LoginZone)
  391.         * @param SloodleUser &$user The user object which will be manipulated (by reference)
  392.         * @return bool True if successful, or false otherwise
  393.         */
  394.         function load_user_by_loginzone($pos, &$user)
  395.         {
  396.             // Calculate the relative position of the allocation
  397.             $abspos = sloodle_vector_to_array($pos);
  398.             $loginzonepos= sloodle_vector_to_array($this->sloodle_course_data->loginzonepos);
  399.             $relpos = array('x'=>$abspos['x'] - $loginzonepos['x'], 'y'=>$abspos['y'] - $loginzonepos['y'], 'z'=>$abspos['z'] - $loginzonepos['z']);
  400.             $relpos = sloodle_array_to_vector($relpos);
  401.         
  402.             // Attempt to find a matching LoginZone position in the database
  403.             $rec = get_record('sloodle_loginzone_allocation', 'course', $this->get_course_id(), 'position', $relpos);
  404.             if (!$rec) return false;
  405.             // Load the user
  406.             return $user->load_user($rec->userid);
  407.         }
  408.         
  409.         /**
  410.         * Deletes any loginzone allocations for the given user
  411.         * If there are multiple for the same user (which there should never be) it will delete them all.
  412.         * @param SloodleUser $user The user whose allocation is to be deleted
  413.         * @return void 
  414.         */
  415.         function delete_loginzone_allocation($user)
  416.         {
  417.             delete_records('sloodle_loginzone_allocation', 'userid', $user->get_user_id());
  418.         }
  419.         
  420.         /**
  421.         * Determines whether or not LoginZone data exists for this course.
  422.         * @return bool True if there is complete data, or false otherwise
  423.         */
  424.         function has_loginzone_data()
  425.         {
  426.             return (!(empty($this->sloodle_course_data->loginzonepos) || empty($this->sloodle_course_data->loginzonesize) || empty($this->sloodle_course_data->loginzoneregion)));
  427.         }
  428.         
  429.         
  430.         /**
  431.         * Reads fresh data into the structure from the database.
  432.         * Fetches Moodle and Sloodle data about the course specified.
  433.         * If necessary, it creates a new Sloodle entry with default settings.
  434.         * Returns true if successful, or false on failure.
  435.         * @param mixed $course Either a unique course ID, or a course data object. If the former, then VLE course data is read from the database. Otherwise, the data object is used as-is.
  436.         * @return bool 
  437.         */
  438.         function load($course)
  439.         {
  440.             // Reset everything
  441.             $this->course_object = null;
  442.             $this->sloodle_course_data = null;
  443.         
  444.             // Check what we are dealing with
  445.             if (is_int($course)) {
  446.                 // It is a course ID - make sure it's valid
  447.                 if ($course <= 0) return false;
  448.                 // Load the course data
  449.                 $this->course_object = get_record('course', 'id', $course);
  450.                 if (!$this->course_object) {
  451.                     $this->course_object = null;
  452.                     return false;
  453.                 }
  454.             } else if (is_object($course)) {
  455.                 // It is an object - make sure it has an ID
  456.                 if (!isset($course->id)) return false;
  457.                 $this->course_object = $course;
  458.             } else {
  459.                 // Don't know what it is - do nothing
  460.                 return false;
  461.             }
  462.             
  463.             // Fetch the Sloodle course data
  464.             $this->sloodle_course_data = get_record('sloodle_course', 'course', $this->course_object->id);
  465.             // Did it fail?
  466.             if (!$this->sloodle_course_data) {
  467.                 // Create the new entry
  468.                 $this->sloodle_course_data = new stdClass();
  469.                 $this->sloodle_course_data->course = $this->course_object->id;
  470.                 $this->sloodle_course_data->autoreg = 0;
  471.                 $this->sloodle_course_data->loginzonepos = '';
  472.                 $this->sloodle_course_data->loginzonesize = '';
  473.                 $this->sloodle_course_data->loginzoneregion = '';
  474.                 $this->sloodle_course_data->id = insert_record('sloodle_course', $this->sloodle_course_data);
  475.                 // Did something go wrong?
  476.                 if (!$this->sloodle_course_data->id) {
  477.                     $this->course_object = null;
  478.                     $this->sloodle_course_data = null;
  479.                     return false;
  480.                 }
  481.             }
  482.             
  483.             return true;
  484.         }
  485.         
  486.         /**
  487.         * Loads course and controller data by the unqiue site-wide identifier of a Sloodle controller.
  488.         * @param mixed $controllerid The unique site-wide identifier for a Sloodle Controller. (For Moodle, an integer cmi)
  489.         * @return bool True if successful, or false on failure.
  490.         */
  491.         function load_by_controller($controllerid)
  492.         {
  493.             // Clear out all our data
  494.             $this->course_object = null;
  495.             $this->sloodle_course_data = null;
  496.             
  497.             // Construct a new controller object, and attempt to load its data
  498.             $this->controller = new SloodleController();
  499.             if (!$this->controller->load($controllerid)) {
  500.                 sloodle_debug("Failed to load controller.<br>");
  501.                 return false;
  502.             }
  503.             
  504.             // Now attempt to load all the course data
  505.             if (!$this->load($this->controller->get_course_id())) {
  506.                 sloodle_debug("Failed to load course data.<br>");
  507.                 return false;
  508.             }
  509.             
  510.             return true;
  511.         }
  512.         
  513.         /**
  514.         * Writes current Sloodle course data back to the database.
  515.         * Requires that a course structure has already been retrieved.
  516.         * @return bool True if successful, or false on failure
  517.         */
  518.         function write()
  519.         {
  520.             // Make sure the course data is valid
  521.             if (empty($this->course_object) || $this->course_object->id <= 0) return false;
  522.             if (empty($this->sloodle_course_data) || $this->sloodle_course_data->id <= 0) return false;
  523.             // Update the Sloodle data
  524.             return update_record('sloodle_course', $this->sloodle_course_data);
  525.         }
  526.         
  527.         /**
  528.         * Gets an array associating layout ID's to names
  529.         * @return array 
  530.         */
  531.         function get_layout_names()
  532.         {
  533.             // Fetch the layout records
  534.             $layouts = get_records('sloodle_layout', 'course', $this->course_object->id, 'name');
  535.             if (!$layouts) return array();
  536.             // Construct the array of names
  537.             $layout_names = array();
  538.             foreach ($layouts as $l) {
  539.                 $layout_names[$l->id] = $l->name;
  540.             }
  541.             
  542.             return $layout_names;
  543.         }
  544.         
  545.         /**
  546.         * Gets all the entries in the named layout.
  547.         * @param string $name The name of the layout to query
  548.         * @return array|boolA numeric array of {@link SloodleLayoutEntry} objects if successful, or false if the layout does not exist
  549.         */
  550.         function get_layout_entries($name)
  551.         {
  552.             // Attempt to find the relevant layout
  553.             $layout = get_record('sloodle_layout', 'course', $this->course_object->id, 'name', $name);
  554.             if (!$layout) return false;
  555.             
  556.             // Fetch all entries
  557.             $recs = get_records('sloodle_layout_entry', 'layout', $layout->id);
  558.             if (!$recs) return array();
  559.             
  560.             // Construct the array of SloodleLayoutEntry objects
  561.             $entries = array();
  562.             foreach ($recs as $r) {
  563.                 $entry = new SloodleLayoutEntry();
  564.                 $entry->name = $r->name;
  565.                 $entry->position = $r->position;
  566.                 $entry->rotation = $r->rotation;
  567.                 $entries[] = $entry;
  568.             }
  569.             
  570.             return $entries;
  571.         }
  572.         
  573.         /**
  574.         * Deletes the named layout.
  575.         * @param string $name The name of the layout to delete
  576.         * @return void 
  577.         */
  578.         function delete_layout($name)
  579.         {
  580.             // Attempt to find the relevant layout
  581.             $layout = get_record('sloodle_layout', 'course', $this->course_object->id, 'name', $name);
  582.             if (!$layout) return;
  583.             
  584.             // Delete all related entries
  585.             delete_records('sloodle_layout_entry', 'layout', $layout->id);
  586.             // Delete the layout itself
  587.             delete_records('sloodle_layout', 'course', $this->course_object->id, 'name', $name);
  588.         }
  589.         
  590.         /**
  591.         * Save the given entries in the named profile.
  592.         * @param string $name The name of the layout to query
  593.         * @param array $entries A numeric array of {@link SloodleLayoutEntry} objects to store
  594.         * @param bool $add (Default: false) If true, then the entries will be added to the layout instead of replacing existing entries
  595.         * @return bool True if successful, or false otherwise
  596.         */
  597.         function save_layout($name, $entries, $add = false)
  598.         {
  599.             // Attempt to find the relevant layout
  600.             $layout = get_record('sloodle_layout', 'course', $this->course_object->id, 'name', $name);
  601.             if (!$layout) {
  602.                 // Does not exist - create it
  603.                 $layout = new stdClass();
  604.                 $layout->name = $name;
  605.                 $layout->course = $this->course_object->id;
  606.                 $layout->timeupdated = time();
  607.                 $layout->id = insert_record('sloodle_layout', $layout);
  608.                 if (!$layout->id) return false;
  609.                 
  610.             } else {
  611.                 // Change the time updated
  612.                 set_field('sloodle_layout', 'timeupdated', time(), 'course', $this->course_object->id, 'name', $name);
  613.             }
  614.             
  615.             // Delete all existing entries if necessary
  616.             if (!$add) delete_records('sloodle_layout_entry', 'layout', $layout->id);
  617.             
  618.             // Insert each new entry
  619.             $success = true;
  620.             foreach ($entries as $e) {
  621.                 $rec = new stdClass();
  622.                 $rec->layout = $layout->id;
  623.                 $rec->name = $e->name;
  624.                 $rec->position = $e->position;
  625.                 $rec->rotation = $e->rotation;
  626.                 
  627.                 if (!insert_record('sloodle_layout_entry', $rec)) $success = false;
  628.             }
  629.             
  630.             return $success;
  631.         }
  632.         
  633.         /**
  634.         * Checks whether or not the CURRENTLY LOGGED-IN user can authorise objects on this course.
  635.         * @return bool True if the user has object authorisation permission, or false otherwise.
  636.         */
  637.         function can_user_authorise_objects()
  638.         {
  639.             global $USER;
  640.             // Make sure some user data
  641.             if (empty($USER) || $USER->id == 0) return FALSE;
  642.             
  643.             // Check the capability
  644.             return has_capability('mod/sloodle:objectauth', get_context_instance(CONTEXT_COURSE, $this->get_course_id()));
  645.         }
  646.     
  647.     }
  648.  
  649. ?>

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