Source for file sl_choice_lib.php

Documentation is available at sl_choice_lib.php

  1. <?php
  2.     /**
  3.     * Sloodle choice local library functions.
  4.     *
  5.     * Allows easier access to the Moodle choice data.
  6.     *
  7.     * @package sloodlechoice
  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.     // This script expects that the Sloodle configuration script has already been included
  16.     
  17.     // Include the standard choice module library
  18.     require_once($CFG->dirroot.'/mod/choice/lib.php');
  19.     
  20.     
  21.     /**
  22.     * Gets an array of available choices in the specified course.
  23.     * Choices which are hidden, or which are in a hidden section of the course, are ignored.
  24.     *
  25.     * @param int $course_id Integer ID of a Moodle course
  26.     * @return mixed If successful, a numeric array, associating module instance ID's with database record objects of the activity modules. Returns boolean false if an error occurs.
  27.     * @see sloodle_get_visible_glossaries_in_course()
  28.     * @see sloodle_get_visible_chatrooms_in_course()
  29.     * @see sloodle_get_choice()
  30.     * @todo: Generalise this function to support any module type
  31.     */
  32.     function sloodle_get_visible_choices_in_course( $course_id )
  33.     {
  34.         // Make sure the course ID is valid
  35.         if (!is_int($course_id) || $course_id <= 0) return FALSE;
  36.         // Find out which module number the choice is (this will fail if the choice module is not installed)
  37.         if (!($choice_module = get_record('modules', 'name', 'choice'))) return FALSE;
  38.         $choice_module_id = $choice_module->id;
  39.         
  40.         // We want a list of sections in the specified course
  41.         if (!($course_sections = get_records('course_sections', 'course', $course_id))) return FALSE;
  42.         // We need to filer that to visible sections only
  43.         $visible_course_sections = array();
  44.         foreach ($course_sections as $cur_section) {
  45.             if ((int)$cur_section->visible != 0) $visible_course_sections[] = (int)$cur_section->id;
  46.         }
  47.         
  48.         // Get full records for all choices in the specified course
  49.         if (!($all_choices_in_course = get_records('choice', 'course', $course_id))) return array();        
  50.         // We're going to want an array of records of visible choices
  51.         $visible_choice_records = array();
  52.         
  53.         // Get a list of module instances in the specified course (this gets everything, not just choices)
  54.         if (!($all_course_modules = get_records('course_modules', 'course', $course_id))) return array();
  55.         // We want to filter the module instances down to visible choice ID's
  56.         $visible_choice_modules = array();
  57.         foreach ($all_course_modules as $mod) {
  58.             // Is this a choice, is it visible, and is it in a visible section of the course?
  59.             // (It's ridiculously complicated... I know...)
  60.             if ($mod->module == $choice_module_id && (int)$mod->visible != 0 && in_array((int)$mod->section, $visible_course_sections)) {
  61.                 // OK - this is a visible choice in the correct course.
  62.                 // Now find its database record...
  63.                 foreach ($all_choices_in_course as $cur_choice_record) {
  64.                     // The 'instance' field of the course module instances corresponds to
  65.                     //  the 'id' field of the choice records
  66.                     if ($mod->instance == $cur_choice_record->id) {
  67.                         // Woohoo! We found a match. Add it to our database
  68.                         $visible_choice_records[$mod->id] = $cur_choice_record;
  69.                     }
  70.                 }
  71.             }
  72.         }
  73.         
  74.         return $visible_choice_records;
  75.     }
  76.     
  77.     
  78.     /**
  79.     * Gets a complete record of a particular choice instance.
  80.     * If successful, returns a database record of the choice, with the following items added:
  81.     * - option[] - associates option IDs with option texts
  82.     * - maxanswers[] - associates option IDs with the maximum allowable number of answers for each one
  83.     * - selections[] - associates option IDs with the number of times each one has already been selected
  84.     *
  85.     * @param object $course_module_instance A course module instance database record
  86.     * @return mixed If successful, a customized database object. Otherwise, boolean false.
  87.     * @see sloodle_get_visible_choices_in_course()
  88.     */
  89.     function sloodle_get_choice($course_module_instance)
  90.     {
  91.         // Get the choice ID
  92.         $choiceid = $course_module_instance->instance;
  93.         // Attempt to get the choice record
  94.         if (!($choice = get_record('choice', 'id', $choiceid))) return FALSE;
  95.         // Attempt to get each option as an array of record
  96.         if (!($options = get_records('choice_options', 'choiceid', $choiceid, 'id'))) return FALSE;
  97.         
  98.         // Go through each option
  99.         foreach ($options as $option) {
  100.             // Add the option and maximum number of answers to the choice object
  101.             $choice->option[$option->id] = $option->text;
  102.             $choice->maxanswers[$option->id] = $option->maxanswers;
  103.             // Determine how many times this option has already been selected
  104.             $selections = get_records('choice_answers', 'optionid', $option->id);
  105.             if (is_array($selections)) {
  106.                 // Count how many selections were made
  107.                 $choice->selections[$option->id] = count($selections);
  108.             } else {
  109.                 // None selected
  110.                 $choice->selections[$option->id] = 0;
  111.             }
  112.         }
  113.         
  114.         // Done!
  115.         return $choice;
  116.     }
  117.  
  118.     /**
  119.     * Gets the number of users on the course who have not yet answered the specified choice.
  120.     * <b>Note:</b> the count includes students and teachers.
  121.     *
  122.     * @param object $choice A choice object from the {@link:sloodle_get_choice()} function
  123.     * @return mixed If successful, a positive integer. Otherwise, a string error message.
  124.     */
  125.     function sloodle_get_num_users_not_answered_choice( $choice )
  126.     {
  127.         // Make sure we were give a valid choice record
  128.         if (!is_object($choice)) return 'Choice record not valid.';
  129.         // Make sure we can get a course number from it
  130.         if (!isset($choice->course)) return 'Course number not set in choice record.';
  131.         $course = $choice->course;
  132.         // Get a list of all users in the course
  133.         $users = get_course_users($course);
  134.         if (!is_array($users)) return 'Failed to retrieve list of course users.';
  135.         // Count that list
  136.         $num_users = count($users);
  137.         // Quick-escape: no users!
  138.         if ($num_users == 0) return 0;
  139.         
  140.         // Now count the number of people who have answered the choice already
  141.         $answers = get_records('choice_answers', 'choiceid', $choice->id);
  142.         if (!is_array($answers)) return $num_users; // Nobody has answered it 
  143.         
  144.         // Calculate the number who are left to answer (do not allow negative values -- e.g. an admin may answers, but not be on the user list)
  145.         $num_left = $num_users - count($answers);
  146.         if ($num_left < 0) $num_left = 0;
  147.         
  148.         return $num_left;
  149.     }
  150.     
  151.     /**
  152.     * Select an option from a choice.
  153.     *
  154.     * The return will either be an integer or a string.
  155.     * If an integer, then it is a {@link http://slisweb.sjsu.edu/sl/index.php/Sloodle_status_codes status code}.
  156.     * The following status codes are typical responses:
  157.     *  - 10011 = added new choice selection
  158.     *  - 10012 = updated existing choice selection
  159.     *  - -10011 = User already made a selection, and re-selection is not allowed
  160.     *  - -10012 = max number of selections for this choice already made
  161.     *  - -10013 = choice is not yet open
  162.     *  - -10014 = choice is already closed
  163.     * If a string, then it is an error message reporting that something went wrong.
  164.     *
  165.     * @param object $choice A choice object from the {@link:sloodle_get_choice()} function
  166.     * @param int $optionid The integer ID of an option (note: these are unique across an entire site)
  167.     * @param int $moodle_user_id The integer ID of the Moodle user making the selection
  168.     * @return mixed If successful, a positive integer. Otherwise, a string error message.
  169.     */
  170.     function sloodle_select_choice_option( $choice, $optionid, $moodle_user_id )
  171.     {
  172.         // Make sure we were give a valid choice record
  173.         if (!is_object($choice)) return 'Choice record not valid.';
  174.         // Make sure the choice has opened
  175.         $opentime = (int)$choice->timeopen;
  176.         $closetime = (int)$choice->timeclose;
  177.         if ($opentime > 0 && $opentime > time()) return (-10013);
  178.         if ($closetime > 0 && $closetime < time()) return (-10014);
  179.         
  180.         // Make sure the specified option belongs to the choice
  181.         if (!isset($choice->option[$optionid])) return (-10015);
  182.         
  183.         // Get a list of answers which have already been made for this choice
  184.         $answers = get_records('choice_answers', 'choiceid', $choice->id);
  185.         // Search the list to see if the user has already made a selection for this choice
  186.         $old_selection = FALSE;
  187.         foreach ($answers as $cur_answer) {
  188.             // Do the user ID's match?
  189.             if ($moodle_user_id == $cur_answer->userid) {
  190.                 // Yes - store the selection and finish
  191.                 $old_selection = $cur_answer;
  192.                 break;
  193.             }
  194.         }
  195.         
  196.         // Has the user already answered?
  197.         if ($old_selection) {
  198.             // Does this choice prohibit re-selection?
  199.             if (!$choice->allowupdate) return (-10011);
  200.             // We can just finish if the same choice is being selected again
  201.             if ($old_selection->optionid == $optionid) return 10012;
  202.         }
  203.                 
  204.         // If the answers are limited, then make sure the number of selection so far has not exceeded the maximum number
  205.         if ($choice->limitanswers && $choice->selections[$optionid] >= $choice->maxanswers[$optionid]) {
  206.             return (-10012);
  207.         }
  208.         
  209.         // Are we updating an old selection?
  210.         if ($old_selection) {
  211.             // Update
  212.             $old_selection->optionid = $optionid;
  213.             $old_selection->timemodified = time();
  214.             if (!update_record('choice_answers', $old_selection)) return 'Failed to update database.';
  215.             // Success!
  216.             return 10012;
  217.         }
  218.         
  219.         // We must be inserting a new selection
  220.         $selection = new stdClass();
  221.         $selection->choiceid = $choice->id;
  222.         $selection->userid = $moodle_user_id;
  223.         $selection->optionid = $optionid;
  224.         $selection->timemodified = time();
  225.         if (!insert_record('choice_answers', $selection)) return 'Failed to insert new database record';
  226.         // Success!
  227.         return 10011;
  228.     }
  229.     
  230.  
  231. ?>

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