3
* A grouping is a set of groups that belong to a course.
4
* There may be any number of groupings for a course and a group may
5
* belong to more than one grouping.
7
* @copyright © 2006 The Open University
8
* @author J.White AT open.ac.uk
9
* @license http://www.gnu.org/copyleft/gpl.html GNU Public License
12
require_once($CFG->dirroot.'/group/lib/basicgrouplib.php');
13
require_once($CFG->dirroot.'/group/db/dbgroupinglib.php');
15
define('GROUP_NOT_IN_GROUPING', -1);
16
define('GROUP_ANY_GROUPING', 0);
18
/*****************************
20
*****************************/
24
* Gets a list of the groupings for a specified course
25
* @param int $courseid The id of the course
26
* @return array | false An array of the ids of the groupings, or false if there
27
* are none or there was an error.
29
function groups_get_groupings($courseid) {
30
return groups_db_get_groupings($courseid);
34
function groups_get_grouping_records($courseid) {
40
FROM {$CFG->prefix}groups_groupings gg
41
INNER JOIN {$CFG->prefix}groups_courses_groupings cg ON gg.id = cg.groupingid
42
WHERE cg.courseid = '$courseid'";
43
$groupings = get_records_sql($sql);
48
* Gets a list of the group IDs in a specified grouping
49
* @param int $groupingid The id of the grouping
50
* @return array | false. An array of the ids of the groups, or false if there
51
* are none or an error occurred.
53
function groups_get_groups_in_grouping($groupingid) {
54
return groups_db_get_groups_in_grouping($groupingid);
58
* Gets data linking a grouping to each group it contains.
59
* @param int $groupingid The ID of the grouping.
60
* @return array | false An array of grouping-group records, or false on error.
62
function groups_get_groups_in_grouping_records($groupingid) {
66
$grouping_groups = get_records('groups_groupings_groups', 'groupingid ',
67
$groupingid, '', $fields='id, groupid, timeadded');
69
return $grouping_groups;
74
* Gets the groupings that a group belongs to
75
* @param int $groupid The id of the group
76
* @return array An array of the ids of the groupings that the group belongs to,
77
* or false if there are none or if an error occurred.
79
function groups_get_groupings_for_group($groupid) {
80
return groups_db_get_groupings_for_group($groupid);
84
* Gets the information about a specified grouping
85
* @param int $groupingid
86
* @return object The grouping settings object - properties are name and
89
function groups_get_grouping_settings($groupingid) {
90
return groups_db_get_grouping_settings($groupingid);
94
* Set information about a grouping
95
* @param int $groupingid The grouping to update the info for.
96
* @param object $groupingsettings
98
function groups_set_grouping_settings($groupingid, $groupingsettings) {
99
return groups_db_set_grouping_settings($groupingid, $groupingsettings);
104
* Gets the name of a grouping with a specified ID
105
* @param int $groupid The grouping ID.
106
* @return string The name of the grouping.
108
function groups_get_grouping_name($groupingid) {
109
if (GROUP_NOT_IN_GROUPING == $groupingid) {
110
return get_string('notingrouping', 'group');
112
elseif (GROUP_ANY_GROUPING == $groupingid) {
113
return get_string('anygrouping', 'group');
115
$settings = groups_get_grouping_settings($groupingid);
116
if ($settings && isset($settings->name)) {
117
return $settings->name;
124
* Get array of group IDs for the user in a grouping.
126
* @param int $groupingid
127
* @return array If the user has groups an array of group IDs, else false.
129
function groups_get_groups_for_user_in_grouping($userid, $groupingid) {
131
$sql = "SELECT gg.groupid
132
FROM {$CFG->prefix}groups_groupings_groups gg
133
INNER JOIN {$CFG->prefix}groups_members gm ON gm.groupid = gg.groupid
134
WHERE gm.userid = '$userid'
135
AND gg.groupingid = '$groupingid'";
136
$records = get_records_sql($sql);
138
//print_object($records);
139
return groups_groups_to_groupids($records);
143
* Gets a list of the groups not in a specified grouping
144
* @param int $groupingid The grouping specified
145
* @return array An array of the group ids
147
function groups_get_groups_not_in_grouping($groupingid, $courseid) {
148
$allgroupids = groups_get_groups($courseid);
150
foreach($allgroupids as $groupid) {
151
if (!groups_belongs_to_grouping($groupid, $groupingid)) {
152
array_push($groupids, $groupid);
159
* Gets a list of the groups not in any grouping, but in this course.
160
* TODO: move to dbgroupinglib.php
161
* @param $courseid If null or false, returns groupids 'not in a grouping sitewide'.
162
* @return array An array of group IDs.
164
function groups_get_groups_not_in_any_grouping($courseid) {
170
$join = "INNER JOIN {$CFG->prefix}groups_courses_groups cg ON g.id = cg.groupid";
171
$where= "AND cg.courseid = '$courseid'";
174
FROM {$CFG->prefix}groups g
177
(SELECT groupid FROM {$CFG->prefix}groups_groupings_groups)
180
$records = get_records_sql($sql);
181
$groupids = groups_groups_to_groupids($records, $courseid);
187
* Gets the users for the course who are not in any group of a grouping.
188
* @param int $courseid The id of the course
189
* @param int $groupingid The id of the grouping
190
* @param int $groupid Excludes members of a particular group
191
* @return array An array of the userids of the users not in any group of
192
* the grouping or false if an error occurred.
194
function groups_get_users_not_in_any_group_in_grouping($courseid, $groupingid,
196
$users = get_course_users($courseid);
197
$userids = groups_users_to_userids($users);
198
$nongroupmembers = array();
200
return $nongroupmembers;
202
foreach($userids as $userid) {
203
if (!groups_is_member_of_some_group_in_grouping($userid, $groupingid)) {
204
// If a group has been specified don't include members of that group
205
if ($groupid and !groups_is_member($userid, $groupid)) {
206
array_push($nongroupmembers, $userid);
208
///array_push($nongroupmembers, $userid);
212
return $nongroupmembers;
217
* Determines if a user is in more than one group in a grouping
218
* @param int $userid The id of the user
219
* @param int $groupingid The id of the grouping
220
* @return boolean True if the user is in more than one group, false otherwise
221
* or if an error occurred.
223
function groups_user_is_in_multiple_groups($userid, $groupingid) {
224
$inmultiplegroups = false;
226
$groupids = groups_get_groups_for_user($courseid);
227
if ($groupids != false) {
228
$groupinggroupids = array();
229
foreach($groupids as $groupid) {
230
if (groups_belongs_to_grouping($groupid, $groupingid)) {
231
array_push($groupinggroupids, $groupid);
234
if (count($groupinggroupids) > 1) {
235
$inmultiplegroups = true;
238
return $inmultiplegroups;
243
* Returns an object with the default grouping settings values - these can of
244
* course be overridden if desired.
245
* Can also be used to set the default for any values not set
246
* @return object The grouping settings object.
248
function groups_set_default_grouping_settings($groupingsettings = null) {
250
if (!isset($groupingsettings->name)) {
251
$groupingsettings->name = 'Temporary Grouping Name';
254
if (!isset($groupingsettings->description)) {
255
$groupingsettings->description = '';
258
if (!isset($groupingsettings->viewowngroup)) {
259
$groupingsettings->viewowngroup = 1;
262
if (!isset($groupingsettings->viewallgroupsmembers)) {
263
$groupingsettings->viewallgroupsmembers = 0;
266
if (!isset($groupingsettings->viewallgroupsactivities)) {
267
$groupingsettings->viewallgroupsactivities = 0;
270
if (!isset($groupingsettings->teachersgroupmark)) {
271
$groupingsettings->teachersgroupmark = 0;
274
if (!isset($groupingsettings->teachersgroupview)) {
275
$groupingsettings->teachersgroupview = 0;
278
if (!isset($groupingsettings->teachersoverride)) {
279
$groupingsettings->teachersoverride = 1;
282
return $groupingsettings;
287
* Gets the grouping ID to use for a particular instance of a module in a course
288
* @param int $coursemoduleid The id of the instance of the module in the course
289
* @return int The id of the grouping or false if there is no such id recorded
290
* or if an error occurred.
292
function groups_get_grouping_for_coursemodule($coursemodule) {
293
return groups_db_get_grouping_for_coursemodule($coursemodule);
296
/*****************************
298
*****************************/
302
* Determines if a grouping with a specified id exists
303
* @param int $groupingid The grouping id.
304
* @return True if the grouping exists, false otherwise or if an error occurred.
306
function groups_grouping_exists($groupingid) {
307
return groups_db_grouping_exists($groupingid);
311
* Determine if a course ID, grouping name and description match a grouping in the database.
312
* For backup/restorelib.php
313
* @return mixed A grouping-like object with $grouping->id, or false.
315
function groups_grouping_matches($courseid, $gg_name, $gg_description) {
317
$sql = "SELECT gg.id, gg.name, gg.description
318
FROM {$CFG->prefix}groups_groupings gg
319
INNER JOIN {$CFG->prefix}groups_courses_groupings cg ON gg.id = cg.groupingid
320
WHERE gg.name = '$gg_name'
321
AND gg.description = '$gg_description'
322
AND cg.courseid = '$courseid'";
323
$records = get_records_sql($sql);
326
$grouping = array_shift($records);
332
* Determines if a group belongs to a specified grouping
333
* @param int $groupid The id of the group
334
* @param int $groupingid The id of the grouping
335
* @return boolean. True if the group belongs to a grouping, false otherwise or
336
* if an error has occurred.
338
function groups_belongs_to_grouping($groupid, $groupingid) {
339
return groups_db_belongs_to_grouping($groupid, $groupingid);
344
* Detemines if a specified user belongs to any group of a specified grouping.
345
* @param int $userid The id of the user
346
* @param int $groupingid The id of the grouping
347
* @return boolean True if the user belongs to some group in the grouping,
348
* false otherwise or if an error occurred.
350
function groups_is_member_of_some_group_in_grouping($userid, $groupingid) {
351
return groups_db_is_member_of_some_group_in_grouping($userid, $groupingid);
355
* Determines if a grouping belongs to a specified course
356
* @param int $groupingid The id of the grouping
357
* @param int $courseid The id of the course
358
* @return boolean True if the grouping belongs to the course, false otherwise,
359
* or if an error occurred.
361
function groups_grouping_belongs_to_course($groupingid, $courseid) {
362
return groups_db_grouping_belongs_to_course($groupingid, $courseid);
366
/*****************************
368
*****************************/
372
* Marks a set of groups as a grouping. This is a best effort operation.
373
* It can also be used to create an 'empty' grouping to which
374
* groups can be added by passing an empty array for the group ids.
375
* @param array $groupids An array of the ids of the groups to marks as a
377
* @param int $courseid The id of the course for which the groups should form
379
* @return int | false The id of the grouping, or false if an error occurred.
380
* Also returns false if any of the groups specified do not belong to the
383
function groups_create_grouping($courseid, $groupingsettings = false) {
384
$groupingid = groups_db_create_grouping($courseid, $groupingsettings);
391
* Adds a specified group to a specified grouping.
392
* @param int $groupid The id of the group
393
* @param int $groupingid The id of the grouping
394
* @return boolean True if the group was added successfully or the group already
395
* belonged to the grouping, false otherwise. Also returns false if the group
396
* doesn't belong to the same course as the grouping.
398
function groups_add_group_to_grouping($groupid, $groupingid) {
399
if (GROUP_NOT_IN_GROUPING == $groupingid) {
402
$belongstogrouping = groups_belongs_to_grouping($groupid, $groupingid);
404
if (!groups_grouping_exists($groupingid)) {
406
} elseif (!$belongstogrouping) {
407
$groupadded = groups_db_add_group_to_grouping($groupid, $groupingid);
416
* Sets the name of a grouping overwriting any current name that the grouping
418
* @param int $groupingid The id of the grouping specified
419
* @param string $name The name to give the grouping
420
* @return boolean True if the grouping settings was added successfully, false
423
function groups_set_grouping_name($groupingid, $name) {
424
return groups_db_set_grouping_name($groupingid, $name);
429
* Sets a grouping to use for a particular instance of a module in a course
430
* @param int $groupingid The id of the grouping
431
* @param int $coursemoduleid The id of the instance of the module in the course
432
* @return boolean True if the operation was successful, false otherwise
434
function groups_set_grouping_for_coursemodule($groupingid, $coursemoduleid) {
435
return groups_db_set_grouping_for_coursemodule($groupingid,
440
/*****************************
442
*****************************/
444
function groups_update_grouping($data, $courseid) {
445
$oldgrouping = get_record('groups_groupings', 'id', $data->id); // should not fail, already tested above
447
// Update with the new data
448
if (update_record('groups_groupings', $data)) {
450
$grouping = get_record('groups_groupings', 'id', $data->id);
452
add_to_log($grouping->id, "groups_groupings", "update", "grouping.php?courseid=$courseid&id=$grouping->id", "");
461
/*****************************
463
*****************************/
466
* Removes a specified group from a grouping. Note that this does
467
* not delete the group.
468
* @param int $groupid The id of the group.
469
* @param int $groupingid The id of the grouping
470
* @return boolean True if the deletion was successful, false otherwise.
472
function groups_remove_group_from_grouping($groupid, $groupingid) {
473
if (GROUP_NOT_IN_GROUPING == $groupingid) {
477
return groups_db_remove_group_from_grouping($groupid, $groupingid);
481
* Removes a grouping from a course - note that this function does not delete
482
* any of the groups in the grouping.
483
* @param int $groupingid The id of the grouping
484
* @return boolean True if the deletion was successful, false otherwise.
486
function groups_delete_grouping($groupingid) {
487
if (GROUP_NOT_IN_GROUPING == $groupingid) {
490
return groups_db_delete_grouping($groupingid);
494
* Delete all groupings from a course. Groups MUST be deleted first.
495
* TODO: If groups or groupings are to be shared between courses, think again!
496
* @param $courseid The course ID.
497
* @return boolean True if all deletes were successful, false otherwise.
499
function groups_delete_all_groupings($courseid) {
503
$groupingids = groups_get_groupings($courseid);
504
if (! $groupingids) {
508
foreach ($groupingids as $gg_id) {
509
$success = $success && groups_db_delete_grouping($gg_id);