group/lib/utillib.php

   1 <?php
   2 /**
   3  * Utility functions for groups.
   4  *
   5  * Functions we need independent of groups about users and courses.
   6  * And groups utility/ user-interface functions.
   7  *
   8  * @copyright &copy; 2006 The Open University
   9  * @author N.D.Freear AT open.ac.uk
  10  * @author J.White AT open.ac.uk
  11  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  12  * @package groups
  13  */
  14 require_once($CFG->libdir.'/moodlelib.php');
  15
  16
  17 /**********************************
  18  * Functions to get display names
  19  **********************************
  20  */
  21
  22
  23 /**
  24  * Gets the number of members of a group
  25  * @param int $groupid The group specified
  26  * @return int The number of members of the group
  27  */
  28 function groups_count_group_members($groupid) {
  29     return count_records('groups_members', 'groupid ', $groupid);
  30 }
  31
  32
  33 /**
  34  * Gets the number of groups in a specified grouping
  35  * @param int $groupingid The grouping specified
  36  * @param int $courseid The related course.
  37  * @return int The number of groups in the grouping
  38  */
  39 function groups_count_groups_in_grouping($groupingid, $courseid) {
  40     if (GROUP_NOT_IN_GROUPING == $groupingid) {
  41         $groupids = groups_get_groups_not_in_any_grouping($courseid);
  42
  43         if ($groupids === false) {
  44             return false;
  45         }
  46
  47         return count($groupids);
  48     } elseif (GROUP_ANY_GROUPING == $groupingid) {
  49         return count_records('groups_courses_groups', 'courseid', $courseid);
  50     } else {
  51         return count_records('groups_groupings_groups', 'groupingid ', $groupingid);
  52     }
  53 }
  54
  55
  56 /**
  57  * Returns the display name of a user - the full name of the user
  58  * prefixed by '#' for editing teachers and '-' for teachers.
  59  * @param int $userid The ID of the user.
  60  * @param int $courseid The ID of the related-course.
  61  * @return string The display name of the user.
  62  */
  63 function groups_get_user_displayname($userid, $courseid) {
  64     if ($courseid == false) {
  65         $fullname = false;
  66     } else {
  67         $user = groups_get_user($userid);
  68         $fullname = fullname($user, true);
  69         //TODO: isteacher, isteacheredit.
  70         if (isteacher($courseid, $userid)) {
  71             if (isteacheredit($courseid, $userid)) {
  72                 $prefix = '# ';
  73             } else {
  74                 $prefix = '- ';
  75             }
  76             $fullname = $prefix.$fullname;
  77         }
  78     }
  79     return $fullname;
  80 }
  81
  82
  83 /**
  84  * Returns the display name of a group - the group name followed by
  85  * the number of members in brackets.
  86  * @param int $groupid The group ID.
  87  * @return string The display name of the group
  88  */
  89 function groups_get_group_displayname($groupid) {
  90     if ($groupname = groups_get_group_name($groupid)) {
  91         $count = groups_count_group_members($groupid);
  92         return "$groupname ($count)";
  93     }
  94     return false;
  95 }
  96
  97
  98 /**
  99  * Returns the display name of a grouping - the grouping name followed
 100  * by the number of groups in the grouping in brackets.
 101  * @param int $groupingid The grouping ID.
 102  * @param int $courseid The related course.
 103  * @return string The display name of the grouping
 104  */
 105 function groups_get_grouping_displayname($groupingid, $courseid) {
 106     if ($groupingname = groups_get_grouping_name($groupingid)) {
 107         $count = groups_count_groups_in_grouping($groupingid, $courseid);
 108         return "$groupingname ($count)";
 109     }
 110     return false;
 111 }
 112
 113
 114 /**
 115  * Takes an array of users (i.e of objects) and converts it in the corresponding
 116  * array of user IDs.
 117  * @param $users array The array of users
 118  * @return array The array of user IDs, or false if an error occurred
 119  */
 120 function groups_users_to_userids($users) {
 121     if (! $users) {
 122         return false;
 123     }
 124     $userids = array();
 125     foreach($users as $user) {
 126         array_push($userids, $user->id);
 127     }
 128     return $userids;
 129 }
 130
 131 /**
 132  * Get an sorted array of user-id/display-name objects.
 133  */
 134 function groups_userids_to_user_names($userids, $courseid) {
 135     if (! $userids) {
 136         return array();
 137     }
 138     $member_names = array();
 139     foreach ($userids as $id) {
 140         $user = new object;
 141         $user->id = $id;
 142         $user->name = groups_get_user_displayname($id, $courseid);
 143         $member_names[] = $user;
 144     }
 145     if (! usort($member_names, 'groups_compare_name')) {
 146         debug('Error usort [groups_compare_name].');
 147     }
 148     return $member_names;
 149 }
 150
 151
 152 /**
 153  * Takes an array of groups (i.e of objects) and converts it to the
 154  * corresponding array of group IDs.
 155  * @param $groups array The array of group-like objects, only the $group->id member is required.
 156  * @return array The array of group IDs, or false if an error occurred
 157  */
 158 function groups_groups_to_groupids($groups) {
 159     if (! $groups) {
 160         return false;
 161     }
 162     $groupids = array();
 163     foreach ($groups as $group) {
 164         if (isset($group->id)) {
 165             array_push($groupids, $group->id);
 166         } else {
 167             //Warn if there's no "groupid" member.
 168             array_push($groupids, $group->groupid);
 169         }
 170     }
 171     return $groupids;
 172 }
 173
 174
 175 /**
 176  * Given an array of group IDs get an array of group objects.
 177  * TODO: quick and dirty. Replace with SQL?
 178  * @param $groupids Array of group IDs.
 179  * @param $courseid Default false, or the course ID for backwards compatibility.
 180  * @param $alldata Default false, or get complete record for group.
 181  * @return array Array of group objects INDEXED by group ID, with basic or all data.
 182  */
 183 function groups_groupids_to_groups($groupids, $courseid=false, $alldata=false) {
 184     if (! $groupids) {
 185         return false;
 186     }
 187     $groups = array();
 188     foreach ($groupids as $id) {
 189         $groups[$id] = groups_get_group_settings($id, $courseid, $alldata);
 190     }
 191     return $groups;
 192 }
 193
 194
 195 /**
 196  * Get a sorted array of group-id/display-name objects.
 197  * @param array $groupids Array of group IDs
 198  * @param bool $justnames Return names only as values, not objects. Needed
 199  *   for print_group_menu in weblib
 200  * @return array If $justnames is set, returns an array of id=>name. Otherwise
 201  *   returns an array without specific keys of objects containing id, name
 202  */
 203 function groups_groupids_to_group_names($groupids, $justnames=false) {
 204     if (! $groupids) {
 205         return array();
 206     }
 207     $group_names = array();
 208     foreach ($groupids as $id) {
 209         $gname = new object;
 210         $gname->id = $id;
 211         $gname->name = groups_get_group_displayname($id);
 212         $group_names[] = $gname;
 213     }
 214     if (! usort($group_names, 'groups_compare_name')) {
 215         debug('Error usort [groups_compare_name].');
 216     }
 217     /*// Put the groups into a hash and sort them
 218     foreach($groupids as $id) {
 219         $listgroups[$id] = groups_get_group_displayname($id);
 220     }
 221     natcasesort($listgroups);
 222
 223     $group_names = array();
 224     foreach ($listgroups as $id => $name) {
 225         $gname = new object;
 226         $gname->id = $id;
 227         $gname->name = $name;
 228         $group_names[] = $gname;
 229     }*/
 230
 231     if ($justnames) {
 232         $namesonly = array();
 233         foreach ($group_names as $id => $object) {
 234             $namesonly[$object->id] = $object->name;
 235         }
 236         return $namesonly;
 237     }
 238
 239     return $group_names;
 240 }
 241
 242
 243 /**
 244  * Comparison function for 'usort' on objects with a name member.
 245  * Equivalent to 'natcasesort'.
 246  */
 247 function groups_compare_name($obj1, $obj2) {
 248     if (!$obj1 || !$obj2 || !isset($obj1->name) || !isset($obj2->name)) {
 249         debug('Error, groups_compare_name.');
 250     }
 251     return strcasecmp($obj1->name, $obj2->name);
 252 }
 253
 254
 255 function groups_groupingids_to_groupings($groupingids) {
 256     if (! $groupingids) {
 257         return false;
 258     }
 259     $groupings = array();
 260     foreach ($groupingids as $id) {
 261         $groupings[] = groups_get_grouping_settings($id);
 262     }
 263     return $groupings;
 264 }
 265
 266 /**
 267  * Gets the user object for a given userid. Can't find a function anywhere to
 268  * do this and we need this for fullname()
 269  *
 270  * @param $userid int The userid
 271  * @return object The corresponding user object, or false if an error occurred
 272  */
 273 function groups_get_user($userid) {
 274     return groups_db_get_user($userid);
 275 }
 276
 277
 278 /**
 279  * Gets the course information object for a given course id
 280  * @param $courseid int The course id
 281  * @return object The course info object, or false if an error occurred.
 282  * TODO: need to put the database bit into a db file
 283  */
 284 function groups_get_course_info($courseid){
 285     if (!$courseid) {
 286         $courseinfo = false;
 287     } else {
 288         $courseinfo = get_record('course', 'id', $courseid);
 289     }
 290     return $courseinfo;
 291 }
 292
 293 /**
 294  * Gets the course ID for a given group.
 295  */
 296 function groups_get_course($groupid) {
 297     $course_group = get_record('groups_courses_groups', 'groupid', $groupid);
 298     if ($course_group) {
 299         return $course_group->courseid;
 300     }
 301     return false;
 302 }
 303
 304 /**
 305  * Return the address for the group settings page.
 306  * (For /user/index.php etc.)
 307  * @param $courseid
 308  * @param $groupid
 309  * @param $groupingid Default false, or optionally a grouping ID.
 310  * @param $html Default true for HTML pages, eg. on error. False for HTTP redirects.
 311  * @param $param Extra parameters.
 312  * @return string An absolute URL.
 313  */
 314 function groups_group_edit_url($courseid, $groupid, $groupingid=false, $html=true, $param=false) {
 315     global $CFG;
 316     $html ? $sep = '&amp;' : $sep = '&';
 317     $url = $CFG->wwwroot.'/group/edit.php?courseid='.$courseid;
 318     if ($groupid) {
 319         $url .= $sep.'id='.$groupid;
 320     }
 321     if ($groupingid) {
 322         $url .= $sep.'grouping='.$groupingid;
 323     }
 324     if ($param) {
 325         $url .= $sep.$param;
 326     }
 327     return $url;
 328 }
 329
 330 /**
 331  * Return the address for the grouping settings page - Internal group use only.
 332  * @param $courseid
 333  * @param $groupingid Default false, or optionally a grouping ID.
 334  * @param $html Default true for HTML pages, eg. on error. False for HTTP redirects.
 335  * @param $param Extra parameters.
 336  * @return string An absolute URL.
 337  */
 338 function groups_grouping_edit_url($courseid, $groupingid=false, $html=true, $param=false) {
 339     global $CFG;
 340     $html ? $sep = '&amp;' : $sep = '&';
 341     $url = $CFG->wwwroot.'/group/grouping.php?courseid='.$courseid;
 342     if ($groupingid) {
 343         $url .= $sep.'id='.$groupingid;
 344     }
 345     if ($param) {
 346         $url .= $sep.$param;
 347     }
 348     return $url;
 349 }
 350
 351 /**
 352  * Return the address for the add/remove users page - Internal group use only.
 353  * @param $courseid
 354  * @param $groupid
 355  * @param $groupingid Default false, or optionally a grouping ID.
 356  * @param $html Default true for HTML pages, eg. on error. False for HTTP redirects.
 357  * @return string An absolute URL.
 358  */
 359 function groups_members_add_url($courseid, $groupid, $groupingid=false, $html=true) {
 360     global $CFG;
 361     $html ? $sep = '&amp;' : $sep = '&';
 362     $url = $CFG->wwwroot.'/group/assign.php?courseid='.$courseid.$sep.'group='.$groupid;
 363     if ($groupingid) {
 364         $url .= $sep.'grouping='.$groupingid;
 365     }
 366     return $url;
 367 }
 368
 369 /**
 370  * Return the address for the main group management page. (For admin block etc.)
 371  * @param $courseid
 372  * @param $groupid Default false, or optionally a group ID.
 373  * @param $groupingid Default false, or optionally a grouping ID.
 374  * @param $html Default true for HTML pages, eg. on error. False for HTTP redirects.
 375  * @return string An absolute URL.
 376  */
 377 function groups_home_url($courseid, $groupid=false, $groupingid=false, $html=true) {
 378     global $CFG;
 379     $html ? $sep = '&amp;' : $sep = '&';
 380     $url = $CFG->wwwroot.'/group/index.php?id='.$courseid;
 381     if ($groupid) {
 382         $url .= $sep.'group='.$groupid;
 383     }
 384     if ($groupingid) {
 385         $url .= $sep.'grouping='.$groupingid;
 386     }
 387     return $url;
 388 }
 389
 390 /**
 391  * Returns the first button action with the given prefix, taken from
 392  * POST or GET, otherwise returns false.
 393  * See /lib/moodlelib.php function optional_param.
 394  * @param $prefix 'act_' as in 'action'.
 395  * @return string The action without the prefix, or false if no action found.
 396  */
 397 function groups_param_action($prefix = 'act_') {
 398     $action = false;
 399 //($_SERVER['QUERY_STRING'] && preg_match("/$prefix(.+?)=(.+)/", $_SERVER['QUERY_STRING'], $matches)) { //b_(.*?)[&;]{0,1}/
 400
 401     if ($_POST) {
 402         $form_vars = $_POST;
 403     }
 404     elseif ($_GET) {
 405         $form_vars = $_GET;
 406     }
 407     if ($form_vars) {
 408         foreach ($form_vars as $key => $value) {
 409             if (preg_match("/$prefix(.+)/", $key, $matches)) {
 410                 $action = $matches[1];
 411                 break;
 412             }
 413         }
 414     }
 415     if ($action && !preg_match('/^\w+$/', $action)) {
 416         $action = false;
 417         error('Action had wrong type.');
 418     }
 419     ///if (debugging()) echo 'Debug: '.$action;
 420     return $action;
 421 }
 422
 423 ?>