Opensocial (v0.9)

From VZ Developer Wiki

This documentation is not completed yet and will be extended by more examples in future.

opensocial

Namespace for top-level people functions.

Methods

opensocial.getEnvironment

<static> opensocial.Environment opensocial.getEnvironment()

Returns

Type	Description
opensocial.Environment	The current environment

Description

opensocial.hasPermission

<static> Boolean opensocial.hasPermission(permission)

Parameters

Name	Type	Description
permission	opensocial.Permission	The permission

Returns

Type	Description
Boolean	True if the gadget has access for the permission; false if it doesn't

Description

opensocial.invalidateCache

<static> opensocial.invalidateCache()

Description

opensocial.newActivity

<static> opensocial.Activity opensocial.newActivity(params)

Parameters

Name	Type	Description
params	Map.<opensocial.Activity.Field|Object>	Parameters defining the activity

Returns

Type	Description
opensocial.Activity	The new activity object

Description

opensocial.newAlbum

<static> opensocial.MediaItem opensocial.newAlbum(opt_params)

Parameters

Name	Type	Description
opt_params	Map.<opensocial.Album.Field|Object>	Any other fields that should be set on the Album object; all of the defined Field s are supported

Returns

Type	Description
opensocial.MediaItem	The new album object

Description

opensocial.newDataRequest

<static> opensocial.DataRequest opensocial.newDataRequest()

Returns

Type	Description
opensocial.DataRequest	The request object

Description

Examples

This code snippet fetches some of the current viewer's detailed information: display name, thumbnail image link, and other fields such as "About Me" and "Status"

function response(data) {
  var viewer = data.get("viewer_profile").getData();
  var aboutme = viewer.getField(opensocial.Person.Field.ABOUT_ME);
  var status = viewer.getField(opensocial.Person.Field.STATUS);
  var img = viewer.getField(opensocial.Person.Field.THUMBNAIL_URL);
 
  output("AboutMe:" + aboutme);
  output("STATUS: " + status);
  output('<img src="' + img +'">');
  var name = viewer.getDisplayName();
  output(name);
};
 
function request() {
  var req = opensocial.newDataRequest();
 
  var params = {};
  params[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] = [
    opensocial.Person.Field.ABOUT_ME,
    opensocial.Person.Field.STATUS,
    opensocial.Person.Field.THUMBNAIL_URL
  ];
 
  req.add(req.newFetchPersonRequest("VIEWER", params), "viewer_profile");
  req.send(response);
};
request();

opensocial.newIdSpec

<static> opensocial.IdSpec opensocial.newIdSpec(parameters)

Parameters

Name	Type	Description
parameters	Map.<opensocial.IdSpec.Field|Object>	Parameters defining the id spec.

Returns

Type	Description
opensocial.IdSpec	The new IdSpec object

Description

opensocial.newMediaItem

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

Parameters

Name	Type	Description
mimeType	String	MIME type of the media
url	String	Where the media can be found
opt_params	Map.<opensocial.MediaItem.Field|Object>	Any other fields that should be set on the media item object; all of the defined Field s are supported

Returns

Type	Description
opensocial.MediaItem	The new media item object

Description

opensocial.newMessage

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

Parameters

Name	Type	Description
body	String	The main text of the message
opt_params	Map.<opensocial.Message.Field|Object>	Any other fields that should be set on the message object; all of the defined Field s are supported

Returns

Type	Description
opensocial.Message	The new message object

Description

Examples

This example shows how to send an notification using OpenSocial.

function sendEmail(title, body) {
  var params = [];
  params[opensocial.Message.Field.TITLE] = title;
  params[opensocial.Message.Field.TYPE] =
      opensocial.Message.Type.NOTIFICATION;
 
   // those are optional parameter you can optionally use in order to add e.g. tracking parameters
  params[opensocial.Message.Field.OPT_PARAMS] = {param1: 'abc', param2: 'def'};
 
  var message = opensocial.newMessage(body, params);
  var recipient = "VIEWER";
  opensocial.requestSendMessage(recipient, message, callback);
};
 
function callback(data) {
  if (data.hadError()) {
    alert("There was a problem:" + data.getErrorCode());
  } else {
    output("Ok");
  }
};
 
sendEmail("This is a test email", "How are you doing?");

