pureweb.client. CollaborationManager

The CollaborationManager class provides methods to implement the collaboration functionality.

Collaboration allows several users to interact simultaneously with the same service session from their own instance of the client application. The collaboration functionality also includes acetate tools, which allow you to display an overlay over views for markup purposes (see the AcetateToolDelegate interface).

Method Summary

addMessageListener
Adds a collaboration message listener.
getActiveSessions
Returns a list of the active sessions; this is expressed as an array of IDs.
getDefaultColor
Returns the default color.
getFramework
Returns the Framework instance used by this CollaborationManager.
getInstanceIdFromElement
Returns the ID of the acetate tool instance for a specified markup element, or null if the element does not exist.
getMarkupVisible
Returns a Boolean value that indicates whether acetate markup is visible for the specified session.
getOwnerSession
Returns the unique identifier of the owner session.
getSessionCollaborationInfo
Returns the session collaboration info for the specified session, or null if it does not exist.
getSessionDefaultColor
Returns the default color for the specified collaboration session, in the format #RRGGBB.
getSessionId
Returns the ID of the collaboration session.
getSessionUserInfo
Returns the user information for the specified session ID.
getUserInfo
Returns the user information for the collaboration session.
getViewCollaborationInfo
Returns the collaboration information for the specified view, or null if the view does not exist.
getViewUpdateBroadcastPath
Returns the view update broadcast path.
isInitialized
Returns a Boolean value indicating whether this instance is initialized.
removeAcetateMarkupByInstance
Removes a specified instance of acetate markup.
removeAcetateMarkupBySession
Removes all instances of acetate markup for a specified view in a given session.
removeAcetateMarkupByTools
Removes markup from the specified acetate tool.
removeAcetateMarkupByType
Removes all instances of acetate markup of the specified type in a given view.
removeAllAcetateMarkupBySession
Removes all instances of acetate markup for the given session, across all views.
removeMessageListener
Removes a collaboration message listener.
sendBroadcastMessage
Sends a broadcast collaboration message.
sendMessage
Sends a collaboration message.
setDefaultColor
Sets the default color.
setMarkupVisible
Sets a Boolean value that indicates whether acetate markup is visible for the specified session.
setSessionUserInfo
Set the user information for the specified session ID.
setUserInfo
Sets the user information for the collaboration session.
setViewCollaborationInfo
Sets the collaboration information for the specified view.
startAcetateMarkup
Starts an acetate tool, and returns the instance ID of the started tool.
updateAcetateMarkup
Updates an instance of an acetate tool.
updateUserInfo
Updates the user information in the session element of application state.

Constructor

new CollaborationManager(framework)

Initalizes a new instance of CollaborationManager.
Parameters:
Name Type Description
framework pureweb.client.Framework The Framework object.

Extends

  • pureweb.events.EventTarget

Members

<static> EventType → string

Types of events for which client applications can listen.
Properties:
Name Type Default Description
IS_INITIALIZED_CHANGED string The event that gets dispatched when the initialized status of the CollaborationManager changes.
SESSIONS_CHANGED string The event that gets dispatched when there is a change to the session element in application state. This would happen, for example, whenever collaboration participants join or leave the session.
OWNER_SESSION_CHANGED string The event that gets dispatched when the owner session changes. This would happen, for example, whenever a session host joins or leaves the session.
DEFAULT_COLOR_CHANGED string The event that gets dispatched when the default color (for acetate tools) changes.
USER_INFO_CHANGED string The event that gets dispatched when the user information changes.

Method Detail

addMessageListener(name, listener, context)

Adds a collaboration message listener.
Parameters:
Name Type Argument Description
name string The message name.
listener function The message listener callback.
context Object <optional>
The context in which the handler will be executed (i.e. 'this').

getActiveSessions() → {Array}

Returns a list of the active sessions; this is expressed as an array of IDs.

getDefaultColor() → {pureweb.PureWebColor}

Returns the default color. This color is used when an acetate tool is active: each participant's cursor or drawing on the view overlay will appear in a different color.

getFramework() → {pureweb.client.Framework}

Returns the Framework instance used by this CollaborationManager.

getInstanceIdFromElement(element) → {string}

Returns the ID of the acetate tool instance for a specified markup element, or null if the element does not exist.
Parameters:
Name Type Description
element Element The markup element.

getMarkupVisible(sessionId) → {boolean}

Returns a Boolean value that indicates whether acetate markup is visible for the specified session. Will return true if it is, or false otherwise.
Parameters:
Name Type Description
sessionId string The ID of the session for which you are checking acetate visibility.

getOwnerSession() → {string}

Returns the unique identifier of the owner session.
Throws:
If the collaboration manager has not been initialized:
pureweb.InvalidOperationException

getSessionCollaborationInfo(sessionId) → {Element}

Returns the session collaboration info for the specified session, or null if it does not exist. The collaboration information is the content of the session element in application state, and includes details such as username and assigned color.
Parameters:
Name Type Description
sessionId string The session id.

getSessionDefaultColor(sessionId) → {pureweb.PureWebColor}

Returns the default color for the specified collaboration session, in the format #RRGGBB. This color is used when an acetate tool is active: each participant's cursor or drawing on the view overlay will appear in a different color.
Parameters:
Name Type Description
sessionId string The ID of the session.

getSessionId() → {string}

Returns the ID of the collaboration session. Will be empty until the framework client is connected.

