Редактирование: Development:Groups API for modules

 <?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) {
 }
 ?>