Opensocial.DataRequest (v0.8)

From OpenSocial

This page has example code which needs to be improved.
Please help improve this page by fixing existing code or writing additional examples. (November 2008)

1 Methods
2 Fields
3 Examples

opensocial.DataRequest

Used to request social information from the container. This includes data for friends, profiles, app data, and activities. All apps that require access to people information should send a DataRequest.

Methods

add

add(request, opt_key)

Adds an item to fetch (get) or update (set) data from the server. A single DataRequest object can have multiple items. As a rule, each item is executed in the order it was added, starting with the item that was added first. However, items that can't collide might be executed in parallel.

Parameters: Object request Specifies which data to fetch or update; String opt_key A key to map the generated response data to
Returns: None

newFetchActivitiesRequest

Object newFetchActivitiesRequest(idSpec, opt_params): Creates an item to request an activity stream from the server.

When processed, returns a Collection<Activity>.

Parameters: opensocial.IdSpec idSpec - An IdSpec used to specify which people to fetch.; Map.<opensocial.DataRequest.ActivityRequestFields, Object> opt_params - Additional parameters to pass to the request; not currently used
Returns: Object - A request object

newFetchPeopleRequest

Object newFetchPeopleRequest(idSpec, opt_params)

Creates an item to request friends from the server. When processed, returns a Collection <Person> object.

Parameters: opensocial.IdSpec idSpec - An IdSpec used to specify which people to fetch.; Map.<opensocial.DataRequest.PeopleRequestFields, Object> opt_params - Additional params to pass to the request
Returns: Object - A request object

newFetchPersonAppDataRequest

Object newFetchPersonAppDataRequest(idSpec, keys, opt_params)

Creates an item to request app data for the given people. When processed, returns a Map< PersonId, Map<String, Object>> object. All of the data values returned will be valid JSON.

Parameters: opensocial.IdSpec idSpec - An IdSpec used to specify which people to fetch.; Array.<String>, String keys - The keys you want data for; this can be an array of key names, a single key name, or "*" to mean "all keys"; Map.<opensocial.DataRequest.DataRequestFields, Object> opt_params - Additional params to pass to the request
Returns: Object - A request object

newFetchPersonRequest

Object newFetchPersonRequest(id, opt_params)

Creates an item to request a profile for the specified person ID. When processed, returns a Person object.

Parameters: String id - The ID of the person to fetch; can be the standard person ID of VIEWER or OWNER; Map.<opensocial.DataRequest.PeopleRequestFields, Object> opt_params - Additional parameters to pass to the request; this request supports PROFILE_DETAILS
Returns: Object - A request object

Examples

function request() {
  var params = {};
  params[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] =
        [opensocial.Person.Field.PROFILE_URL];
 
  var req = opensocial.newDataRequest();
  req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.VIEWER, params), "req");
  req.send(response);
};

newRemovePersonAppDataRequest

Object newRemovePersonAppDataRequest(id, keys)

Deletes the given keys from the datastore for the given person. When processed, does not return any data.

Parameters: String id - The ID of the person to update; only the special VIEWER ID is currently allowed.; Array.<String>, String keys - The keys you want to delete from the datastore; this can be an array of key names, a single key name, or "*" to mean "all keys"
Returns: Object - A request object

newUpdatePersonAppDataRequest

Object newUpdatePersonAppDataRequest(id, key, value)

Creates an item to request an update of an app field for the given person. When processed, does not return any data.

Parameters: String id - The ID of the person to update; only the special VIEWER ID is currently allowed.; String key - The name of the key. This may only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-).; Object value - The value, must be valid JSON
Returns: Object - A request object

Examples

mobyDick = { 'title' : 'Moby Dick',
             'author': 'Herman Melville' };
var json = gadgets.json.stringify(mobyDick);
 
var req = opensocial.newDataRequest();
req.add(req.newUpdatePersonAppDataRequest("VIEWER", 'favoriteBook', json));
req.send();

send

send(opt_callback)

Sends a data request to the server in order to get a data response. Although the server may optimize these requests, they will always be executed as though they were serial.

Parameters: Function opt_callback - The function to call with the data response generated by the server
Returns: None

Fields

opensocial.DataRequest.DataRequestFields