getSessionUserInfo(sessionId) → {Element}

Returns the user information for the specified session ID. User information is stored in a UserInfo element in application state, and contains details specific to a given collaboration participant.
Parameters:
Name Type Description
sessionId string The unique identifier of the session.

getUserInfo() → {Element}

Returns the user information for the collaboration session. This is the UserInfo element in application state that stores any details specific to a given collaboration participant.

getViewCollaborationInfo(viewName) → {Element}

Returns the collaboration information for the specified view, or null if the view does not exist.
Parameters:
Name Type Argument Description
viewName string <nullable>
The name of the view.

getViewUpdateBroadcastPath(viewName, isNameEscaped) → {string}

Returns the view update broadcast path.
Parameters:
Name Type Argument Description
viewName string <nullable>
The name of the view.
isNameEscaped boolean Set to true if the view name is escaped, or set to false otherwise.

isInitialized() → {boolean}

Returns a Boolean value indicating whether this instance is initialized. Will return true if it is, or false otherwise.

removeAcetateMarkupByInstance(viewName, markupType, instanceId, opt_tools)

Removes a specified instance of acetate markup.
Parameters:
Name Type Argument Description
viewName string The name of the view from which to remove the markup.
markupType string The type of markup to remove.
instanceId string The unique identifier of the instance.
opt_tools pureweb.client.collaboration.AcetateToolset <optional>
The toolset from which to remove markup.

removeAcetateMarkupBySession(viewName, opt_sessionId, opt_tools)

Removes all instances of acetate markup for a specified view in a given session.
Parameters:
Name Type Argument Description
viewName string <nullable>
The name of the view from which to remove the markup.
opt_sessionId string <optional>
The unique identifier of the session from which to remove the markup. If omitted, the ID of the local session is used.
opt_tools pureweb.client.collaboration.AcetateToolset <optional>
The toolset from which to remove markup.

removeAcetateMarkupByTools(tools)

Removes markup from the specified acetate tool.
Parameters:
Name Type Description
tools pureweb.client.collaboration.AcetateToolset The acetate tool from which to remove markup.

removeAcetateMarkupByType(viewName, markupType, opt_tools)

Removes all instances of acetate markup of the specified type in a given view.
Parameters:
Name Type Argument Description
viewName string The name of the view from which to remove the markup.
markupType string The type of markup to remove.
opt_tools pureweb.client.collaboration.AcetateToolset <optional>
The toolset from which to remove markup.

removeAllAcetateMarkupBySession(sessionId)

Removes all instances of acetate markup for the given session, across all views.
Parameters:
Name Type Description
sessionId string The unique identifier of the session from which to remove the markup.

removeMessageListener(name)

Removes a collaboration message listener.
Parameters:
Name Type Description
name string The message name.

sendBroadcastMessage(name, payload)

Sends a broadcast collaboration message.
Parameters:
Name Type Description
name string The message name.
payload Object The payload of the message.

sendMessage(name, targetSessionId, payload)

Sends a collaboration message.
Parameters:
Name Type Argument Description
name string The message name.
targetSessionId string <nullable>
The session ID of the message target.
payload Object The payload of the message.

setDefaultColor(defaultColor)

Sets the default color. This color is used when an acetate tool is active: each participant's cursor or drawing on the view overlay will appear in a different color.
Parameters:
Name Type Description
defaultColor pureweb.PureWebColor The color to set as default.

setMarkupVisible(sessionId, markupVisible)

Sets a Boolean value that indicates whether acetate markup is visible for the specified session.
Parameters:
Name Type Description
sessionId string The ID of the session for which you are setting acetate visibility.
markupVisible boolean Set to true to make the markup is visible, or set to false otherwise.

setSessionUserInfo(sessionId, userInfo)

Set the user information for the specified session ID. User information is stored in a UserInfo element in application state, and contains details specific to a given collaboration participant.
Parameters:
Name Type Description
sessionId string The unique identifier of the session.
userInfo Element The user information to set.

setUserInfo(value)

Sets the user information for the collaboration session. This is the UserInfo element in application state that stores any details specific to a given collaboration participant.
Parameters:
Name Type Description
value Element The UserInfo element to set.

setViewCollaborationInfo(viewName, info)

Sets the collaboration information for the specified view.
Parameters:
Name Type Description
viewName string The name of the view.
info Element The collaboration information to set.

startAcetateMarkup(viewName, markupType, markup, newInstance) → {string}

Starts an acetate tool, and returns the instance ID of the started tool. The specified draw data is placed into the collaboration acetate data for the specified view for the current session. The return value is used to identify the instance to update with markup in the future.
Parameters:
Name Type Description
viewName string Name of the view.
markupType string The markup type.
markup Element The markup.
newInstance boolean Set to true for tools that support creating multiple instances of markup. This will create a new instance, otherwise the same instance would always be used.

updateAcetateMarkup(viewName, markupType, instanceId, markup)

Updates an instance of an acetate tool.
Parameters:
Name Type Description
viewName string The name of the view where the markup will be updated.
markupType string The type of markup to update.
instanceId string The unique identifier of the instance to which the update applies.
markup Element The actual markup to update.

updateUserInfo(key, val)

Updates the user information in the session element of application state. User information is expressed as a key/value pair.
Parameters:
Name Type Description
key string The key to update.
val string The new value to attach to the key.