grade/report/lib.php

   1 <?php // $Id$
   2 /**
   3  * File containing the grade_report class.
   4  * @package gradebook
   5  */
   6
   7 require_once($CFG->libdir.'/gradelib.php');
   8
   9 /**
  10  * An abstract class containing variables and methods used by all or most reports.
  11  * @abstract
  12  * @package gradebook
  13  */
  14 class grade_report {
  15     /**
  16      * The courseid.
  17      * @var int $courseid
  18      */
  19     var $courseid;
  20
  21     /** Grade plugin return tracking object.
  22     var $gpr;
  23
  24     /**
  25      * The context.
  26      * @var int $context
  27      */
  28     var $context;
  29
  30     /**
  31      * The grade_tree object.
  32      * @var object $gtree
  33      */
  34     var $gtree;
  35
  36     /**
  37      * User preferences related to this report.
  38      * @var array $prefs
  39      */
  40     var $prefs = array();
  41
  42     /**
  43      * The roles for this report.
  44      * @var string $gradebookroles
  45      */
  46     var $gradebookroles;
  47
  48     /**
  49      * base url for sorting by first/last name.
  50      * @var string $baseurl
  51      */
  52     var $baseurl;
  53
  54     /**
  55      * base url for paging.
  56      * @var string $pbarurl
  57      */
  58     var $pbarurl;
  59
  60     /**
  61      * Current page (for paging).
  62      * @var int $page
  63      */
  64     var $page;
  65
  66     /**
  67      * Array of cached language strings (using get_string() all the time takes a long time!).
  68      * @var array $lang_strings
  69      */
  70     var $lang_strings = array();
  71
  72 //// GROUP VARIABLES (including SQL)
  73
  74     /**
  75      * The current group being displayed.
  76      * @var int $currentgroup
  77      */
  78     var $currentgroup;
  79
  80     /**
  81      * A HTML select element used to select the current group.
  82      * @var string $group_selector
  83      */
  84     var $group_selector;
  85
  86     /**
  87      * An SQL fragment used to add linking information to the group tables.
  88      * @var string $groupsql
  89      */
  90     var $groupsql;
  91
  92     /**
  93      * An SQL constraint to append to the queries used by this object to build the report.
  94      * @var string $groupwheresql
  95      */
  96     var $groupwheresql;
  97
  98
  99     /**
 100      * Constructor. Sets local copies of user preferences and initialises grade_tree.
 101      * @param int $courseid
 102      * @param object $gpr grade plugin return tracking object
 103      * @param string $context
 104      * @param int $page The current page being viewed (when report is paged)
 105      */
 106     function grade_report($courseid, $gpr, $context, $page=null) {
 107         global $CFG;
 108
 109         $this->courseid  = $courseid;
 110         $this->gpr       = $gpr;
 111         $this->context   = $context;
 112         $this->page      = $page;
 113
 114         // roles to be displayed in the gradebook
 115         $this->gradebookroles = $CFG->gradebookroles;
 116
 117         // init gtree in child class
 118     }
 119
 120     /**
 121      * Given the name of a user preference (without grade_report_ prefix), locally saves then returns
 122      * the value of that preference. If the preference has already been fetched before,
 123      * the saved value is returned. If the preference is not set at the User level, the $CFG equivalent
 124      * is given (site default).
 125      * @static (Can be called statically, but then doesn't benefit from caching)
 126      * @param string $pref The name of the preference (do not include the grade_report_ prefix)
 127      * @param int $objectid An optional itemid or categoryid to check for a more fine-grained preference
 128      * @return mixed The value of the preference
 129      */
 130     function get_pref($pref, $objectid=null) {
 131         global $CFG;
 132         $fullprefname = 'grade_report_' . $pref;
 133
 134         $retval = null;
 135
 136         if (!isset($this) OR get_class($this) != 'grade_report') {
 137             if (!empty($objectid)) {
 138                 $retval = get_user_preferences($fullprefname . $objectid, grade_report::get_pref($pref));
 139             } else {
 140                 $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
 141             }
 142         } else {
 143             if (empty($this->prefs[$pref.$objectid])) {
 144
 145                 if (!empty($objectid)) {
 146                     $retval = get_user_preferences($fullprefname . $objectid);
 147                     if (empty($retval)) {
 148                         // No item pref found, we are returning the global preference
 149                         $retval = $this->get_pref($pref);
 150                         $objectid = null;
 151                     }
 152                 } else {
 153                     $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
 154                 }
 155                 $this->prefs[$pref.$objectid] = $retval;
 156             } else {
 157                 $retval = $this->prefs[$pref.$objectid];
 158             }
 159         }
 160
 161         return $retval;
 162     }
 163
 164     /**
 165      * Uses set_user_preferences() to update the value of a user preference. If 'default' is given as the value,
 166      * the preference will be removed in favour of a higher-level preference.
 167      * @static
 168      * @param string $pref_name The name of the preference.
 169      * @param mixed $pref_value The value of the preference.
 170      * @param int $itemid An optional itemid to which the preference will be assigned
 171      * @return bool Success or failure.
 172      * TODO print visual feedback
 173      */
 174     function set_pref($pref, $pref_value='default', $itemid=null) {
 175         $fullprefname = 'grade_report_' . $pref;
 176         if ($pref_value == 'default') {
 177             return unset_user_preference($fullprefname.$itemid);
 178         } else {
 179             return set_user_preference($fullprefname.$itemid, $pref_value);
 180         }
 181     }
 182
 183     /**
 184      * Handles form data sent by this report for this report. Abstract method to implement in all children.
 185      * @abstract
 186      * @param array $data
 187      * @return mixed True or array of errors
 188      */
 189     function process_data($data) {
 190         // Implement in children classes
 191     }
 192
 193     /**
 194      * Processes a single action against a category, grade_item or grade.
 195      * @param string $target Sortorder
 196      * @param string $action Which action to take (edit, delete etc...)
 197      * @return
 198      */
 199     function process_action($target, $action) {
 200         //implement if needed
 201     }
 202
 203     /**
 204      * format grade using lang specific decimal point and thousand separator
 205      * the result is suitable for printing on html page
 206      * @static
 207      * @param float $gradeval raw grade value pulled from db
 208      * @param int $decimalpoints Optional integers to override global decimalpoints preference
 209      * @return string $gradeval formatted grade value
 210      */
 211     function get_grade_clean($gradeval, $decimalpoints=null) {
 212         global $CFG;
 213
 214         if (is_null($gradeval)) {
 215             $gradeval = '';
 216         } else {
 217             // decimal points as specified by user
 218             if (is_null($decimalpoints)) {
 219                 $decimalpoints = $this->get_pref('decimalpoints');
 220             }
 221             $gradeval = number_format($gradeval, $decimalpoints, $this->get_lang_string('decpoint', 'langconfig'),
 222                                       $this->get_lang_string('thousandsep', 'langconfig'));
 223         }
 224
 225         return $gradeval;
 226
 227         /*
 228         // commenting this out, if this is added, we also need to find the number of decimal place preserved
 229         // so it can go into number_format
 230         if ($gradeval != 0) {
 231             $gradeval = rtrim(trim($gradeval, "0"), ".");
 232         } else {
 233             $gradeval = 0;
 234         }
 235         */
 236
 237     }
 238
 239     /**
 240      * Given a user input grade, format it to standard format i.e. no thousand separator, and . as decimal point
 241      * @static
 242      * @param string $gradeval grade value from user input, language specific format
 243      * @return string - grade value for storage, en format
 244      */
 245     function format_grade($gradeval) {
 246
 247         $decimalpt = $this->get_lang_string('decpoint', 'langconfig');
 248         $thousandsep = $this->get_lang_string('thousandsep', 'langconfig');
 249         // replace decimal point with '.';
 250         $gradeval = str_replace($decimalpt, '.', $gradeval);
 251         // thousand separator is not useful
 252         $gradeval = str_replace($thousandsep, '', $gradeval);
 253
 254         return clean_param($gradeval, PARAM_NUMBER);
 255     }
 256
 257     /**
 258      * First checks the cached language strings, then returns match if found, or uses get_string()
 259      * to get it from the DB, caches it then returns it.
 260      * @param string $strcode
 261      * @param string $section Optional language section
 262      * @return string
 263      */
 264     function get_lang_string($strcode, $section=null) {
 265         if (empty($this->lang_strings[$strcode])) {
 266             $this->lang_strings[$strcode] = get_string($strcode, $section);
 267         }
 268         return $this->lang_strings[$strcode];
 269     }
 270
 271     /**
 272      * Computes then returns the percentage value of the grade value within the given range.
 273      * @param float $gradeval
 274      * @param float $grademin
 275      * @param float $grademx
 276      * @return float $percentage
 277      */
 278     function grade_to_percentage($gradeval, $grademin, $grademax) {
 279         if ($grademin >= $grademax) {
 280             debugging("The minimum grade ($grademin) was higher than or equal to the maximum grade ($grademax)!!! Cannot proceed with computation.");
 281         }
 282         $offset_value = $gradeval - $grademin;
 283         $offset_max = $grademax - $grademin;
 284         $factor = 100 / $offset_max;
 285         $percentage = $offset_value * $factor;
 286         return $percentage;
 287     }
 288
 289     /**
 290      * Fetches and returns an array of grade letters indexed by their grade boundaries, as stored in preferences.
 291      * @return array
 292      */
 293     function get_grade_letters() {
 294         $letters = array();
 295         for ($i = 1; $i <= 10; $i++) {
 296             $boundary = grade_report::get_pref('gradeboundary' . $i);
 297             $letter = grade_report::get_pref('gradeletter' . $i);
 298             if (!is_null($boundary) && $boundary != -1 && !empty($letter)) {
 299                 $letters[$boundary] = $letter;
 300             }
 301         }
 302         return $letters;
 303     }
 304
 305     /**
 306      * Fetches and returns a count of all the users that will be shown on this page.
 307      * @return int Count of users
 308      */
 309     function get_numusers() {
 310         global $CFG;
 311
 312         $countsql = "SELECT COUNT(DISTINCT u.id)
 313                     FROM {$CFG->prefix}grade_grades g RIGHT OUTER JOIN
 314                          {$CFG->prefix}user u ON u.id = g.userid
 315                          LEFT JOIN {$CFG->prefix}role_assignments ra ON u.id = ra.userid
 316                          $this->groupsql
 317                     WHERE ra.roleid in ($this->gradebookroles)
 318                          $this->groupwheresql
 319                     AND ra.contextid ".get_related_contexts_string($this->context);
 320         return count_records_sql($countsql);
 321     }
 322
 323     /**
 324      * Sets up this object's group variables, mainly to restrict the selection of users to display.
 325      */
 326     function setup_groups() {
 327         global $CFG;
 328
 329         /// find out current groups mode
 330         $course = get_record('course', 'id', $this->courseid);
 331         $groupmode = $course->groupmode;
 332         ob_start();
 333         $this->currentgroup = setup_and_print_groups($course, $groupmode, $this->pbarurl);
 334         $this->group_selector = ob_get_clean();
 335
 336         // update paging after group
 337         $this->baseurl .= 'group='.$this->currentgroup.'&amp;';
 338         $this->pbarurl .= 'group='.$this->currentgroup.'&amp;';
 339
 340         if ($this->currentgroup) {
 341             $this->groupsql = " LEFT JOIN {$CFG->prefix}groups_members gm ON gm.userid = u.id ";
 342             $this->groupwheresql = " AND gm.groupid = $this->currentgroup ";
 343         }
 344     }
 345 }
 346 ?>