Groups API

Overview

Groups in Moodle are collections of users within a course. They may be defined by the teacher in the course settings, or created automatically during a bulk user upload (eg from a text file). Groups can optionally be grouped together into named Groupings.

In the course settings, a teacher can choose whether a course uses groups or not, and whether those groups are separate (users can only see users in their own group) or visible (can see other groups just like teachers). This setting can be forced on all activities in the course, or not, allowing a lot of flexibility. The course-level groups mode also affects what is visible in course-wide reporting like the gradebook.

Additionally, activities can optionally be made visible to only one grouping at a time. In this case only the members of the groups in that grouping will be able to see that activity. If the user is in multiple groups then they have the ability to change their "current group" - this is a sticky enviroment variable that persists for the whole session. There is an experimental feature to restrict access to an activity only to those who are members of a group (in the applicable grouping).

There is a capability 'Access all groups' that lets some users (Typically teachers and admins) access the information about all groups, without being a member of them.

Most of these settings are handled by the core groups code and core groups API. If the activity module wants to implement group support, it need only use the Groups API to:

• Find out the current settings for this instance of the activity
• Show group controls (eg group selection menus) when appropriate
• Explore memberships and structures of groups
• Modify it's own interface to hide/show data accordingly

Note that this is mostly only useful to activity modules, and perhaps some blocks.

File locations

The Groups API is all in lib/grouplib.php and is automatically included for you during the page setup.

Functions

(This should not just a regurgitation of the phpdocs, we can link to the generated phpdoc page for the details. Instead here we should group these and talk about them as an API)

function groups_group_exists($groupid)
function groups_get_group_name($groupid)
function groups_get_grouping_name($groupingid)
function groups_get_group_by_name($courseid, $name)
function groups_get_grouping_by_name($courseid, $name)
function groups_get_group($groupid, $fields='*', $strictness=IGNORE_MISSING)
function groups_get_grouping($groupingid, $fields='*', $strictness=IGNORE_MISSING)
function groups_get_all_groups($courseid, $userid=0, $groupingid=0, $fields='g.*')
function groups_get_user_groups($courseid, $userid=0)
function groups_get_all_groupings($courseid)
function groups_is_member($groupid, $userid=null)
function groups_has_membership($cm, $userid=null)
function groups_get_members($groupid, $fields='u.*', $sort='lastname ASC')
function groups_get_grouping_members($groupingid, $fields='u.*', $sort='lastname ASC')
function groups_get_course_groupmode($course)
function groups_get_activity_groupmode($cm, $course=null)
function groups_print_course_menu($course, $urlroot, $return=false)
function groups_print_activity_menu($cm, $urlroot, $return=false, $hideallparticipants=false)
function groups_get_course_group($course, $update=false, $allowedgroups=null)
function groups_get_activity_group($cm, $update=false, $allowedgroups=null)
function groups_get_activity_allowed_groups($cm,$userid=0)
function groups_course_module_visible($cm, $userid=null)