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
mNo edit summary
(Complete rewrite to try and give some direction)
Line 1: Line 1:
==Overview==
==Overview==


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


* Creating and deleting of groups and groupings.
Groups can optionally be grouped together into Groupings.
* Adding and removing groups from a grouping.
* Adding and removing members from a group.
* Obtaining information regarding accessibility and permissions.


==Creation and deletion methods==
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.


These methods are located in group/lib.php
Additionally, activities can be made visible to 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.


* Creating a group.
All of these settings are done OUTSIDE the activity module.
* Deleting a group.
* Creating a grouping.
* Deleting a grouping.
* Adding a group to a grouping.
* Removing a group from a grouping.
* Adding members to a group.
* Removing members to a group.


==Obtaining accessibility information==
If the activity module wants to implement group support, it needs to use the Groups API to:


These methods are located in lib/grouplib.php
* 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


* Getting activities allowed for a group.
* Getting all groups.
* Getting a group by a name.
* Getting all groupings.
* Getting the members of a grouping.
* Checking to see if a group exists.
* Checking to see if there are any users in a group.
* Checking whether a user is part of a group.
* Verifying an active group.


==Database Structure==
==File locations==


There are four core tables for Groups.
The main Groups API is all contained in lib/grouplib.php and that is all you need to include.


===groupings===
A grouping is a collection of groups.


{| border="1" cellpadding="2" cellspacing="0"
==Functions==
|'''Field'''
|'''Type'''
|'''Info'''
|-
|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===
function groups_group_exists($groupid)
This table links a grouping to a group. There can be multiple groups in a grouping.
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)


{| border="1" cellpadding="2" cellspacing="0"
|'''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===
==Examples==
Each record represents a group.


{| border="1" cellpadding="2" cellspacing="0"
===How to find and use the "current" group===
|'''Field'''
|'''Type'''
|'''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===
===How to make sure that the current user can see a given item in your module ===
This table links a user to a group.
 
{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|groupid
|int(10)
|The id of the group
|-
|userid
|int(10)
|The user's id
|-
|timeadded
|int(10)
|Time the group member was added
|}

Revision as of 09:20, 10 January 2012

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). See Groups in the main documentation.

Groups can optionally be grouped together into 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.

Additionally, activities can be made visible to 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.

All of these settings are done OUTSIDE the activity module.

If the activity module wants to implement group support, it needs to 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


File locations

The main Groups API is all contained in lib/grouplib.php and that is all you need to include.


Functions

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)


Examples

How to find and use the "current" group

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

Retrieved from "https://docs.moodle.org/dev/index.php?title=Groups_API&oldid=31197"
Powered by MediaWiki