Source for file sl_choice_linker.php

Documentation is available at sl_choice_linker.php

  1. <?php
  2.     // This file is part of the Sloodle project (www.sloodle.org)
  3.     
  4.     /**
  5.     * Sloodle choice linker
  6.     * Allows Sloodle "choice" objects in Second Life to interact with Moodle choice module instances
  7.     *
  8.     * @package sloodlechoice
  9.     * @copyright Copyright (c) 2008 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.     
  17.     ////////////////////////////////////////////////////////////
  18.     //
  19.     // The script is expected to be access directly by objects from within SL, and behaves in 3 modes.
  20.     // The mode depends on which parameters are specified (see below).
  21.     //
  22.     // MODES //
  23.     //  1. Available choices query = returns a list of choice module instances available in the specified course
  24.     //  2. Choice details query = returns the details for a specific choice instance
  25.     //  3. Option selection = informs Moodle that a user has made a selection
  26.     //
  27.     //
  28.     // PARAMETERS //
  29.     // *Always* required:
  30.     //    sloodlepwd = prim password for accessing site/course
  31.     //    sloodlecourseid = ID of the course being accessed
  32.     //
  33.     // Required for modes 2 and 3:
  34.     //    sloodlemoduleid = ID of the choice module instance being accessed
  35.     //
  36.     // Required for mode 3:
  37.     //    sloodleoptionid = ID of the option being selected
  38.     //    sloodleuuid = UUID (key) of avatar making the selection
  39.     //    sloodleavname = name of the avatar making the selection
  40.     // (NOTE: the script will function even if only uuid *or* avname is specified, but both is better)
  41.     //
  42.     // The script will default to mode 1.
  43.     // If the "optionid" is specified, it will attempt to adopt mode 3.
  44.     // Otherwise, if the additional "sloodlemoduleid" parameter is specified, then it will adopt mode 2.
  45.     //
  46.     ////////////////////////////////////////////////////////////
  47.     
  48.     
  49.     require_once('../../config.php'); // Sloodle/Moodle configuration
  50.     require_once(SLOODLE_DIRROOT.'/sl_debug.php'); // Debug functionality
  51.     //require_once(SLOODLE_DIRROOT.'/login/authlib.php'); // Sloodle authentication library
  52.     require_once(SLOODLE_DIRROOT.'/lib/sl_lsllib.php'); // Sloodle LSL handling
  53.     require_once(SLOODLE_DIRROOT.'/mod/choice/sl_choice_lib.php'); // Sloodle choice library
  54.     
  55.     sloodle_debug_output('<br/>');
  56.     
  57.     // The sloodleoptionid is specified to the choice, so get it explicitly
  58.     $sloodleoptionid = optional_param('sloodleoptionid', NULL, PARAM_INT);
  59.     
  60.     // Process the basic request data and authenticate the request
  61.     sloodle_debug_output('Instantiating LSL handler...<br/>');
  62.     $lsl = new SloodleLSLHandler();
  63.     sloodle_debug_output('Processing basic request data...<br/>');
  64.     $lsl->request->process_request_data();
  65.     sloodle_debug_output('Authenticating request...<br/>');
  66.     $lsl->request->authenticate_request(TRUE);
  67.         
  68.     // Make sure we were able to get a course object
  69.     // (With TRUE paramater, terminates the script if the course cannot be retrieved)
  70.     sloodle_debug_output('Requiring course record retrieval...<br/>');
  71.     $course_record = $lsl->request->get_course_record(TRUE);
  72.     
  73.     // If no choice ID was specified then we are in MODE 1
  74.     if ($lsl->request->get_module_id() == NULL) {
  75.     ///// ///// MODE 1 ///// /////
  76.     // In this mode, we're just giving a list of choices in the specified course
  77.     sloodle_debug_output('***** Script in Mode 1 *****<br/>');
  78.     
  79.         // Fetch a list of choices in this course
  80.         sloodle_debug_output('Fetching list of visible choice module instances in course...<br/>');
  81.         $choices = sloodle_get_visible_choices_in_course($lsl->request->get_course_id());
  82.         if (!is_array($choices)) {
  83.             // Something went wrong
  84.             sloodle_debug_output('ERROR: failed to retrieve list of instances.<br/>');
  85.             $lsl->response->set_status_code(-612);
  86.             $lsl->response->set_status_descriptor('CHOICE_LIST_QUERY');
  87.             $lsl->response->add_data_line('Failed to query for list of visible choice modules instances in course.');
  88.             $lsl->response->render_to_output();
  89.             exit();
  90.         }
  91.         
  92.         // Make sure we got at least 1 choice instance
  93.         $num_choices = count($choices);
  94.         if ($num_choices < 1) {
  95.             sloodle_debug_output('ERROR: no choices available.<br/>');
  96.             $lsl->response->set_status_code(-10022);
  97.             $lsl->response->set_status_descriptor('CHOICE_LIST_QUERY');
  98.             $lsl->response->add_data_line('No choice module instances available in course.');
  99.             $lsl->response->render_to_output();
  100.             exit();
  101.         }
  102.         
  103.  
  104.         // Prepare our response data
  105.         sloodle_debug_output('Setting up response...<br/>');
  106.         $lsl->response->set_status_code(10021);
  107.         $lsl->response->set_status_descriptor('CHOICE_LIST_QUERY');
  108.         //$lsl->response->add_data_line(array('num_instances',$num_choices)); // removed from spec 2008-02-06
  109.         // Go throgh each choice module instance
  110.         sloodle_debug_output('Going through each choice module instance...<br/>');
  111.         foreach ($choices as $id => $cur_choice) {
  112.             // Output each instance in the format "choice_instance|{id}|{name}"
  113.             //$lsl->response->add_data_line(array('choice_instance', $id, $cur_choice->name));
  114.             $lsl->response->add_data_line(array($id, $cur_choice->name)); // changed in spec 2008-02-06
  115.         }
  116.         // Output the response and finish
  117.         sloodle_debug_output('<pre>');
  118.         $lsl->response->render_to_output();
  119.         sloodle_debug_output('</pre>');
  120.         exit();
  121.     }
  122.     
  123.     // We require a course module instance of the 'choice' type
  124.     // This function will terminate the script with an LSL message if anything goes wrong
  125.     sloodle_debug_output('Attempting to get course module instance of \'choice\' type...<br/>');
  126.     $course_module_instance = $lsl->request->get_course_module_instance('choice', TRUE);
  127.     
  128.     // Fetch the status of the specified choice
  129.     sloodle_debug_output('Getting status of choice...<br/>');
  130.     $choice_status = sloodle_get_choice($course_module_instance);
  131.     if ($choice_status === FALSE) {
  132.         sloodle_debug_output('ERROR: failed to get choice status.<br/>');
  133.         $lsl->response->set_status_code(-10001);
  134.         $lsl->response->set_status_descriptor('CHOICE_QUERY');
  135.         $lsl->response->add_data_line('Failed to retreive status of specified choice module instance.');
  136.         $lsl->response->render_to_output();
  137.         exit();
  138.     }
  139.     
  140.     // If no option ID was specified then we are in MODE 2
  141.     if (is_null($sloodleoptionid)) {
  142.     ///// ///// MODE 2 ///// /////
  143.     // In this mode, we want to show the status of a particular choice
  144.     //  (i.e. the question, possible answers, results so far etc.)
  145.         sloodle_debug_output('***** Script in Mode 2 *****<br/>');        
  146.         
  147.         // Determine if the choice is open
  148.         sloodle_debug_output('Determining if the choice is open or closed...<br/>');
  149.         $is_open = 'false';
  150.         $cur_time = time();
  151.         // If timeopen or timeclose is 0, then it is either always open or it never closes (respectively)
  152.         // Otherwise, make sure it has opened and hasn't yet closed
  153.         if (    ($choice_status->timeopen == '0' || (int)$choice_status->timeopen <= $cur_time) &&
  154.                 ($choice_status->timeclose == '0' || (int)$choice_status->timeclose >= $cur_time)) {
  155.                 
  156.             $is_open = 'true';
  157.         }
  158.         
  159.         // Should results be given?
  160.         // (Either always, or after close)
  161.         sloodle_debug_output('Determine if results should be shown...<br/>');
  162.         $show_results = FALSE;
  163.         if ($choice_status->showresults == CHOICE_SHOWRESULTS_ALWAYS) {
  164.             $show_results = TRUE;
  165.             sloodle_debug_output('&nbsp;Always show results.<br/>');
  166.         } else if ($choice_status->showresults == CHOICE_SHOWRESULTS_AFTER_CLOSE && $is_open == 'false') {
  167.             $show_results = TRUE;
  168.             sloodle_debug_output('&nbsp;Showing results because choice is closed.<br/>');
  169.         } else {
  170.             sloodle_debug_output('&nbsp;Results display is disallowed.<br/>');
  171.         }
  172.         
  173.         // Get the number of people who have not yet answered, if we are OK to show results
  174.         $num_unanswered = -1;
  175.         if ($show_results == TRUE && (int)$choice_status->showunanswered != 0) {
  176.             sloodle_debug_output('Checking how many course users have not yet answered...<br/>');
  177.             $num_unanswered = sloodle_get_num_users_not_answered_choice($choice_status);
  178.             // Make sure an error did not occur
  179.             if (!is_int($num_unanswered)) {
  180.                 sloodle_debug_output("ERROR getting num unanswered: $num_unanswered<br/>");
  181.                 $num_unanswered = -1;
  182.             }
  183.         } else {
  184.             sloodle_debug_output('Not allowed to display number unanswered.<br/>');
  185.         }
  186.         
  187.         // Make sure our choice text is safe... remove newlines and such like as they mess up our response data! :-(
  188.         sloodle_debug_output('Cleaning choice text (removing HTML tags etc.)...<br/>');
  189.         $choice_text = str_replace("\n", " ", $choice_status->text);
  190.         $choice_text = str_replace("\r", "", $choice_text);
  191.         $choice_text = stripslashes(strip_tags($choice_text));
  192.     
  193.         // Prepare our response data
  194.         sloodle_debug_output('Setting up response...<br/>');
  195.         $lsl->response->set_status_code(10001);
  196.         $lsl->response->set_status_descriptor('CHOICE_QUERY');
  197.         $lsl->response->add_data_line(array('choice_name',$choice_status->name));
  198.         $lsl->response->add_data_line(array('choice_text',$choice_text));
  199.         //$lsl->response->add_data_line(array('num_options',count($choice_status->option))); // removed from spec 2008-02-06
  200.                 
  201.         // Go throgh each option
  202.         sloodle_debug_output('Going through each option in the choice...<br/>');
  203.         foreach ($choice_status->option as $optionid => $cur_option) {
  204.             // Make sure it's OK to show the results
  205.             $selections = -1;
  206.             if ($show_results) $selections = $choice_status->selections[$optionid];
  207.             // Output each option in the format: "option|{option_id}|{option_text}|{num_selected}"
  208.             $lsl->response->add_data_line(array('option', $optionid, $cur_option, $selections));
  209.         }
  210.         
  211.         // Add other response data
  212.         $lsl->response->add_data_line(array('num_unanswered',$num_unanswered));
  213.         $lsl->response->add_data_line(array('accepting_answers',$is_open));
  214.         
  215.         // Output the response and finish
  216.         sloodle_debug_output('<pre>');
  217.         $lsl->response->render_to_output();
  218.         sloodle_debug_output('</pre>');
  219.         
  220.         exit();
  221.     }
  222.         
  223. ///// ///// MODE 3 ///// /////
  224. // We must be in mode 3
  225. // In this mode, the user has selected a choice, and we must apply it return the result
  226.  
  227.     // Attempt to login the Moodle user
  228.     sloodle_debug_output('Attempting to login Moodle user...<br/>');
  229.     $lsl->login_by_request();
  230.     // Make sure the user is in the course specified
  231.     sloodle_debug_output('Ensuring that the Moodle user is enrolled in the course...<br/>');
  232.     $lsl->is_user_enrolled_by_request(); // By default, this is a 'require' style function -- it will terminate the script with an LSL error message if it fails
  233.     
  234.     // TODO (future): check that the user is allowed to access the choice (i.e. group mode)
  235.     
  236.     // Attempt to make the selection
  237.     sloodle_debug_output('Attempting to selected choice...<br/>');
  238.     $result = sloodle_select_choice_option($choice_status, $sloodleoptionid, $lsl->user->get_moodle_user_id());
  239.     // The response will be an integer status code, or a string
  240.     // Negative status codes and strings mean error messages
  241.     if (is_int($result)) {
  242.         if ($result >= 0) sloodle_debug_output("Success with code $result<br/>");
  243.         else sloodle_debug_output("Failed with code $result<br/>");
  244.         $lsl->response->set_status_code($result);
  245.     } else {
  246.         sloodle_debug_output("Failed with error: $result<br/>");
  247.         $lsl->response->set_status_code(-10016);
  248.         $lsl->response->add_data_line($result);
  249.     }
  250.     
  251.     // The status descriptor will be the same in all cases
  252.     $lsl->response->set_status_descriptor('CHOICE_SELECT');
  253.     $lsl->response->render_to_output();
  254.     exit();
  255.  
  256. ?>

Documentation generated on Tue, 04 Mar 2008 15:08:38 +0000 by phpDocumentor 1.4.0