Source for file module_presenter.php

Documentation is available at module_presenter.php

  1. <?php
  2.     // This file is part of the Sloodle project (www.sloodle.org)
  3.     
  4.     /**
  5.     * This file defines a Presenter module for Sloodle.
  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.     /** The Sloodle module base. */
  15.     require_once(SLOODLE_LIBROOT.'/modules/module_base.php');
  16.     /** General Sloodle functions. */
  17.     require_once(SLOODLE_LIBROOT.'/general.php');
  18.     
  19.     /**
  20.     * The Sloodle presenter module class.
  21.     * @package sloodle
  22.     */
  23.     class SloodleModulePresenter extends SloodleModule
  24.     {
  25.     // DATA //
  26.     
  27.         /**
  28.         * Internal for Moodle only - course module instance.
  29.         * Corresponds to one record from the Moodle 'course_modules' table.
  30.         * @var object 
  31.         * @access private
  32.         */
  33.         var $cm = null;
  34.     
  35.         /**
  36.         * Internal only - Sloodle module instance database object.
  37.         * Corresponds to one record from the Moodle 'mdl_sloodle' table.
  38.         * @var object 
  39.         * @access private
  40.         */
  41.         var $sloodle_instance = null;
  42.  
  43.         /**
  44.         * Internal only - a database objects representing the Presenter itself.
  45.         * Corresponds to one record from the Moodle 'mdl_sloodle_presenter' table.
  46.         * @var object 
  47.         * @access private
  48.         */
  49.         var $presenter = null;
  50.  
  51.                 
  52.         
  53.     // FUNCTIONS //
  54.     
  55.         /**
  56.         * Constructor
  57.         */
  58.         function SloodleModulePresenter(&$_session)
  59.         {
  60.             $constructor = get_parent_class($this);
  61.             parent::$constructor($_session);
  62.         }
  63.         
  64.         /**
  65.         * Loads data from the database.
  66.         * Note: even if the function fails, it may still have overwritten some or all existing data in the object.
  67.         * @param mixed $id The site-wide unique identifier for all modules. Type depends on VLE. On Moodle, it is an integer course module identifier ('id' field of 'course_modules' table)
  68.         * @return bool True if successful, or false otherwise
  69.         */
  70.         function load($id)
  71.         {
  72.             // Make sure the ID is valid
  73.             $id = (int)$id;
  74.             if ($id <= 0) return false;
  75.             
  76.             // Fetch the course module data
  77.             if (!($this->cm = get_coursemodule_from_id('sloodle', $id))) {
  78.                 sloodle_debug("Failed to load course module instance #$id.<br/>");
  79.                 return false;
  80.             }
  81.             // Make sure the module is visible
  82.             if ($this->cm->visible == 0) {
  83.                 sloodle_debug("Error: course module instance #$id not visible.<br/>");
  84.                 return false;
  85.             }
  86.             
  87.             // Load from the primary table: sloodle instance
  88.             if (!($this->sloodle_instance = get_record('sloodle', 'id', $this->cm->instance))) {
  89.                 sloodle_debug("Failed to load Sloodle module with instance ID #{$cm->instance}.<br/>");
  90.                 return false;
  91.             }
  92.  
  93.             // Load from the secondary table: sloodle_presenter
  94.             if (!($this->presenter = get_record('sloodle_presenter', 'sloodleid', $this->cm->instance))) {
  95.                 sloodle_debug("Failed to load secondary module table with instance ID #{$cm->instance}.<br/>");
  96.                 return false;
  97.             }
  98.             
  99.             return true;
  100.         }
  101.         
  102.         
  103.         /**
  104.         * Gets an array of absolute URLs to images in this slideshow, all correctly ordered.
  105.         * @return 2d numeric array, each element associates an entry ID to a numeric array of URL string, the name of the source type, and the name of the slide.
  106.         */
  107.         function get_entry_urls()
  108.         {
  109.             // Search the database for entries
  110.             $recs = get_records_select('sloodle_presenter_entry', "sloodleid = {$this->sloodle_instance->id}", 'ordering');
  111.             if (!$recs) return array();
  112.             // Format it all nicely into a simple array
  113.             $output = array();
  114.             foreach ($recs as $r) {
  115.                 // Substitute the URL for the name if the name has been left blank (this can particularly happen on Presenters upgraded from an alpha version)
  116.                 $name = $r->name;
  117.                 if (empty($name)) $name = $r->source;
  118.                 $output[$r->id] = array($r->source, $r->type, $name);
  119.             }
  120.             return $output;
  121.         }
  122.  
  123.         /**
  124.         * Gets an ordered associative array of slides in presentation order.
  125.         * @return Array associating slide IDs to SloodlePresenterSlide objects if successful, or false if not.
  126.         */
  127.         function get_slides()
  128.         {
  129.             // Make sure we have valid ordering
  130.             $this->validate_ordering();
  131.             // Fetch the database records
  132.             $recs = get_records_select('sloodle_presenter_entry', "sloodleid = {$this->sloodle_instance->id}", 'ordering');
  133.             if (!$recs) return array();
  134.             // Construct the array of objects
  135.             $output = array();
  136.             $slideposition = 1;
  137.             foreach ($recs as $r) {
  138.                 // Substitute the source data for the name if no name is given.
  139.                 $name = $r->name;
  140.                 if (empty($name)) $name = $r->source;
  141.                 
  142.                 // Update legacy slide types
  143.                 $type = $r->type;
  144.                 switch ($r->type)
  145.                 {
  146.                 case 'image': $type = 'PresenterSlideImage'; break;
  147.                 case 'web': $type = 'PresenterSlideWeb'; break;
  148.                 case 'video': $type = 'PresenterSlideVideo'; break;
  149.                 }
  150.                 // Remove the 'SloodlePlugin' prefix if necessary
  151.                 $type = str_replace('SloodlePlugin', '', $type);
  152.  
  153.                 // Add the slide to our list
  154.                 $output[$r->id] = new SloodlePresenterSlide($r->id, $this, $name, $r->source, $type, $r->ordering, $slideposition);
  155.                 $slideposition++;
  156.             }
  157.             return $output;
  158.         }
  159.        
  160.         /**
  161.         * Adds a new entry to the presentation.
  162.         * @param string $source A string containing the source address -- must start with http for absolute URLs
  163.         * @param string $type Name of the type of source, e.g. "web", "image", or "video"
  164.         * @param string $name Name of the slide
  165.         * @param integer $position Integer indicating the position of the new entry. If negative, then it is placed last in the presentation.
  166.         * @return True if successful, or false on failure.
  167.         */
  168.         function add_entry($source, $type, $name, $position = -1)
  169.         {
  170.             // Make sure our entry ordering is valid before we start
  171.             $this->validate_ordering();
  172.  
  173.             // Construct and attempt to insert the new record
  174.             $rec = new stdClass();
  175.             $rec->sloodleid = $this->sloodle_instance->id;
  176.             $rec->source = $source;
  177.             $rec->name = $name;
  178.             $rec->type = $type;
  179.             if ($position < 0) {
  180.                 $num = count_records('sloodle_presenter_entry', 'sloodleid', $this->sloodle_instance->id);
  181.                 $rec->ordering = ((int)$num + 1) * 10;
  182.             } else {
  183.                 $rec->ordering = ($position * 10) - 1; // Ordering works in multiples of 10, starting at 10.
  184.             }
  185.             $result = (bool)insert_record('sloodle_presenter_entry', $rec, false);
  186.             
  187.             // Make sure our entry ordering is valid again now
  188.             $this->validate_ordering();
  189.             return $result;
  190.         }
  191.        
  192.  
  193.         /**
  194.         * Edits an existing entry in the presentation.
  195.         * @param int $id The ID of the entry in the database.
  196.         * @param string $source A string containing the source address -- must start with http for absolute URLs
  197.         * @param string $type Name of the type of source, e.g. "web", "image", or "video"
  198.         * @param string $name Name of the slide
  199.         * @param integer $position Integer indicating the desired position of the entry. If negative, then its position is left unchanged.
  200.         * @return True if successful, or false on failure.
  201.         */
  202.         function edit_entry($id, $source, $type, $name, $position = -1)
  203.         {
  204.             // Ensure we have valid ordering to begin with
  205.             $this->validate_ordering();
  206.  
  207.             // Attempt to fetch the existing entry from the database
  208.             $id = (int)$id;
  209.             $rec = get_record('sloodle_presenter_entry', 'id', $id, 'sloodleid', $this->sloodle_instance->id);
  210.             if (!$rec) return false;
  211.  
  212.             // Apply the changes to the record
  213.             $rec->source = $source;
  214.             $rec->name = $name;
  215.             $rec->type = $type;
  216.             if ($position > 0) {
  217.                 $rec->ordering = ($position * 10) - 1; // Ordering works in multiples of 10, starting at 10.
  218.             }
  219.             // Update the database
  220.             $result = (bool)update_record('sloodle_presenter_entry', $rec);
  221.             
  222.             // Make sure our entry ordering is valid
  223.             $this->validate_ordering();
  224.             return $result;
  225.         }
  226.         
  227.         /**
  228.         * Deletes the identified entry by ID.
  229.         * Only works if the entry is part of this presentation.
  230.         * @param int $id The ID of an entry record to delete
  231.         * @return void 
  232.         */
  233.         function delete_entry($id)
  234.         {
  235.             delete_records('sloodle_presenter_entry', 'sloodleid', $this->sloodle_instance->id, 'id', $id);
  236.            // Fix the ordering
  237.            $this->validate_ordering();
  238.         }
  239.  
  240.         /**
  241.         * Moves the ID'd entry forward or back in the presentation ordering.
  242.         * Only works if the entry is part of this presentation.
  243.         * @param int $id The ID of the entry to move.
  244.         * @param bool $forward TRUE to move the entry forward (closer to the beginning) or FALSE to push it back (closer to the end)
  245.         * @return void 
  246.         */
  247.         function move_entry($id, $forward)
  248.         {
  249.             // Start by ensuring uniform ordering, starting at 10.
  250.             $this->validate_ordering();
  251.             // Attempt to move the specified entry in the appropriate direction
  252.             $entry = get_record('sloodle_presenter_entry', 'sloodleid', $this->sloodle_instance->id, 'id', $id);
  253.             if (!$entry) return;
  254.             if ($forward) {
  255.                 // Avoid a negative ordering value.
  256.                 if ($entry->ordering >= 20) $entry->ordering -= 15;
  257.             } else {
  258.                 $entry->ordering += 15;
  259.             }
  260.             update_record('sloodle_presenter_entry', $entry);
  261.             // Re-validate the entry ordering
  262.             $this->validate_ordering();
  263.         }
  264.         
  265.         /**
  266.         * Relocates the identified entry to the specified position in the presentation.
  267.         * Positions count from 1 upwards. If an entry already exists in that location, then the existing entry is pushed to the next position.
  268.         * @param int $id The ID of the entry to relocate
  269.         * @param int $pos The position in the presentation to move the slide to
  270.         * @return void 
  271.         */
  272.         function relocate_entry($id, $pos)
  273.         {
  274.             // Start by ensuring uniform ordering, starting at 10.
  275.             $this->validate_ordering();
  276.             // Calculate the ordering value for our entry.
  277.             // The first entry in a presentation has ordering 10, and subsequent entries increment by 10.
  278.             // Therefore, we can insert an entry before an existing slot by moving it to one BEFORE the appropriate multiple of 10.
  279.             $newordering = ($pos * 10) - 1;
  280.             
  281.             // Write the new ordering to the database, and re-validate the order
  282.             $entry = get_record('sloodle_presenter_entry', 'sloodleid', $this->sloodle_instance->id, 'id', $id);
  283.             if (!$entry) return;
  284.             $entry->ordering = $newordering;
  285.             update_record('sloodle_presenter_entry', $entry);
  286.             
  287.             $this->validate_ordering();
  288.         }
  289.         
  290.         /**
  291.         * Validates the ordering value of all entries in the presenter.
  292.         * Gives each record an ordering value from 10 upwards, incrementing by 10 each time.
  293.         * @return void 
  294.         */
  295.         function validate_ordering()
  296.         {
  297.             // Get all entries in this presentation
  298.             $entries = get_records('sloodle_presenter_entry', 'sloodleid', $this->sloodle_instance->id, 'ordering');
  299.             if (!$entries || count($entries) <= 1) return;
  300.  
  301.             // Go through each entry in our array, and give it a valid ordering value.
  302.             $ordering = 10;
  303.             foreach ($entries as $entry) {
  304.                 $entry->ordering = $ordering;
  305.                 update_record('sloodle_presenter_entry', $entry);
  306.                 $ordering += 10;
  307.             }
  308.         }
  309.  
  310.         /**
  311.         * Gets the width of the Presenter frame (for viewing in Moodle).
  312.         * @return int Width of the Presenter frame.
  313.         */
  314.         function get_frame_width()
  315.         {
  316.             return (int)$this->presenter->framewidth;
  317.         }
  318.  
  319.         /**
  320.         * Gets the height of the Presenter frame (for viewing in Moodle).
  321.         * @return int Height of the Presenter frame.
  322.         */
  323.         function get_frame_height()
  324.         {
  325.             return (int)$this->presenter->frameheight;
  326.         }
  327.         
  328.     // ACCESSORS //
  329.     
  330.         /**
  331.         * Gets the name of this module instance.
  332.         * @return string The name of this module
  333.         */
  334.         function get_name()
  335.         {
  336.             return $this->sloodle_instance->name;
  337.         }
  338.         
  339.         /**
  340.         * Gets the intro description of this module instance, if available.
  341.         * @return string The intro description of this controller
  342.         */
  343.         function get_intro()
  344.         {
  345.             return $this->sloodle_instance->intro;
  346.         }
  347.         
  348.         /**
  349.         * Gets the identifier of the course this controller belongs to.
  350.         * @return mixed Course identifier. Type depends on VLE. (In Moodle, it will be an integer).
  351.         */
  352.         function get_course_id()
  353.         {
  354.             return (int)$this->sloodle_instance->course;
  355.         }
  356.         
  357.         /**
  358.         * Gets the time at which this instance was created, or 0 if unknown.
  359.         * @return int Timestamp
  360.         */
  361.         function get_creation_time()
  362.         {
  363.             return (int)$this->sloodle_instance->timecreated;
  364.         }
  365.         
  366.         /**
  367.         * Gets the time at which this instance was last modified, or 0 if unknown.
  368.         * @return int Timestamp
  369.         */
  370.         function get_modification_time()
  371.         {
  372.             return (int)$this->sloodle_instance->timemodified;
  373.         }
  374.         
  375.         
  376.         /**
  377.         * Gets the short type name of this instance.
  378.         * @return string 
  379.         */
  380.         function get_type()
  381.         {
  382.             return SLOODLE_TYPE_PRESENTER;
  383.         }
  384.  
  385.         /**
  386.         * Gets the full type name of this instance, according to the current language pack, if available.
  387.         * Note: should be overridden by sub-classes.
  388.         * @return string Full type name if possible, or the short name otherwise.
  389.         */
  390.         function get_type_full()
  391.         {
  392.             return get_string('moduletype:'.SLOODLE_TYPE_PRESENTER, 'sloodle');
  393.         }
  394.  
  395.     }
  396.  
  397.     /**
  398.     * Defines a single slide from a presentation, containing raw data.
  399.     * The data will usually need to interpreted by a slide plugin.
  400.     * @package sloodle
  401.     */
  402.     class SloodlePresenterSlide
  403.     {
  404.     // FUNCTIONS //
  405.  
  406.         // Constructor
  407.         function SloodlePresenterSlide($id=0, $presenter=null, $name='', $source='', $type='', $ordering=0, $slideposition=0)
  408.         {
  409.             $this->id = $id;
  410.             $this->presenter = $presenter;
  411.             $this->name = $name;
  412.             $this->source = $source;
  413.             $this->type = $type;
  414.             $this->ordering = $ordering;
  415.             $this->slideposition = $slideposition;
  416.         }
  417.  
  418.     // DATA //
  419.  
  420.         /**
  421.         * The ID of this slide in the DB table of slides.
  422.         * @access public
  423.         * @var int 
  424.         */
  425.         var $id = 0;
  426.     
  427.         /**
  428.         * The SloodleModulePresenter object relating the presentation this slide is in
  429.         * @access public
  430.         * @var SloodleModulePresenter 
  431.         */
  432.         var $presenter = null;
  433.  
  434.         /**
  435.         * The name of this slide
  436.         * @access public
  437.         * @var string 
  438.         */
  439.         var $name = '';
  440.  
  441.         /**
  442.         * The source data for this slide. Normally this would be an absolute url (starting with a protocol specifier like HTTP),
  443.         *  or a relative path, in which case it is treated as an internal Moodle file.
  444.         * Plugins may alternatively use this to store data which is to be rendered.
  445.         * @access public
  446.         * @var string 
  447.         */
  448.         var $source = '';
  449.  
  450.         /**
  451.         * The type of this slide. This will be the ID of a plugin, or it may be a legacy type, 'web', 'image', or 'video'.
  452.         * @access public
  453.         * @var string 
  454.         */
  455.         var $type = '';
  456.  
  457.         /**
  458.         * The ordering value for this slide. This should not generally be used. Refer to 'slideposition' instead.
  459.         * @access public
  460.         * @var integer 
  461.         */
  462.         var $ordering = 0;
  463.  
  464.         /**
  465.         * The position of this slide in the presentation. This is a 1-based count.
  466.         * @access public
  467.         * @var integer 
  468.         */
  469.         var $slideposition = 0;
  470.  
  471.     }
  472.  
  473.  
  474.  
  475. ?>

Documentation generated on Fri, 17 Jul 2009 11:02:05 +0100 by phpDocumentor 1.4.0