define(
        createUser
        updateUserProfile
        removeUser
        getUser
        getMultipleUsers
        login
        logout
        getProfileBasicElementValue
        setProfileBasicElementValue
        loadMeData
        getProfilePicture
        getFirstName
        getDisplayName
        getShortDescription
        getConnectionState
        preparePeopleForRender
        loadPrivacySettings
        savePrivacySettings
define(

class User
description Advanced user related functionality, especially common actions that originate from a logged in user. This should only hold functions which are used across multiple pages, and does not constitute functionality related to a single area/page
namespace Advanced user related functionality, especially common actions that originate from a logged in user.


createUser : function(username, firstName, lastName, email, password, passwordConfirm, extraOptions, callback) {

param {Object} extraOptions can include recaptcha: {challenge, response}, locale : 'user_LOCALE', template: 'templateName'


updateUserProfile: function( userid, section, data, tags, sectionData, multiple, callback ) {

Update a user's profile
param {String} userid The userid of the user to update their profile
param {String} section The profile section (ie basic, publications)
param {Object} data The data to save on this section
param {Array} tags The tags and categories on this user
param {Object} sectionData The current data for this section, before any updates. Used for saving tags on the user.
param {Boolean} multiple If this is a multi-assign section, like publications
param {Function} callback The callback function for after the data has been saved


removeUser : function(userid, callback) {

Remove the user credentials in the Sakai OAE system. Note that this doesn't actually remove the user, only its permissions.
example sakai.api.User.createUser({ 'firstName': 'User', 'lastName': '0', 'email': 'user.0
sakatest.edu', 'pwd': 'test', 'pwdConfirm': 'test', ':name': 'user0' });
param {String} userid The id of the user you want to remove from the system
param {Function} [callback] A callback function which will be called after the request to the server.


getUser: function(userid, callback) {

Gets the profile data for a user
param {String} userid The userId to fetch the profile for
param {Function} callback Callback function to call when the request is complete


getMultipleUsers: function(userArray, callback) {

Gets the profile data for multiple users
param {Array} userArray Array of userIds to fetch the profiles for
param {Function} callback Callback function to call when the request is complete


login : function(credentials, callback) {

Log-in to Sakai OAE
example sakai.api.User.login({ 'username': 'user1', 'password': 'test' });
param {Object} credentials JSON object container the log-in information. Contains the username and password.
param {Function} [callback] Callback function that is called after sending the log-in request to the server.


logout : function(callback) {

Log-out from Sakai OAE
example sakai.api.user.logout();
param {Function} [callback] Callback function that is called after sending the log-in request to the server.


getProfileBasicElementValue : function(profile, eltName) {

Safely retrieves an element value from the user's profile
param {Object} profile the user's profile (data.me.profile for the current user)
param {String} eltName the element name to retrieve the value for
return {String} the value of the element name provided


setProfileBasicElementValue : function(profile, eltName, eltValue) {

Sets a value to the user's basic profile information
param {Object} profile the user's profile (data.me.profile for the current user)
param {String} eltName the element name to retrieve the value for
param {String} eltValue the value to place in the element


loadMeData : function(callback) {

Retrieves all available information about a logged in user and stores it under data.me object. When ready it will call a specified callback function
param {Function} [callback] A function which will be called when the information is retrieved from the server. The first argument of the callback is a boolean whether it was successful or not, the second argument will contain the retrieved data or the xhr object
return {Void}


getProfilePicture : function(profile) {

Retrieves the profile picture for the user
param {Object} profile the users profile (data.me.profile for the current user)
return {String} the url for the profile picture


getFirstName : function(profile, doSafeOutput) {

Retrieves the first name display to use for the user from config and parses it from the profile elements
param {Object} profile the user's profile (data.me.profile for the current user)
param {Boolean} doSafeOutput (Optional) perform html safe output. Defaults to true
return {String} the first name to show for a user


getDisplayName : function(profile, doSafeOutput) {

Retrieves the display name to use for the user from config and parses it from the profile elements
param {Object} profile the user's profile (data.me.profile for the current user)
param {Boolean} doSafeOutput (Optional) perform html safe output. Defaults to true
return {String} the name to show for a user


getShortDescription : function(profile) {

Get a user's short description from their profile This is based off of the configuration in config.js Example: '${role} in ${department}' could translate to 'Undergraduate Student in Computer Science' based on the configuration in config.js and the user's profile information If the user doesn't have the profile information requested by config.js, the function will remove the token from the string and any modifiers before the token after the previous token In the above example, if the user only had a department, the resulting string would be 'Computer Science'
param {Object} profile The user's profile to get a description from
return {String} the user's short description


getConnectionState : function(userid, callback) {

Get a contacts connection state, or return false if user is not a contact
param {String} the user's ID
param {Function} [callback] A function which will be called when the information is retrieved from the server.


preparePeopleForRender: function(results, meData) {

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


loadPrivacySettings: function(callback) {

Load the privacy settings for the current user's account
param {Function} callback Function to call once the privacy setting has been retrieved. Returns 'public' for public user accounts or 'everyone' for user accounts that are only visible to logged in users


savePrivacySettings: function(option, callback) {

Store new account privacy settings for the current user. This can either make the account public or only visible to logged in users
param {String} option 'public' for a public account or 'everyone' for an account that's only visible to logged in users
param {Function} callback Function to call once the privacy setting has been stored. Returns true when the change was successful and false when the change failed