← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/moodle/jaunty

« back to all changes in this revision

Viewing changes to group/lib/modulelib.php

  • Committer: Bazaar Package Importer
  • Author(s): Jordan Mantha, Matt Oquist
  • Date: 2009-02-25 15:16:22 UTC
  • mfrom: (1.1.11 upstream)
  • Revision ID: james.westby@ubuntu.com-20090225151622-0ekt1liwhv2obfza
Tags: 1.9.4.dfsg-0ubuntu1
https://launchpad.net/bugs/322961
https://launchpad.net/bugs/239481
https://launchpad.net/bugs/334611
https://launchpad.net/bugs/225662
https://launchpad.net/bugs/325450
https://launchpad.net/bugs/327843
https://launchpad.net/bugs/303078
https://launchpad.net/bugs/234609
* Merge with Debian git (Closes LP: #322961, #239481, #334611):
  - use Ubuntu's smarty lib directory for linking
  - use internal yui library 
  - add update-notifier support back in

[Matt Oquist]
  * renamed prerm script
  * significantly rewrote postinst and other maintainer scripts to improve
    user experience and package maintainability
    (Closes LP: #225662, #325450, #327843, #303078, #234609)

Show diffs side-by-side

added added

removed removed

Lines of Context:
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) { //TODO: check.
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_get_group($currentgroup, false);
424
 
    } else {
425
 
        return $currentgroup;
426
 
    }
427
 
}
428
 
 
429
 
?>
 
 
b'\\ No newline at end of file'