define(
        getGroupData
        getGroupInformation
        getGroupAuthorizableData
        createGroup
        deleteGroup
        updateGroupInfo
        updateGroupProfile
        isValidPermissionsProperty
        setPermissions
        isCurrentUserAManager
        isCurrentUserAMember
        isAllowedToLeave
        getManagerCount
        addJoinRequest
        removeJoinRequest
        getJoinRequests
        searchMembers
        getMembers
        hasManagementRights
        getProfilePicture
        prepareGroupsForRender
        changeUsersPermission
        addUsersToGroup
        addContentToGroup
        removeUsersFromGroup
        removeContentFromGroup
define(

class Groups
description Group related convenience functions. This should only hold functions which are used across multiple pages, and does not constitute functionality related to a single area/page
namespace Group related convenience functions


getGroupData : function(groupid, callback, async, cache) {

Get the data for the specified group
param {String} groupid The ID of the group
param {Function} callback Callback function, passes (success, (data|xhr))
param {Boolean} async If this call should be ascynronous, defaults to true


getGroupInformation: function(options, callback) {

Gets information for specified group
param {Object} options Contains function parameters
param {Function} callback Callback function, passes ( {Boolean} success, {Object} data )


getGroupAuthorizableData : function(groupids, callback) {

Get the data for the specified group
param {Object} groupids The ID of the group or an array of group IDs
param {Function} callback Callback function, passes (success, (data|xhr))
param {Boolean} async If this call should be ascynronous, defaults to true


createGroup : function(id, title, description, tags, users, joinability, visibility, templatePath, subject, body, meData, callback) {

Create a group
param {String} id the id of the group that's being created
param {String} title the title of the group that's being created
param {String} description the description of the group that's being created
param {Array} tags The tags to tag the group with on creation
param {Array} users An array of users of the format: 'name': user name 'firstName': user's first name 'userid': user's userid 'role': the permission to give the user (manager, member, ta) 'roleString': The translated role string to give the user ('Member', 'Manager', 'Teaching Assistant') 'creator': true | false (if this user is the creator of the group)
param {String} joinability The joinability of the group (yes, no, withauth)
param {String} visibility The visibility of the group (members-only, logged-in-only, public)
param {String} templatePath The path in the /var/templates/worlds space for this template, without .json (/var/templates/worlds/group/basic-group)
param {String} subject The tokenized subject of the message (translated) to send to the users joined to this group
param {String} body The body of the aforementioned message in the same format
param {Object} meData The sakai.data.me object
param {Function} callback the callback function for when the group save is complete. It will pass two params, success {Boolean} and nameTaken {Boolean}


deleteGroup : function(groupID, meData, callback) {

Delete a group
param {String} id the id of the group that's being deleted
param {Function} callback the callback function for when the group delete is complete.


updateGroupInfo : function(id, title, description, kind, callback) {

Update group basic information
param {String} id The id of the group to update
param {String} title The new title of the group
param {String} description The new description of the group
param {String} kind The kind of group, defined in (TODO define this somewhere, currently only in groupbasicinfo.html)
param {Function} callback Callback function, passes (success)


updateGroupProfile : function(id, profile, tags, groupData, callback) {

Update group profile
param {String} id The id of the group to update
param {Object} profile The group's profile
param {Array} tags The group's tags
param {Object} groupData The group's authprofile data - need this for role extraction
param {Function} callback Callback function, passes (success, updated)


isValidPermissionsProperty : function(permissionsProperty, value) {

Checks whether the given value is valid as defined by the given permissionsProperty.
param {Object} permissionsProperty Permissions property object (i.e. sakai.config.Permissions.Groups.joinable) with valid values to check against
param {Object} value Value to investigate
return true if the value has a valid property value, false otherwise


setPermissions : function(groupid, joinable, visible, roles, callback) {

Public function used to set joinability and visibility permissions for a group with groupid.
param {String} groupid The id of the group that needs permissions set
param {String} joinable The joinable state for the group (from sakai.config.Permissions.Groups)
param {String} visible The visibile state for the group (from sakai.config.Permissions.Groups)
param {Array} roles The roles for this group, from the 'sakai:roles' property of the group
param {Function} callback Function to be called on complete - callback args: (success)
return None


isCurrentUserAManager : function(groupid, meData, groupinfo) {

Determines whether the current user is a manager of the given group.
param groupid {String} id of the group to check
param {Object} meData the data from sakai.api.User.data.me
return true if the current user is a manager, false otherwise


isCurrentUserAMember : function(groupid, meData) {

Determines whether the current user is a member of the given group. Managers are considered members of a group. If the current user is a manager of the group, this function will return true.
param groupid {String} id of the group to check
param {Object} meData the data from sakai.api.User.data.me
return true if the current user is a member or manager, false otherwise


isAllowedToLeave : function(groupids, meData, callback) {

Determines whether the current user is allowed to leave the group
param groupid {String} id of the group to check
param {Object} meData the data from sakai.api.User.data.me
param {Function} callback Function to be called on complete - callback


getManagerCount : function(groupdata, members) {

Get the number of managers in the group
param {Object} groupdata The data from the group's authprofile
param {Object} members The result of sakai.api.Groups.getMembers()


addJoinRequest : function(groupID, callback) {

Creates a join request for the current user for a given group
param {String} groupID ID of the group to the user wants to join
param {Function} callback Callback function executed at the end of the operation - callback args: -- {Boolean} success True if operation succeeded, false otherwise


removeJoinRequest : function(userID, groupID, callback) {

Removes a join request for the given user for the specified group
param {String} userID ID of the user that wants to join the group
param {String} groupID ID of the group to the user wants to join
param {Function} callback Callback function executed at the end of the operation - callback args: -- {Boolean} success True if operation succeeded, false otherwise


getJoinRequests : function(groupID, callback, async) {

Returns all join requests for the specified group
param {String} groupID ID of the group to fetch join requests for
param {Function} callback Callback function executed at the end of the
param {Boolean} async Optional argument to set whether this operation is asynchronous or not. Default is true. operation - callback args: -- {Boolean} success true if operation succeeded, false otherwise -- {Object} joinrequest data if successful


searchMembers: function(groupId, query, num, page, sort, sortOrder, callback, roleCache) {

Searches through managers and members of a group and returns the results
param {String} groupId Id of the group to search in
param {String} query Query put in by the user, if empty a search for all participants is executed
param {Number} num The number of items to search for (page size)
param {Number} page The current page (0-indexed)
param {String} sort The parameter to sort on (firstName or lastName)
param {String} sortOrder The direction of the sort (desc or asc)
param {Function} callback Function executed on success or error
param {Boolean} roleCache Flag to get group role data from cache if available


getMembers : function(groupids, callback, everyone, noCache) {

Returns all the users who are member of a certain group
param {String} groupids The ID of the group we would like to get the members of or an array of group IDs
param {Function} callback Callback function, passes (success, (data|xhr))
param {Boolean} everyone If we should return managers + members (useful for pseudoGroups)
param {Boolean} noCache Whether or not to refresh the cache


hasManagementRights : function(parentRoleObject, roleIdToCheck) {

Checks if one role managers the other, returns true if the role has management rights
param {Object} parentRoleObject The role we want to check if it has management rights on the other
param {String} roleIdToCheck The role to check if it can be managed by


getProfilePicture : function(profile) {

Retrieves the profile picture for the group
param {Object} profile the groups profile
return {String} the url for the profile picture


prepareGroupsForRender: function(results, meData) {

Function to process search results for groups
param {Object} results Search results to process
param {Object} meData User object for the user
returns {Object} results Processed results


changeUsersPermission : function(groupID, rolesToAdd, rolesToDelete, medata, managerShip, callback) {

Change the permission of some users on a group
param {String} groupID the ID of the group to add members to
param {Array} rolesToAdd Array of user/group IDs to add to the group
param {Array} rolesToDelete Array of user/group IDs to remove from the group
param {Object} meData the data from sakai.api.User.data.me
param {Boolean} managerShip if the user should be added as a manager of the group (almost never is the case)
param {Function} callback Callback function


addUsersToGroup : function(groupID, users, medata, managerShip, callback, onlyReturnRequests) {

Add users to the specified group
param {String} groupID the ID of the group to add members to
param {Array} users Array of user/group IDs to add to the group
param {Object} meData the data from sakai.api.User.data.me
param {Boolean} managerShip if the user should be added as a manager
param {Function} callback Callback function
param {Boolean} onlyReturnRequests only return the requests, don't make them


addContentToGroup : function(groupID, contentIDs, callback) {

Add content items to the specified group
param {String} groupID the ID of the group to add members to
param {Array} contentList Array of content IDs to add to the group
param {Function} callback Callback function


removeUsersFromGroup : function(groupID, users, medata, callback, onlyReturnRequests) {

Remove users from the specified group
param {String} groupID the ID of the group to remove members from
param {Array} users Array of user/group IDs to remove from the group
param {Object} meData the data from sakai.api.User.data.me
param {Function} callback Callback function
param {Boolean} onlyReturnRequests only return the requests, don't make them


removeContentFromGroup : function(groupID, contentIDs, callback) {

Add users to the specified group
param {String} groupID the ID of the group to add members to
param {Array} content Array of content IDs to remove from the group
param {Function} callback Callback function