opensocial.newNavigationParameters

<static> opensocial.NavigationParameters opensocial.newNavigationParameters(parameters)

Parameters

Name	Type	Description
parameters	Map.<opensocial.NavigationParameters.Field|Object>	Parameters defining the navigation

Returns

Type	Description
opensocial.NavigationParameters	The new NavigationParameters object

Description

opensocial.requestCreateActivity

<static> opensocial.requestCreateActivity(activity, priority, opt_callback)

Parameters

Name	Type	Description
activity	opensocial.Activity	The activity to create
priority	opensocial.CreateActivityPriority	The priority for this request
opt_callback	Function	The function to call once the request has been processed. The callback function will not be called until after the existing callstack has completed execution.

Description

opensocial.requestPermission

<static> opensocial.requestPermission(permissions, reason, opt_callback)

Parameters

Name	Type	Description
permissions	Array.<opensocial.Permission>	The permissions to request from the viewer
reason	String	Displayed to the user as the reason why these permissions are needed
opt_callback	Function	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. The callback function will not be called until after the existing callstack has completed execution.

Description

opensocial.requestSendMessage

<static> opensocial.requestSendMessage(An, message, opt_callback, opt_params)

Parameters

Name	Type	Description
An	opensocial.IdSpec	IdSpec used to specify which people/groups to send the message to.
message	opensocial.Message	The message to send to the specified users
opt_callback	Function	The function to call once the request has been processed; The callback function has a parameter with a complete list of final recipients
opt_params	opensocial.NavigationParameters	The optional parameters indicating where to send a user when a request is made, or when a request is accepted; options are of type NavigationParameters.DestinationType

Description

Quota

Example

function sendEmail(title, body) {
  var params = [];
  params[opensocial.Message.Field.TITLE] = title;
  params[opensocial.Message.Field.TYPE] =
      opensocial.Message.Type.NOTIFICATION;
 
   // those are optional parameter you can optionally use in order to add e.g. tracking parameters
  params[opensocial.Message.Field.OPT_PARAMS] = {param1: 'abc', param2: 'def'};
 
  var message = opensocial.newMessage(body, params);
  var recipient = "VIEWER";
  opensocial.requestSendMessage(recipient, message, callback);
};
 
function callback(data) {
  if (data.hadError()) {
    alert("There was a problem:" + data.getErrorCode());
  } else {
    output("Ok");
  }
};
 
sendEmail("This is a test email", "How are you doing?");

opensocial.requestUpdateViewer

<static> opensocial.requestUpdateViewer(person, opt_callback)

Parameters

Name	Type	Description
person	opensocial.Person	A person object to which the current users profile should be updated, currently we only support to request a change to the users profile picture (field thumbnailUrl)
opt_callback	Function	The function to call once the request has been processed; The callback function has a parameter with a boolean value to indicate if the user accepted the change or not

Description

Format of thumbnailUrl

the thumbnailUrl needs to be a valid Data URL (see http://de.wikipedia.org/wiki/Data-URL for details)

var person = opensocial.newPerson({thumbnailUrl : 'BASE64_ENCODED_PHOTO'});
opensocial.requestUpdateViewer(person, function(response) {
 
});

opensocial.requestShareApp

<static> opensocial.requestShareApp(recipients, reason, opt_callback, opt_params)

Parameters

Name	Type	Description
recipients	opensocial.IdSpec	An IdSpec used to specify which people/groups to send the ShareApp request to.
reason	opensocial.Message	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.
opt_callback	Function	The function to call once the request has been processed
opt_params	opensocial.NavigationParameters	The optional parameters indicating where to send a user when a request is made, or when a request is accepted; options are of type NavigationParameters.DestinationType

Description

opensocial.requestUploadMediaItem

<static> opensocial.requestUploadMediaItem(albumId, opt_callback)

Parameters

Name	Type	Description
albumId	string	Indicates which album/collection to insert the items into. If not present or set to null|undefined, the items go into the default location for the container. Partial upload is possible, such that if the container allows for multiple items, some items may fail to be added.
opt_callback	Function	Method is called when the upload completes. The callback function is 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. getErrorMessage will contain a comma separated list of files that failed to upload. The data on the response item will be set to an array of media item objects for successful items.

Description