DataRequestFields are used to format the results of a DataRequest.

opensocial.DataRequest.DataRequestFields.ESCAPE_TYPE

How to escape person data returned from the server; defaults to HTML_ESCAPE. Possible values are defined by opensocial.EscapeType. This field may be used interchangeably with the string 'escapeType'.

Examples

opensocial.DataRequest.FilterType

FilterTypes are used to limit the people returned in a newFetchPeopleRequest.

opensocial.DataRequest.FilterType.ALL

Retrieves all friends. This field may be used interchangeably with the string 'all'.

opensocial.DataRequest.FilterType.HAS_APP

Retrieves all friends that use this application. Note: Containers may define "use" in any manner they deem appropriate for their functionality, and it is not expected that this field will have the exact same semantics across containers. This field may be used interchangeably with the string 'hasApp'.

opensocial.DataRequest.FilterType.TOP_FRIENDS

Retrieves only the user's top friends as defined by the container. Container support for this filter type is OPTIONAL. This field may be used interchangeably with the string 'topFriends'.

opensocial.DataRequest.FilterType.IS_FRIENDS_WITH

Will filter the people requested by checking if they are friends with the given IdSpec. Expects a filterOptions parameter to be passed with the IdSpec that each person must be friends with. This field may be used interchangeably with the string 'isFriendsWith'.

Examples

Here's an example of getting the viewer's friends that also have this app installed.

var req = opensocial.newDataRequest();  
  var viewerFriends = opensocial.newIdSpec({ "userId" : "VIEWER", "groupId" : "FRIENDS" });
  var opt_params = {};
  opt_params[opensocial.DataRequest.PeopleRequestFields.FILTER ] =
      opensocial.DataRequest.FilterType.HAS_APP;
  req.add(req.newFetchPeopleRequest(viewerFriends, opt_params), 'viewerFriends');
 
  req.send(onLoadFriends);

opensocial.DataRequest.PeopleRequestFields

PeopleRequestFields are used to specify the content returned in a newFetchPeopleRequest

opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS

An array of opensocial.Person.Field specifying what profile data to fetch for each of the person objects. The server will always include ID, NAME, and THUMBNAIL_URL. This field may be used interchangeably with the string 'profileDetail'.

opensocial.DataRequest.PeopleRequestFields.SORT_ORDER

A sort order for the people objects; defaults to TOP_FRIENDS. Possible values are defined by opensocial.DataRequest.SortOrder. This field may be used interchangeably with the string 'sortOrder'.

opensocial.DataRequest.PeopleRequestFields.FILTER

How to filter the people objects; defaults to ALL. Possible values are defined by opensocial.DataRequest.FilterType. This field may be used interchangeably with the string 'filter'.

opensocial.DataRequest.PeopleRequestFields.FILTER_OPTIONS

Additional options to be passed into the filter, specified as a Map<String, Object>. This field may be used interchangeably with the string 'filterOptions'.

opensocial.DataRequest.PeopleRequestFields.FIRST

When paginating, the index of the first item to fetch; specified as a number. This field may be used interchangeably with the string 'first'.

opensocial.DataRequest.PeopleRequestFields.MAX

The maximum number of items to fetch, specified as a number; defaults to 20. If set to a larger number, a container may honor the request, or may limit the number to a container-specified limit of at least 20. This field may be used interchangeably with the string 'max'.

Examples

opensocial.DataRequest.SortOrder

opensocial.DataRequest.SortOrder.TOP_FRIENDS

When used will sort people by the container's definition of top friends. This field may be used interchangeably with the string 'topFriends'.

opensocial.DataRequest.SortOrder.NAME

When used will sort people alphabetically by the name field. This field may be used interchangeably with the string 'name'.

Examples

Here's an example of creating, initializing, sending, and handling the results of a data request:

function requestMe() {
   var req = opensocial.newDataRequest();
   req.add(req.newFetchPersonRequest(
            opensocial.IdSpec.PersonId.VIEWER),
           "viewer");
   req.send(handleRequestMe);
 };
 
 function handleRequestMe(data) {
   var viewer = data.get("viewer");
   if (viewer.hadError()) {
     //Handle error using viewer.getError()...
     return;
   }
 
   //No error. Do something with viewer.getData()...
 }