group/lib/modulelib.php

   1 <?php
   2 /**
   3  * modulelib.php
   4  *
   5  * This file contains functions to be used by modules to support groups. More
   6  * documentation is available on the Developer's Notes section of the Moodle
   7  * wiki.
   8  *
   9  * For queries, suggestions for improvements etc. please post on the Groups
  10  * forum on the moodle.org site.
  11  *
  12  * @copyright &copy; 2006 The Open University
  13  * @author J.White AT open.ac.uk
  14  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  15  * @package groups
  16  */
  17
  18 /*
  19  * (OLD) Permission types
  20  *
  21  * There are six types of permission that a user can hold for a particular
  22  * group - 'student view', 'student contribute', 'teacher view',
  23  * 'teacher contribute', 'view members list' and 'view group existence'.
  24  *
  25  * A particular user need not to be a member of the group to have a specific
  26  * permission and may have more than one permission type. The permission that a
  27  * particular user has for a group used by an particular instance of the module
  28  * depends on whether the student is a teacher or student for the course and on
  29  * the settings for the set of groups (the 'grouping') being used by the
  30  * instance of the module
  31  *
  32  * It is up to each module to decide how to interpret the different permission
  33  * types. The only exception is with 'view members list' and 'view group
  34  * existence'. The former means that the user can view the members of the group
  35  * while the latter means that the user can view information such as the group
  36  * name and description. It is possible that a user may have 'view members list'
  37  * permission without 'view group existence' permission - the members would just
  38  * appear as the other users on the course.
  39  *
  40  * Permission types can be combined with boolean expressions where they are used
  41  * if necessary.
  42  *
  43  * @name GROUPS_STUDENT Either 'student view' or 'student contribute' permission
  44  * @name GROUPS_TEACHER Either 'teacher view' or 'teacher contribute' permission
  45  * @name GROUPS_VIEW Either 'teacher view' or 'student view' permission
  46  * @name GROUPS_CONTRIBUTE Either 'teacher contribute' or 'student contribute'
  47  * permission
  48  * @name GROUPS_VIEW_GROUP_EXISTENCE 'view group existence' permission
  49  * @name GROUPS_VIEW_MEMBERS_LIST 'view members list' permission
  50  * @name GROUPS_STUDENT_VIEW 'student view' permission
  51  * @name GROUPS_STUDENT_CONTRIBUTE 'student contribute' permission
  52  * @name GROUPS_TEACHER_VIEW 'teacher view' permission
  53  * @name GROUPS_TEACHER_CONTRIBUTE 'teacher contribute' permission
  54  */
  55 define('GROUPS_STUDENT', 1);
  56 define('GROUPS_TEACHER', 2);
  57 define('GROUPS_VIEW', 4);
  58 define('GROUPS_CONTRIBUTE', 8);
  59 define('GROUPS_VIEW_GROUP_EXISTENCE', 16);
  60 define('GROUPS_VIEW_MEMBERS_LIST', 48);
  61 define('GROUPS_STUDENT_VIEW', 5);
  62 define('GROUPS_STUDENT_CONTRIBUTE', 9);
  63 define('GROUPS_TEACHER_VIEW', 6);
  64 define('GROUPS_TEACHER_CONTRIBUTE', 10);
  65
  66 /**
  67  * Indicates if the instance of the module has been set up by an editor of the
  68  * course to use groups. This functionality can also be obtained using the
  69  * groups_m_get_groups() function, however it is sufficiently commonly needed
  70  * that this separate function has been provided and should be used instead.
  71  * @param int $cmid The id of the module instance
  72  * @return boolean True if the instance is set up to use groups, false otherwise
  73  */
  74 function groups_m_uses_groups($cmid) {
  75     $usesgroups = false;
  76     $groupingid = groups_db_get_groupingid($cmid);
  77     if (!$groupingid) {
  78         $usesgroups = true;
  79     }
  80
  81     return $usesgroups;
  82 }
  83
  84 /**
  85  * Prints a dropdown box to enable a user to select between the groups for the
  86  * module instance of which they are a member. If a user belongs to 0 or 1
  87  * groups, no form is printed. The dropdown box belongs to a form and when a
  88  * user clicks on the box this form is automatically submitted so that the page
  89  * knows about the change.
  90  * @param int $cmid The id of the module instance
  91  * @param string $urlroot The url of the page - this is necessary so the form
  92  * can submit to the correct page.
  93  * @param int $permissiontype - see note on permissiontypes above.
  94  * @return boolean True unless an error occurred or the module instance does not
  95  * use groups in which case returns false.
  96  */
  97 function groups_m_print_group_selector($cmid, $urlroot, $permissiontype) {
  98     // Get the groups for the cmid
  99     // Produce an array to put into the $groupsmenu array.
 100     // Add an all option if necessary.
 101     $groupids = groups_module_get_groups_for_current_user($cmid, $permissiontype);
 102
 103     // Need a line to check if current group selected.
 104     if ($groupids) {
 105         $currentgroup = groups_module_get_current_group($cmid);
 106         if ($allgroupsoption) {
 107             $groupsmenu[0] = get_string('allparticipants');
 108         }
 109
 110         foreach ($groupids as $groupid) {
 111             $groupsmenu[$groupid] = groups_get_group_name($groupid);
 112             popup_form($urlroot.'&amp;group=', $groupsmenu, 'selectgroup',
 113                 $currentgroup, '', '', '', false, 'self');
 114         }
 115     }
 116 }
 117
 118 /**
 119  * Gets the group that a student has selected from the drop-down menu printed
 120  * by groups_m_print_group_selector and checks that the student has the
 121  * specified permission for the group and that the group is one of the groups
 122  * assigned for this module instance.
 123  *
 124  * Groups selected are saved between page changes within the module instance but
 125  * not necessarily if the user leaves the instance e.g. returns to the main
 126  * course page. If the selector has not been printed anywhere during the user's
 127  * 'visit' to the module instance, then the function returns false. This means
 128  * that you need to be particularly careful about pages that might be
 129  * bookmarked by the user.
 130  *
 131  * @uses $USER
 132  * @param int $cmid The id of the module instance
 133  * @param int $permissiontype The permission type - see note on permission types
 134  * above
 135  * @param int $userid The id of the user, defaults to the current user
 136  * @return boolean True if no error occurred, false otherwise.
 137  *
 138  * TO DO - make this and other functions default to current user
 139  */
 140 function groups_m_get_selected_group($cmid, $permissiontype, $userid) {
 141     $currentgroup = optional_param('group');
 142     if (!$currentgroup) {
 143         $groupids = groups_get_groups_for_user();
 144     }
 145     // Get it from the session variable, otherwise get it from the form, otherwise
 146     // Get it from the database as the first group.
 147     // Then set the  group in the session variable to make it easier to get next time.
 148 }
 149
 150 /**
 151  * Gets an array of the group IDs of all groups for the user in this course module.
 152  * @uses $USER
 153  * @param object $cm The course-module object.
 154  * @param int $userid The ID of the user.
 155  * @return array An array of group IDs, or false.
 156  */
 157 function groups_m_get_groups_for_user($cm, $userid) {
 158 //echo 'User'; print_object($cm);
 159     $groupingid = groups_get_grouping_for_coursemodule($cm);
 160     if (!$groupingid || GROUP_NOT_IN_GROUPING == $groupingid) {
 161         return false;
 162     }
 163     if (!isset($cm->course) || !groupmode($cm->course, $cm)) {
 164         return false;
 165     }
 166     elseif (GROUP_ANY_GROUPING == $groupingid) {
 167         return groups_get_groups_for_user($userid, $cm->course);
 168     }
 169     return groups_get_groups_for_user_in_grouping($userid, $groupingid);
 170 }
 171
 172
 173 /**
 174  * Get the ID of the first group for the global $USER in the course module.
 175  * Replaces legacylib function 'mygroupid'.
 176  * @uses $USER
 177  * @param $cm A course module object.
 178  * @return int A single group ID for this user.
 179  */
 180 function groups_m_get_my_group($cm) {
 181     global $USER;
 182     $groupids = groups_m_get_groups_for_user($cm, $USER->id);
 183     if (!$groupids || count($groupids) == 0) {
 184         return 0;
 185     }
 186     return array_shift($groupids);
 187 }
 188
 189
 190 /**
 191  * Indicates if a specified user has a particular type of permission for a
 192  * particular group for this module instance.
 193  * @uses $USER
 194  * @param int $cmid The id of the module instance. This is necessary because the
 195  * same group can be used in different module instances with different
 196  * permission setups.
 197  * @param int $groupid The id of the group
 198  * @param int $permissiontype The permission type - see note on permission types
 199  * above
 200  * @userid int $userid The id of the user, defaults to the current user
 201  * @return boolean True if the user has the specified permission type, false
 202  * otherwise or if an error occurred.
 203  */
 204 function groups_m_has_permission($cm, $groupid, $permissiontype, $userid = null) {
 205     if (!$userid) {
 206         global $USER;
 207         $userid = $USER->id;
 208     }
 209     $groupingid = groups_get_grouping_for_coursemodule($cm);
 210     if (!$groupingid || !is_object($cm) || !isset($cm->course)) {
 211         return false;
 212     }
 213     $courseid = $cm->course;
 214     $isstudent = isstudent($courseid, $userid);
 215     $isteacher = isteacher($courseid, $userid);
 216     $groupmember = groups_is_member($groupid, $userid);
 217     $memberofsomegroup = groups_is_member_of_some_group_in_grouping($userid, $groupingid);
 218
 219     $groupingsettings = groups_get_grouping_settings($groupingid);
 220     $viewowngroup = $groupingsettings->viewowngroup;
 221     $viewallgroupsmembers = $groupingsettings->viewallgroupmembers;
 222     $viewallgroupsactivities = $groupingsettings->viewallgroupsactivities;
 223     $teachersgroupsmark = $groupingsettings->teachersgroupsmark;
 224     $teachersgroupsview = $groupingsettings->teachersgroupsview;
 225     $teachersgroupmark = $groupingsettings->teachersgroupmark;
 226     $teachersgroupview = $groupingsettings->teachersgroupview;
 227     $teachersoverride = $groupingsettings->teachersoverride;
 228
 229     $permission = false;
 230
 231     switch ($permissiontype) {
 232     case 'view':
 233         if (($isstudent and $groupmember) or
 234             ($isteacher and $groupmember) or
 235             ($isstudent and $viewallgroupsactivities) or
 236             ($isteacher and !$teachersgroupview) or
 237             ($isteacher and !$memberofsomegroup and $teachersoverride)) {
 238                 $permission = true;
 239             }
 240         break;
 241
 242     case 'studentcontribute':
 243         if (($isstudent and $groupmember) or
 244             ($isteacher and $groupmember) or
 245             ($isteacher and !$memberofsomegroup and $teachersoverride)) {
 246                 $permission = true;
 247             }
 248         break;
 249     case 'teachermark':
 250         if (($isteacher and $groupmember) or
 251             ($isteacher and !$teachersgroupmark) or
 252             ($isteacher and !$memberofsomegroup and $teachersoverride)) {
 253                 $permission = true;
 254             }
 255         break;
 256
 257     case 'viewmembers':
 258         if (($isstudent and $groupmember and $viewowngroup) or
 259             ($isstudent and $viewallgroupsmembers) or
 260             ($isteacher and $groupmember) or
 261             ($isteacher and !$teachersgroupview) or
 262             ($isteacher and !$memberofsomegroup and $teachersoverride) or
 263             $isteacheredit) {
 264                 $permission = true;
 265             }
 266         break;
 267     }
 268     return $permission;
 269 }
 270
 271 /**
 272  * Gets an array of members of a group that have a particular permission type
 273  * for this instance of the module and that are enrolled on the course that
 274  * the module instance belongs to.
 275  *
 276  * @param int $cmid The id of the module instance. This is necessary because the
 277  * same group can be used in different module instances with different
 278  * permission setups.
 279  * @param int $groupid The id of the group
 280  * @param int $permissiontype The permission type - see note on permission types
 281  * above
 282  * @return array An array containing the ids of the users with the specified
 283  * permission.
 284  */
 285 function groups_m_get_members_with_permission($cmid, $groupid,
 286                                               $permissiontype) {
 287     // Get all the users as $userid
 288     $validuserids = array();
 289     foreach($validuserids as $userid) {
 290         $haspermission = groups_m_has_permission($cmid, $groupid,
 291             $permissiontype, $userid);
 292         if ($haspermission) {
 293             array_push($validuserids, $userid);
 294         }
 295     }
 296     return $validuserids;
 297                                               }
 298
 299 /**
 300  * Gets the group object associated with a group id. This group object can be
 301  * used to get information such as the name of the group and the file for the
 302  * group icon if it exists. (Look at the groups table in the database to see
 303  * the fields).
 304  * @param int $groupid The id of the group
 305  * @return group The group object
 306  */
 307 function groups_m_get_group($groupid) {
 308     return groups_db_m_get_group($groupid);
 309 }
 310
 311 /**
 312  * Gets the groups for the module instance. In general, you should use
 313  * groups_m_get_groups_for_user, however this function is provided for
 314  * circumstances where this function isn't sufficient for some reason.
 315  * @param int $cmid The id of the module instance.
 316  * @return array An array of the ids of the groups for the module instance
 317  */
 318 function groups_m_get_groups($cmid) {
 319     $groupingid = groups_db_get_groupingid($cmid);
 320     $groupids = groups_get_groups_in_grouping($groupingid);
 321     return $groupids;
 322 }
 323
 324 /**
 325  * Gets the members of group that are enrolled on the course that the specified
 326  * module instance belongs to.
 327  * @param int $cmid The id of the module instance
 328  * @param int $groupid The id of the group
 329  * @return array An array of the userids of the members.
 330  */
 331 function groups_m_get_members($cmid, $groupid) {
 332     $userids = groups_get_members($groupid, $membertype);
 333     if (!$userids) {
 334         $memberids = false;
 335     } else {
 336         // Check if each user is enrolled on the course @@@ TO DO
 337     }
 338     return $memberids;
 339 }
 340
 341 /**
 342  * Stores a current group in the user's session, if not already present.
 343  *
 344  * Current group applies to all modules in the current course that share
 345  * a grouping (or use no grouping).
 346  *
 347  * This function allows the user to change group if they want, but it
 348  * checks they have permissions to access the new group and calls error()
 349  * otherwise.
 350  * @param object $cm Course-module object
 351  * @param int $groupmode Group mode
 352  * @param int $changegroup If specified, user wants to change to this group
 353  * @return Group ID
 354  */
 355 function groups_m_get_and_set_current($cm, $groupmode, $changegroup=-1) {
 356     // Check group mode is turned on
 357     if (!$groupmode) {
 358         return false;
 359     }
 360
 361     // Get current group and return it if no change requested
 362     $currentgroupid = groups_m_get_current($cm);
 363     if ($changegroup<0) {
 364         return $currentgroupid;
 365     }
 366
 367     // Check 'all groups' access
 368     $context = get_context_instance(CONTEXT_COURSE, $cm->course);
 369     $allgroups = has_capability('moodle/site:accessallgroups', $context);
 370
 371     // 0 is a special case for 'all groups'.
 372     if ($changegroup==0) {
 373         if ($groupmode!=VISIBLEGROUPS && !$allgroups) {
 374             error('You do not have access to view all groups');
 375         }
 376     } else { // Normal group specified
 377         // Check group is in the course...
 378         if (!groups_group_belongs_to_course($changegroup, $cm->course)) {
 379             error('Requested group is not in this course.');
 380         }
 381         // ...AND in the right grouping if required...
 382         if ($cm->groupingid && !groups_belongs_to_grouping($changegroup, $cm->groupingid)) {
 383             print_object($cm);
 384             print_object(groups_get_group($changegroup));
 385             error('Requested group is not in this grouping.');
 386         }
 387         // ...AND user has access to all groups, or it's in visible groups mode, or
 388         // user is a member.
 389         if (!$allgroups &&
 390           $groupmode != VISIBLEGROUPS && !groups_is_member($changegroup)) {
 391         }
 392     }
 393     // OK, now remember this group in session
 394     global $SESSION;
 395     $SESSION->currentgroupinggroup[$cm->course][$cm->groupingid] = $changegroup;
 396     return $changegroup;
 397 }
 398
 399 /**
 400  * Obtains the current group (see groups_m_get_and_set_current) either as an ID or object.
 401  * @param object $cm Course-module object
 402  * @param bool $full If true, returns group object rather than ID
 403  * @return mixed Group ID (default) or object
 404  */
 405 function groups_m_get_current($cm, $full=false) {
 406     global $SESSION;
 407     if (isset($SESSION->currentgroupinggroup[$cm->course][$cm->groupingid])) {
 408         $currentgroup = $SESSION->currentgroupinggroup[$cm->course][$cm->groupingid];
 409     } else {
 410         global $USER;
 411         if ($cm->groupingid) {
 412             $mygroupids=groups_get_groups_for_user_in_grouping($USER->id, $cm->groupingid);
 413         } else {
 414             $mygroupids=groups_get_groups_for_user($USER->id, $cm->course);
 415         }
 416         if (!$mygroupids) {
 417             return false;
 418         }
 419         $currentgroup = array_shift($mygroupids);
 420         $SESSION->currentgroupinggroup[$cm->course][$cm->groupingid]=$currentgroup;
 421     }
 422     if ($full) {
 423         return groups_groupid_to_group($currentgroup);
 424     } else {
 425         return $currentgroup;
 426     }
 427 }
 428
 429 ?>