<?php
/*******************************************************************************
* modulelib.php
*
* This file contains functions to be used by modules to support groups. More
* documentation is available on the Developer's Notes section of the Moodle
* wiki.
*
* For queries, suggestions for improvements etc. please post on the Groups
* forum on the moodle.org site.
******************************************************************************/
/*******************************************************************************
* Permission types
*
* There are six types of permission that a user can hold for a particular
* group - 'student view', 'student contribute', 'teacher view',
* 'teacher contribute', 'view members list' and 'view group existence'.
*
* A particular user need not to be a member of the group to have a specific
* permission and may have more than one permission type. The permission that a
* particular user has for a group used by an particular instance of the module
* depends on whether the student is a teacher or student for the course and on
* the settings for the set of groups (the 'grouping') being used by the
* instance of the module
*
* It is up to each module to decide how to interpret the different permission
* types. The only exception is with 'view members list' and 'view group
* existence'. The former means that the user can view the members of the group
* while the latter means that the user can view information such as the group
* name and description. It is possible that a user may have 'view members list'
* permission without 'view group existence' permission - the members would just
* appear as the other users on the course.
*
* Permission types can be combined with boolean expressions where they are used
* if necessary.
*
* @name GROUPS_STUDENT Either 'student view' or 'student contribute' permission
* @name GROUPS_TEACHER Either 'teacher view' or 'teacher contribute' permission
* @name GROUPS_VIEW Either 'teacher view' or 'student view' permission
* @name GROUPS_CONTRIBUTE Either 'teacher contribute' or 'student contribute'
* permission
* @name GROUPS_VIEW_GROUP_EXISTENCE 'view group existence' permission
* @name GROUPS_VIEW_MEMBERS_LIST 'view members list' permission
* @name GROUPS_STUDENT_VIEW 'student view' permission
* @name GROUPS_STUDENT_CONTRIBUTE 'student contribute' permission
* @name GROUPS_TEACHER_VIEW 'teacher view' permission
* @name GROUPS_TEACHER_CONTRIBUTE 'teacher contribute' permission
******************************************************************************/
define('GROUPS_STUDENT', 1);
define('GROUPS_TEACHER', 2);
define('GROUPS_VIEW', 4);
define('GROUPS_CONTRIBUTE', 8);
define('GROUPS_VIEW_GROUP_EXISTENCE', 16);
define('GROUPS_VIEW_MEMBERS_LIST', 48);
define('GROUPS_STUDENT_VIEW', 5);
define('GROUPS_STUDENT_CONTRIBUTE', 9);
define('GROUPS_TEACHER_VIEW', 6);
define('GROUPS_TEACHER_CONTRIBUTE', 10);
/**
* Indicates if the instance of the module has been set up by an editor of the
* course to use groups. This functionality can also be obtained using the
* groups_m_get_groups() function, however it is sufficiently commonly needed
* that this separate function has been provided and should be used instead.
* @param int $cmid The id of the module instance
* @return boolean True if the instance is set up to use groups, false otherwise
*/
function groups_m_uses_groups($cmid) {
}
/**
* Prints a dropdown box to enable a user to select between the groups for the
* module instance of which they are a member. If a user belongs to 0 or 1
* groups, no form is printed. The dropdown box belongs to a form and when a
* user clicks on the box this form is automatically submitted so that the page
* knows about the change.
* @param int $cmid The id of the module instance
* @param string $urlroot The url of the page - this is necessary so the form
* can submit to the correct page.
* @param int $permissiontype - see note on permissiontypes above.
* @return boolean True unless an error occurred or the module instance does not
* use groups in which case returns false.
*/
function groups_m_print_group_selector($cmid, $urlroot, $permissiontype) {
}
/**
* Gets the group that a student has selected from the drop-down menu printed
* by groups_m_print_group_selector and checks that the student has the
* specified permission for the group and that the group is one of the groups
* assigned for this module instance.
*
* Groups selected are saved between page changes within the module instance but
* not necessarily if the user leaves the instance e.g. returns to the main
* course page. If the selector has not been printed anywhere during the user's
* 'visit' to the module instance, then the function returns false. This means
* that you need to be particularly careful about pages that might be
* bookmarked by the user.
*
* @uses $USER
* @param int $cmid The id of the module instance
* @param int $permissiontype The permission type - see note on permission types
* above
* @param int $userid The id of the user, defaults to the current user
* @return boolean True if no error occurred, false otherwise.
*/
function groups_m_get_selected_group($cmid, $permissiontype,
$userid = $USER->id) {
}
/**
* Gets an array of the groupids of all the groups that the specified user has
* particular permission for in this particular instance of the module
* @uses $USER
* @param int $cmid The id of the module instance
* @param int $permissiontype The permission type - see note on permission types
* above
* @param int $userid The id of the user, defaults to the current user
* @return array An array of the group ids
*/
function groups_m_get_groups_for_user($cmid, $permissiontype,
$userid = $USER->id) {
}
/**
* Indicates if a specified user has a particular type of permission for a
* particular group for this module instance.
* @uses $USER
* @param int $cmid The id of the module instance. This is necessary because the
* same group can be used in different module instances with different
* permission setups.
* @param int $groupid The id of the group
* @param int $permissiontype The permission type - see note on permission types
* above
* @userid int $userid The id of the user, defaults to the current user
* @return boolean True if the user has the specified permission type, false
* otherwise or if an error occurred.
*/
function groups_m_has_permission($cmid, $groupid, $permissiontype,
$userid = $USER->id) {
}
/**
* Gets an array of members of a group that have a particular permission type
* for this instance of the module and that are enrolled on the course that
* the module instance belongs to.
*
* @param int $cmid The id of the module instance. This is necessary because the
* same group can be used in different module instances with different
* permission setups.
* @param int $groupid The id of the group
* @param int $permissiontype The permission type - see note on permission types
* above
* @return array An array containing the ids of the users with the specified
* permission.
*/
function groups_m_get_members_with_permission($cmid, $groupid,
$permissiontype) {
}
/**
* Gets the group object associated with a group id. This group object can be
* used to get information such as the name of the group and the file for the
* group icon if it exists. (Look at the groups table in the database to see
* the fields).
* @param int $groupid The id of the group
* @return group The group object
*/
function groups_m_get_group($groupid) {
}
/**
* Gets the groups for the module instance. In general, you should use
* groups_m_get_groups_for_user, however this function is provided for
* circumstances where this function isn't sufficient for some reason.
* @param int $cmid The id of the module instance.
* @return array An array of the ids of the groups for the module instance
*/
function groups_m_get_groups($cmid) {
}
/**
* Gets the members of group that are enrolled on the course that the specified
* module instance belongs to.
* @param int $cmid The id of the module instance
* @param int $groupid The id of the group
* @return array An array of the userids of the members.
*/
function groups_m_get_members($cmid, $groupid) {
}
/**
* Indicates if a user is a member of a particular group. In general you should
* use groups_m_has_permission, however this function is provided for
* circumstances where this function isn't sufficient for some reason.
* @param int $groupid The id of the group
* @param int $userid The id of the user
* @return boolean True if the user is a member of the group, false otherwise
*/
function groups_m_is_member($groupid, $userid) {
}
?>
Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: Groups API for modules.
