/**
* Distributes students into groups randomly and creates a grouping with those
* groups.
*
* You need to call groups_seed_random_number_generator() at some point in your
* script before calling this function.
*
* Note that this function does not distribute teachers into groups - this still
* needs to be done manually.
*
* @param int $courseid The id of the course that the grouping should belong to
* @param int $nostudentspergroup The number of students to put in each group -
* this can be set to false if you prefer to specify the number of groups
* instead
* @param int $nogroups The number of groups - this can be set to false if you
* prefer to specify the number of student in each group. If both are specified
* then $nostudentspergroup takes precedence. If neither is
* specified then the function does nothing and returns false.
* @param boolean $distribevenly If $noofstudentspergroup is specified, then
* if this is set to true, any leftover students are distributed evenly among
* the groups, whereas if it is set to false then they are put in a separate
* group.
* @param object $groupsettings The default settings to give each group.
* This should contain prefix and defaultgroupdescription fields. The groups
* are named with the prefix followed by 1, 2, etc. and given the
* default group description set.
* @param int $groupid If this is not set to false, then only students in the
* specified group are distributed into groups, not all the students enrolled on
* the course.
* @param boolean $alphabetical If this is set to true, then the students are
* not distributed randomly but in alphabetical order of last name.
* @return int The id of the grouping
*/
function groups_create_automatic_grouping($courseid, $nostudentspergroup, $nogroups, $distribevenly, $groupingsettings, $groupid = false, $alphabetical = false)
{
if (!$nostudentspergroup and !$noteacherspergroup and !$nogroups) {
$groupingid = false;
} else {
// Set $userids to the list of students that we want to put into groups
// in the grouping
if (!$groupid) {
$users = get_course_students($courseid);
$userids = groups_users_to_userids($users);
} else {
$userids = groups_get_members($groupid);
}
// Distribute the users into sets according to the parameters specified
$userarrays = groups_distribute_in_random_sets($userids, $nostudentspergroup, $nogroups, $distribevenly, !$alphabetical);
if (!$userarrays) {
$groupingid = false;
} else {
// Create the grouping that the groups we create will go into
$groupingid = groups_create_grouping($courseid, $groupingsettings);
// Get the prefix for the names of each group and default group
// description to give each group
if (!$groupingsettings->prefix) {
$prefix = get_string('defaultgroupprefix', 'groups');
} else {
$prefix = $groupingsettings->prefix;
}
if (!$groupingsettings->defaultgroupdescription) {
$defaultgroupdescription = '';
} else {
$defaultgroupdescription = $groupingsettings->defaultgroupdescription;
}
// Now create a group for each set of students, add the group to the
// grouping and then add the students
$i = 1;
foreach ($userarrays as $userids) {
$groupsettings->name = $prefix . ' ' . $i;
$groupsettings->description = $defaultgroupdescription;
$i++;
$groupid = groups_create_group($courseid, $groupsettings);
$groupadded = groups_add_group_to_grouping($groupid, $groupingid);
if (!$groupid or !$groupadded) {
$groupingid = false;
} else {
if ($userids) {
foreach ($userids as $userid) {
$usersadded = groups_add_member($groupid, $userid);
// If unsuccessful just carry on I guess
}
}
}
}
}
}
return $groupingid;
}
/**
* Gets the users for the course who are not in any group of a grouping.
* @param int $courseid The id of the course
* @param int $groupingid The id of the grouping
* @param int $groupid Excludes members of a particular group
* @return array An array of the userids of the users not in any group of
* the grouping or false if an error occurred.
*/
function groups_get_users_not_in_any_group_in_grouping($courseid, $groupingid, $groupid = false)
{
$users = get_course_users($courseid);
$userids = groups_users_to_userids($users);
$nongroupmembers = array();
if (!$userids) {
return $nongroupmembers;
}
foreach ($userids as $userid) {
if (!groups_is_member_of_some_group_in_grouping($userid, $groupingid)) {
// If a group has been specified don't include members of that group
if ($groupid and !groups_is_member($userid, $groupid)) {
array_push($nongroupmembers, $userid);
} else {
///array_push($nongroupmembers, $userid);
}
}
}
return $nongroupmembers;
}
/**
* Gets the users for a course who are not in a specified group
* @param int $groupid The id of the group
* @return array An array of the userids of the non-group members, or false if
* an error occurred.
*/
function groups_get_users_not_in_group($courseid, $groupid)
{
$users = get_course_users($courseid);
$userids = groups_users_to_userids($users);
$nongroupmembers = array();
foreach ($userids as $userid) {
if (!groups_is_member($groupid, $userid)) {
array_push($nongroupmembers, $userid);
}
}
return $nongroupmembers;
}
