Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Groups API: Difference between revisions

From MoodleDocs
m (Protected "Groups API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite)))
 
(39 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{Template:Migrated|newDocId=/docs/apis/subsystems/group/}}
==Overview==
==Overview==


The groups API is a core system in Moodle which allows for:
[https://docs.moodle.org/22/en/Groups 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 [https://docs.moodle.org/en/Groupings Groupings].


*Creating and deleting of groups and 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.
*Adding and removing members from a group.
*Polling of information regarding accessibility and permissions.


==Database Structure==
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 are four core tables for Groups.
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.


===groupings===
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:
A grouping is a collection of groups.


{| border="1" cellpadding="2" cellspacing="0"
* Find out the current settings for this instance of the activity
|'''Field'''
* Show group controls (eg group selection menus) when appropriate
|'''Type'''
* Explore memberships and structures of groups
|'''Info'''
* Modify it's own interface to hide/show data accordingly
|-
|id
|int(10)
|auto increment identifier
|-
|courseid
|int(10)
|The course id
|-
|name
|varchar(255)
|Name of the grouping
|-
|description
|text
|Description of the grouping
|-
|descriptionformat
|int(2)
|The format of the description
|-
|configdata
|text
|Configuration data
|-
|timecreated
|int(10)
|The time that the grouping was created
|-
|timemodified
|into(10)
|The time last changes were made
|}


===groupings_groups===
Note that this is mostly only useful to activity modules, and perhaps some blocks.
This table links a grouping to a group. There can be multiple groups in a grouping.


{| border="1" cellpadding="2" cellspacing="0"
==Group modes==
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|groupingid
|int(10)
|The grouping id
|-
|groupid
|int(10)
|The group id
|-
|timeadded
|int(10)
|Time that the group was added to the grouping
|}


===groups===
There are three different group modes, these modes allow for restrictions to be put in place for access and visibility.
Each record represents a group.


{| border="1" cellpadding="2" cellspacing="0"
*No groups - The course or activity has no groups.
|'''Field'''
*Separate groups - Teachers and students can normally only see information relevant to that group.
|'''Type'''
*Visible groups - Teachers and students are separated into groups but can still see all information.
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|courseid
|int(10)
|The id of the course
|-
|name
|varchar(255)
|The name of the group
|-
|description
|text
|A description of the group
|-
|descriptionformat
|int(2)
|Format for the description
|-
|enrolmentkey
|varchar(50)
|The key used when self enrolling into a course. This will automatically put the student into a specific group.
|-
|picture
|int(10)
|picture for the group
|-
|hidepicture
|int(1)
|Whether the group picture is displayed or hidden
|-
|timecreated
|int(10)
|The time that the group was created
|-
|timemodified
|int(10)
|The last time that the group details were changed
|}


===groups_members===
This is explained in more detail on the [[Groups access control]] page.
This table links a user to a group.


{| border="1" cellpadding="2" cellspacing="0"
==File locations==
|'''Field'''
 
|'''Type'''
The Groups API is all in [https://github.com/moodle/moodle/blob/master/lib/grouplib.php lib/grouplib.php] and is automatically included for you during the page setup.
|'''Info'''
 
|-
==Functions==
|id
 
|int(10)
 
|auto increment identifier
*'''get group information'''
|-
**groups_group_exists($groupid)
|groupid
**groups_get_group_name($groupid)
|int(10)
**groups_get_group_by_name($courseid, $name)
|The id of the group  
**groups_get_group_by_idnumber($courseid, $idnumber)
|-
**groups_get_group($groupid, $fields='*', $strictness=IGNORE_MISSING)
|userid
**groups_get_all_groups($courseid, $userid=0, $groupingid=0, $fields='g.*')
|int(10)
**groups_get_user_groups($courseid, $userid=0)
|The user's id
 
|-
*'''get grouping information'''
|timeadded
**groups_get_grouping_name($groupingid)
|int(10)
**groups_get_grouping_by_name($courseid, $name)
|Time the group member was added
**groups_get_grouping($groupingid, $fields='*', $strictness=IGNORE_MISSING)
|}
**groups_get_all_groupings($courseid)
 
*'''print group information'''
**groups_print_course_menu($course, $urlroot, $return=false)
**groups_print_activity_menu($cm, $urlroot, $return=false, $hideallparticipants=false)
 
*'''group membership'''
**groups_is_member($groupid, $userid=null)
**groups_has_membership($cm, $userid=null)
**groups_get_members($groupid, $fields='u.*', $sort='lastname ASC')
**groups_get_grouping_members($groupingid, $fields='u.*', $sort='lastname ASC')
 
*'''course'''
**groups_get_course_groupmode($course)
**groups_get_course_group($course, $update=false, $allowedgroups=null)
**groups_course_module_visible($cm, $userid=null)
 
*'''activity'''
**groups_get_activity_groupmode($cm, $course=null)
**groups_get_activity_group($cm, $update=false, $allowedgroups=null)
**groups_get_activity_allowed_groups($cm,$userid=0)
 
==Examples==
 
===How to find and use the "current" group===
 
This is using an example from the module forums.
 
<syntaxhighlight lang="php">
// Get the course module id from a post or get request.
$id = required_param('id', PARAM_INT);
 
// Get the course module.
$cm = get_coursemodule_from_id('forum', $id, 0, false, MUST_EXIST)
 
// Get the current group id.
$currentgroupid = groups_get_activity_group($cm);
// Get the current group name from the group id.
$currentgroupname = groups_get_group_name($currentgroupid);
 
// Do as you please with your newly obtained group information.
</syntaxhighlight>
 
===How to make sure that the current user can see a given item in your module ===
 
For this example we are going to check to see if groups are active and whether the user has access to the discussion.
 
<syntaxhighlight lang="php">
// Get the course module and discussion id from a post or get request.
$id           = required_param('id', PARAM_INT);
$discussionid = required_param('discussionid', PARAM_INT);
 
// Get the course module.
$cm = get_coursemodule_from_id('forum', $id, 0, false, MUST_EXIST);
 
// Get the group id for this discussion
$discussiongroup = $DB->get_record('forum_discussions', array('id' => $discussionid), groupid);
 
// Check access.
if (groups_get_activity_groupmode($cm)) {
    $groups = groups_get_activity_allowed_groups($cm);
} else {
    $groups = array();
}
if (! in_array($discussiongroup->groupid, array_keys($groups))) {
    print_error('groupnotamember', 'group');
}
 
// Continue on with group specific discussion
</syntaxhighlight>
 
===How to display a group menu===
 
This will display a drop down box with a label of the current group visibility (seperate groups, visibile groups).
It will also check to see what groups the user has access to and display the group options accordingly.
 
<syntaxhighlight lang="php">
// Get the course module id from a post or get request
$id = required_param('id', PARAM_INT);
 
// Get the course module
$cm = get_coursemodule_from_id('forum', $id, 0, false, MUST_EXIST);
 
// Create a moodle_url. A URL is required so that if the user selects a different group, the page can be
// reloaded with the new groups information.
$url = new moodle_url('/mod/forum/view.php', array('id' => $cm->id));
 
// Print group information (A drop down box will be displayed if the user is a member of more than one group,
// or has access to all groups).
groups_print_activity_menu($cm, $url);
</syntaxhighlight>
 
=== New group/lib.php ===
 
https://github.com/moodle/moodle/blob/master/group/lib.php
 
* groups_add_member($grouporid, $userorid)
* groups_remove_member($grouporid, $userorid)
* groups_create_group($data, $editform=false, $editoroptions=null)
* groups_create_grouping($data, $editoroptions=null)
* groups_update_group($data, $editform=false)
* groups_update_grouping($data, $editoroptions=null)
* groups_delete_group($grouporid)
* groups_delete_grouping($groupingorid)
* groups_delete_group_members($courseid, $userid=0, $showfeedback=false)
* groups_delete_groupings_groups($courseid, $showfeedback=false)
* groups_delete_groups($courseid, $showfeedback=false)
* groups_delete_groupings($courseid, $showfeedback=false)
* groups_assign_grouping($groupingid, $groupid)
* groups_unassign_grouping($groupingid, $groupid)
* groups_get_members_by_role($groupid, $courseid, $fields='u.*', $sort='u.lastname ASC', $extrawheretest='', $whereparams=array())
* groups_group_exists($groupid)
* groups_get_group_name($groupid)
* groups_get_grouping_name($groupingid)
* groups_get_group_by_name($courseid, $name)
* groups_get_grouping_by_name($courseid, $name)
* groups_get_group($groupid, $fields='*', $strictness=IGNORE_MISSING)
* groups_get_grouping($groupingid, $fields='*', $strictness=IGNORE_MISSING)
* groups_get_all_groups($courseid, $userid=0, $groupingid=0, $fields='g.*')
* groups_get_user_groups($courseid, $userid=0)
* groups_get_all_groupings($courseid)
* groups_is_member($groupid, $userid=null)
* groups_has_membership($cm, $userid=null)
* groups_get_members($groupid, $fields='u.*', $sort='lastname ASC')
* groups_get_grouping_members($groupingid, $fields='u.*', $sort='lastname ASC')
* groups_get_course_groupmode($course)
* groups_get_activity_groupmode($cm, $course=null)
* groups_get_course_group($course, $update=false)
* groups_get_activity_group($cm, $update=false)
* groups_get_activity_allowed_groups($cm,$userid=0)
* groups_print_course_menu($course, $urlroot, $return=false)
* groups_print_activity_menu($cm, $urlroot, $return=false, $hideallparticipants=false)
* groups_course_module_visible($cm, $userid=null)
 
===Examples===
<syntaxhighlight lang="php">
require_once($CFG->dirroot.'/group/lib.php');
 
$data = new stdClass();
$data->courseid = $COURSE->id;
$data->idnumber = 'someidnumber';
$data->name = 'group name';
$data->description = 'group description';
$data->descriptionformat = FORMAT_HTML;
 
$newgroupid = groups_create_group($data);
</syntaxhighlight>
 
==Further reading==
 
* [https://docs.moodle.org/22/en/Available_for_group_members_only Available for group members only]
* [https://docs.moodle.org/20/en/Groups_FAQ Groups FAQ]
* [https://docs.moodle.org/22/en/Groupings_FAQ Groupings FAQ]

Latest revision as of 11:07, 17 June 2022

Important:

This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date.

Why not view this page on the new site and help us to migrate more content to the new site!

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.

Group modes

There are three different group modes, these modes allow for restrictions to be put in place for access and visibility.

  • No groups - The course or activity has no groups.
  • Separate groups - Teachers and students can normally only see information relevant to that group.
  • Visible groups - Teachers and students are separated into groups but can still see all information.

This is explained in more detail on the Groups access control page.

File locations

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

Functions

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

Examples

How to find and use the "current" group

This is using an example from the module forums.

// Get the course module id from a post or get request.
$id = required_param('id', PARAM_INT); 

// Get the course module. 
$cm = get_coursemodule_from_id('forum', $id, 0, false, MUST_EXIST)

// Get the current group id.
$currentgroupid = groups_get_activity_group($cm);
// Get the current group name from the group id.
$currentgroupname = groups_get_group_name($currentgroupid);

// Do as you please with your newly obtained group information.

How to make sure that the current user can see a given item in your module

For this example we are going to check to see if groups are active and whether the user has access to the discussion.

// Get the course module and discussion id from a post or get request.
$id           = required_param('id', PARAM_INT);
$discussionid = required_param('discussionid', PARAM_INT);

// Get the course module.
$cm = get_coursemodule_from_id('forum', $id, 0, false, MUST_EXIST);

// Get the group id for this discussion
$discussiongroup = $DB->get_record('forum_discussions', array('id' => $discussionid), groupid);

// Check access.
if (groups_get_activity_groupmode($cm)) {
    $groups = groups_get_activity_allowed_groups($cm);
} else {
    $groups = array();
}
if (! in_array($discussiongroup->groupid, array_keys($groups))) {
    print_error('groupnotamember', 'group');
}

// Continue on with group specific discussion

How to display a group menu

This will display a drop down box with a label of the current group visibility (seperate groups, visibile groups). It will also check to see what groups the user has access to and display the group options accordingly.

// Get the course module id from a post or get request
$id = required_param('id', PARAM_INT); 

// Get the course module
$cm = get_coursemodule_from_id('forum', $id, 0, false, MUST_EXIST); 

// Create a moodle_url. A URL is required so that if the user selects a different group, the page can be
// reloaded with the new groups information.
$url = new moodle_url('/mod/forum/view.php', array('id' => $cm->id));

// Print group information (A drop down box will be displayed if the user is a member of more than one group, 
// or has access to all groups). 
groups_print_activity_menu($cm, $url);

New group/lib.php

https://github.com/moodle/moodle/blob/master/group/lib.php

  • groups_add_member($grouporid, $userorid)
  • groups_remove_member($grouporid, $userorid)
  • groups_create_group($data, $editform=false, $editoroptions=null)
  • groups_create_grouping($data, $editoroptions=null)
  • groups_update_group($data, $editform=false)
  • groups_update_grouping($data, $editoroptions=null)
  • groups_delete_group($grouporid)
  • groups_delete_grouping($groupingorid)
  • groups_delete_group_members($courseid, $userid=0, $showfeedback=false)
  • groups_delete_groupings_groups($courseid, $showfeedback=false)
  • groups_delete_groups($courseid, $showfeedback=false)
  • groups_delete_groupings($courseid, $showfeedback=false)
  • groups_assign_grouping($groupingid, $groupid)
  • groups_unassign_grouping($groupingid, $groupid)
  • groups_get_members_by_role($groupid, $courseid, $fields='u.*', $sort='u.lastname ASC', $extrawheretest=, $whereparams=array())
  • groups_group_exists($groupid)
  • groups_get_group_name($groupid)
  • groups_get_grouping_name($groupingid)
  • groups_get_group_by_name($courseid, $name)
  • groups_get_grouping_by_name($courseid, $name)
  • groups_get_group($groupid, $fields='*', $strictness=IGNORE_MISSING)
  • groups_get_grouping($groupingid, $fields='*', $strictness=IGNORE_MISSING)
  • groups_get_all_groups($courseid, $userid=0, $groupingid=0, $fields='g.*')
  • groups_get_user_groups($courseid, $userid=0)
  • groups_get_all_groupings($courseid)
  • groups_is_member($groupid, $userid=null)
  • groups_has_membership($cm, $userid=null)
  • groups_get_members($groupid, $fields='u.*', $sort='lastname ASC')
  • groups_get_grouping_members($groupingid, $fields='u.*', $sort='lastname ASC')
  • groups_get_course_groupmode($course)
  • groups_get_activity_groupmode($cm, $course=null)
  • groups_get_course_group($course, $update=false)
  • groups_get_activity_group($cm, $update=false)
  • groups_get_activity_allowed_groups($cm,$userid=0)
  • groups_print_course_menu($course, $urlroot, $return=false)
  • groups_print_activity_menu($cm, $urlroot, $return=false, $hideallparticipants=false)
  • groups_course_module_visible($cm, $userid=null)

Examples

require_once($CFG->dirroot.'/group/lib.php');

$data = new stdClass();
$data->courseid = $COURSE->id;
$data->idnumber = 'someidnumber';
$data->name = 'group name';
$data->description = 'group description';
$data->descriptionformat = FORMAT_HTML;

$newgroupid = groups_create_group($data);

Further reading