opensocial (v0.7)

 SUMMARY     DETAIL

Static Class opensocial

Namespace for top-level people functions.

Method Summary

<static>  opensocial.Environment getEnvironment()

Gets the current environment for this gadget.

<static>  Boolean hasPermission(permission)

Returns true if the current gadget has access to the specified permission.

<static>  opensocial.Activity newActivity(params)

Creates an activity object, which represents an activity on the server.

<static>  opensocial.Activity.MediaItem newActivityMediaItem(mimeType, url, opt_params)

Creates a media item associated with an activity.

<static>  opensocial.DataRequest newDataRequest()

Creates a data request object to use for sending and fetching data from the server.

<static>  opensocial.Message newMessage(body, opt_params)

Creates a media item associated with an activity.

<static> requestCreateActivity(activity, priority, opt_callback)

Takes an activity and tries to create it, without waiting for the operation to complete.

<static> requestPermission(permissions, reason, opt_callback)

Requests the user to grant access to the specified permissions.

<static> requestSendMessage(recipients, message, opt_callback)

Requests the container to send a specific message to the specified users.

<static> requestShareApp(recipients, reason, opt_callback)

Requests the container to share this gadget with the specified users.

 

Method Detail

getEnvironment

<static> opensocial.Environment getEnvironment()

Gets the current environment for this gadget. You can use the environment to make queries such as what profile fields and surfaces are supported by this container, what parameters were passed to the current gadget, and so on.

Returns:
opensocial.Environment The current environment

hasPermission

<static> Boolean hasPermission(permission)

Returns true if the current gadget has access to the specified permission. If the gadget calls opensocial.requestPermission and permissions are granted then this function must return true on all subsequent calls.

Parameters:
opensocial.Permission permission - The permission

Returns:
Boolean True if the gadget has access for the permission; false if it doesn't

newActivity

<static> opensocial.Activity newActivity(params)

Creates an activity object, which represents an activity on the server.

See also: requestCreateActivity(),

It is only required to set one of TITLE_ID or TITLE. In addition, if you are using any variables in your title or title template, you must set TEMPLATE_PARAMS.

Other possible fields to set are: URL, MEDIA_ITEMS, BODY_ID, BODY, EXTERNAL_ID, PRIORITY, STREAM_TITLE, STREAM_URL, STREAM_SOURCE_URL, and STREAM_FAVICON_URL.

Containers are only required to use TITLE_ID or TITLE, and may choose to ignore additional parameters.

See Fields are supported for more details.

Parameters:
Map.<opensocial.Activity.Field, Object> params - Parameters defining the activity.

Returns:
opensocial.Activity The new activity object

newActivityMediaItem

<static> opensocial.Activity.MediaItem newActivityMediaItem(mimeType, url, opt_params)

Creates a media item associated with an activity. Represents images, movies, and audio. Used when creating activities on the server.

Parameters:
String mimeType - MIME type of the media
String url - Where the media can be found
Map.<opensocial.Activity.MediaItem.Field, Object> opt_params - Any other fields that should be set on the media item object; all of the defined Fields are supported

Returns:
opensocial.Activity.MediaItem The new media item object

newDataRequest

<static> opensocial.DataRequest newDataRequest()

Creates a data request object to use for sending and fetching data from the server.

Returns:
opensocial.DataRequest The request object

newMessage

<static> opensocial.Message newMessage(body, opt_params)

Creates a media item associated with an activity. Represents images, movies, and audio. Used when creating activities on the server.

Parameters:
String body - The main text of the message.
Map.<opensocial.Message.Field, Object> opt_params - Any other fields that should be set on the message object; all of the defined Fields are supported

Returns:
opensocial.Message The new message object

requestCreateActivity

<static> requestCreateActivity(activity, priority, opt_callback)

Takes an activity and tries to create it, without waiting for the operation to complete. Optionally calls a function when the operation completes.

See also: newActivity()

Note: If this is the first activity that has been created for the user and the request is marked as HIGH priority then this call may open a user flow and navigate away from your gadget. If the container does not support this method the callback will be called with a opensocial.ResponseItem. The response item will have its error code set to NOT_IMPLEMENTED.

Parameters:
opensocial.Activity activity - The activity to create
opensocial.CreateActivityPriority priority - The priority for this request
Function opt_callback - The function to call once the request has been processed. This callback will either be called or the gadget will be reloaded from scratch. This function will be passed one parameter, an opensocial.ResponseItem. The error code will be set to reflect whether there were any problems with the request. If there was no error, the activity was created. If there was an error, you can use the response item's getErrorCode method to determine how to proceed. The data on the response item will not be set.

requestPermission

<static> requestPermission(permissions, reason, opt_callback)

Requests the user to grant access to the specified permissions. If the container does not support this method the callback will be called with a opensocial.ResponseItem. The response item will have its error code set to NOT_IMPLEMENTED.

Parameters:
Array.<opensocial.Permission> permissions - The permissions to request from the viewer
String reason - Displayed to the user as the reason why these permissions are needed
Function opt_callback - The function to call once the request has been processed; either this callback will be called or the gadget will be reloaded from scratch. This function will be passed one parameter, an opensocial.ResponseItem. The error code will be set to reflect whether there were any problems with the request. If there was no error, all permissions were granted. If there was an error, you can use opensocial.hasPermission to check which permissions are still denied. The data on the response item will be set. It will be an array of the opensocial.Permissions that were granted.

requestSendMessage

<static> requestSendMessage(recipients, message, opt_callback)

Requests the container to send a specific message to the specified users. If the container does not support this method the callback will be called with a opensocial.ResponseItem. The response item will have its error code set to NOT_IMPLEMENTED.

Parameters:
Array.<String>, String recipients - An ID, array of IDs, or a group reference; the supported keys are VIEWER, OWNER, VIEWER_FRIENDS, OWNER_FRIENDS, or a single ID within one of those groups
opensocial.Message message - The message to send to the specified users.
Function opt_callback - The function to call once the request has been processed; either this callback will be called or the gadget will be reloaded from scratch. This function will be passed one parameter, an opensocial.ResponseItem. The error code will be set to reflect whether there were any problems with the request. If there was no error, the message was sent. If there was an error, you can use the response item's getErrorCode method to determine how to proceed. The data on the response item will not be set.

requestShareApp

<static> requestShareApp(recipients, reason, opt_callback)

Requests the container to share this gadget with the specified users. If the container does not support this method the callback will be called with a opensocial.ResponseItem. The response item will have its error code set to NOT_IMPLEMENTED.

Parameters:
Array.<String>, String recipients - An ID, array of IDs, or a group reference; the supported keys are VIEWER, OWNER, VIEWER_FRIENDS, OWNER_FRIENDS, or a single ID within one of those groups
opensocial.Message reason - The reason the user wants the gadget to share itself. This reason can be used by the container when prompting the user for permission to share the app. It may also be ignored.
Function opt_callback - The function to call once the request has been processed; either this callback will be called or the gadget will be reloaded from scratch. This function will be passed one parameter, an opensocial.ResponseItem. The error code will be set to reflect whether there were any problems with the request. If there was no error, the sharing request was sent. If there was an error, you can use the response item's getErrorCode method to determine how to proceed. The data on the response item will not be set.

---