Opensocial (v0.8)

From VZ Developer Wiki
Revision as of 13:51, 30 June 2010 by Seba (talk | contribs) (Examples)
Jump to: navigation, search

General Guidelines | XML Specification | Features | Views | JavaScript API | REST API | Tutorials | OAuth


opensocial

Namespace for top level functions.

Methods

opensocial.requestSendMessage

opensocial.requestSendMessage(recipients, message, opt_callback, opt_params)
Parameters
Array.<String> | String recipients - An ID or array of IDs; the supported keys are VIEWER, OWNER, or a single ID within one of the groups VIEWER_FRIENDS or OWNER_FRIENDS
opensocial.Message message - The message to send to the specified users
Function opt_callback - The function to call once the request has been processed, returns a boolean as first parameter to indicate if the request was successfull.

opensocial.NavigationParameters opt_params - 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

Returns
None
but for opensocial.Message.Type.PUBLIC_MESSAGE an Array - complete list of the recipients

Examples

This example shows how to send a notification using OpenSocial.

function sendNotification(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");
  }
};

sendNotification("This is a test email", "How are you doing?");

opensocial.requestShareApp

opensocial.requestShareApp(recipients, reason, opt_callback, opt_params) uses the implementation of Vz.invite
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. Not supported at VZ-Netzwerke.
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. Only the message body is used at VZ-Netzwerke.
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. Not supported at VZ-Netzwerke.
opensocial.NavigationParameters opt_params - The optional parameters indicating where to send a user when a request is made, or when a request is accepted; options are of type opensocial.NavigationParameters . Not supported at VZ-Netzwerke.
Returns
None

opensocial.requestCreateActivity

opensocial.requestCreateActivity(activity, priority, opt_callback)
Parameters
opensocial.Activity activity - The activity to create
opensocial.CreateActivityPriority priority - The priority for this request - priority is currently not supported
Function opt_callback - The function to call once the request has been processed.
Returns
None

opensocial.hasPermission

opensocial.hasPermission(permission)
Parameters
opensocial.Permission permission - The permission
Returns
Boolean - True if the gadget has access for the permission; false if it doesn't

Examples

This code snippet checks to see if the current gadget has permission to the viewer object for the current container

if(opensocial.hasPermission(opensocial.Permission.VIEWER )) {
    output("You have permission to viewer object");
} else {
    output("You don't have permissions to viewer object");
}

opensocial.requestPermission

opensocial.requestPermission(permissions, reason, opt_callback)
Parameters
Array.<opensocial.Permission> permissions - The permission 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.
Returns
None

opensocial.getEnvironment

opensocial.getEnvironment()
None
Returns
opensocial.Environment - The current environment

opensocial.newDataRequest

opensocial.newDataRequest()
None
Returns
opensocial.DataRequest - The DataRequest object

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.newActivity

opensocial.newActivity(params)
Parameters
Map.<opensocial.Activity.Field, Object> params - Parameters defining the activity
Returns
opensocial.Activity - The new activity object

opensocial.newMediaItem

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

opensocial.newMessage

opensocial.newMessage(body, opt_params)
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 message fields are supported
Returns
opensocial.Message - The new message object

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;

  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.newPerson

opensocial.newPerson(opt_params)
Parameters
Map.<opensocial.Person.Field, Object> opt_params - Any other fields that should be set on the message object; all of the defined person fields are supported
Returns
opensocial.Person - The new person object

opensocial.newIdSpec

opensocial.newIdSpec(params)
Parameters
Map.<opensocial.IdSpec.Field, Object> parameters - Parameters defining the id spec.
Returns
opensocial.IdSpec - The new IdSpec object

opensocial.newNavigationParameters

opensocial.newNavigationParameters(params)
Parameters
Map.<opensocial.NavigationParameters.Field, Object> parameters - Parameters defining the navigation
Returns
opensocial.NavigationParameters - The new NavigationParameters object



We are implementing the following APIs from the OpenSocial 0.8 spec

gadgets.flash

gadgets.io

gadgets.json

gadgets.MiniMessage

gadgets.Prefs

gadgets.pubsub

gadgets.rpc

gadgets.skins

gadgets.Tab


gadgets.TabSet

gadgets.util

gadgets.views

gadgets.window

opensocial

opensocial.Activity

opensocial.Address

opensocial.BodyType

opensocial.Collection

opensocial.CreateActivityPriority

opensocial.DataRequest

opensocial.DataResponse

opensocial.Email

opensocial.Enum

opensocial.Environment

opensocial.EscapeType

opensocial.IdSpec

opensocial.MediaItem

opensocial.Message

opensocial.Name

opensocial.NavigationParameters

opensocial.Organization

opensocial.Permission

opensocial.Person

opensocial.Phone

opensocial.ResponseItem

opensocial.Url