Opensocial.DataRequest (v0.9)

From OpenSocial

Jump to: navigation, search
Image:Codesample.png This page has example code which needs to be improved.
Please help improve this page by fixing existing code or writing additional examples.


Contents

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. Here's an example of creating, initializing, sending, and handling the results of a data request: 

function requestMe() {
 var req = opensocial.newDataRequest();
 var fetchPersonRequest =
    req.newFetchPersonRequest( opensocial.IdSpec.PersonId.VIEWER);
 req.add(fetchPersonRequest, "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()... */
 }

See also: opensocial.newDataRequest()

Methods

opensocial.DataRequest.add

add(request, opt_key)
Parameters
Name Type Description
request Object Specifies which data to fetch or update
opt_key String A key to map the generated response data to
Description
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.

opensocial.DataRequest.newCreateAlbumRequest

Object newCreateAlbumRequest(An, album)
Parameters
Name Type Description
An opensocial.IdSpec IdSpec used to specify which people/groups to create an album for.
album opensocial.Album The album to create.
Returns
Type Description
Object A request object
Description
Creates a new album and returns the ID of the album created. Containers implement restrictions - like allowing a viewer to create albums for only him/herself.

opensocial.DataRequest.newCreateMediaItemRequest

Object newCreateMediaItemRequest(An, albumId, mediaItem)
Parameters
Name Type Description
An opensocial.IdSpec IdSpec used to specify which people/groups own the album.
albumId string The album to add the media item to.
mediaItem opensocial.MediaItem The MediaItem to add to the album.
Returns
Type Description
Object A request object
Description
Creates a new media item in the album and returns the ID of the album created. Containers implement restrictions.

opensocial.DataRequest.newDeleteAlbumRequest

Object newDeleteAlbumRequest(An, albumId)
Parameters
Name Type Description
An opensocial.IdSpec IdSpec used to specify which people/groups own the album.
albumId string The album to delete.
Returns
Type Description
Object A request object
Description
Deletes the album specified. Containers implement restriction.

opensocial.DataRequest.newFetchActivitiesRequest

Object newFetchActivitiesRequest(idSpec, opt_params)
Parameters
Name Type Description
idSpec opensocial.IdSpec An IdSpec used to specify which people to fetch. See also IdSpec.
opt_params Map.<opensocial.DataRequest.ActivityRequestFields|Object> Additional parameters to pass to the request; not currently used
Returns
Type Description
Object A request object
Description
Creates an item to request an activity stream from the server.

When processed, returns a Collection<Activity>.

opensocial.DataRequest.newFetchAlbumsRequest

Object newFetchAlbumsRequest(An, opt_params)
Parameters
Name Type Description
An opensocial.IdSpec IdSpec used to specify which people/groups to fetch albums from.
opt_params Map.<string|string> opt_params can specify the following: opensocial.Album.Field.ID - an array of album Ids to fetch (fetch all albums if empty, subject to pagination) opensocial.Album.Field.MEDIA_TYPE - an array of MediaItem.TYPE values to specify the kind of Albums to fetch. opensocial.DataRequest.AlbumRequestFields.FIRST - The first item to fetch. opensocial.DataRequest.AlbumRequestFields.MAX - The maximum number of items to fetch.
Returns
Type Description
Object A request object
Description
The newFetchAlbumsRequest() creates an object for DataRequest to request albums.

opensocial.DataRequest.newFetchMediaItemsRequest

Object newFetchMediaItemsRequest(An, albumId, opt_params)
Parameters
Name Type Description
An opensocial.IdSpec IdSpec used to specify which people/groups to fetch media items from.
albumId string The id of the album to fetch MediaItems from.
opt_params Map.<string|string> opt_params can specify the following: opensocial.MediaItem.Field.ID - an array of media item ids to selectively fetch (fetch all items if empty, subject to pagination) opensocial.MediaItem.Field.MEDIA_TYPE - an array of MediaItem.TYPE values to specify the types of MediaItems to fetch opensocial.DataRequest.MediaItemRequestFields.FIRST - The first item to fetch. opensocial.DataRequest.MediaItemRequestFields.MAX - The maximum number of items to fetch.
Returns
Type Description
Object A request object
Description
The newFetchMediaItemsRequest() creates an object for DataRequest to request mediaItems.

opensocial.DataRequest.newFetchPeopleRequest

Object newFetchPeopleRequest(idSpec, opt_params)
Parameters
Name Type Description
idSpec opensocial.IdSpec An IdSpec used to specify which people to fetch. See also IdSpec.
opt_params Map.<opensocial.DataRequest.PeopleRequestFields|Object> Additional params to pass to the request
Returns
Type Description
Object A request object
Description
Creates an item to request friends from the server. When processed, returns a Collection < Person > object.

opensocial.DataRequest.newFetchPersonAppDataRequest

Object newFetchPersonAppDataRequest(idSpec, keys, opt_params)
Parameters
Name Type Description
idSpec opensocial.IdSpec An IdSpec used to specify which people to fetch. See also IdSpec.
keys Array.<String> | String The keys you want data for; this can be an array of key names, a single key name, or "*" to mean "all keys"
opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request
Returns
Type Description
Object A request object
Description
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.

opensocial.DataRequest.newFetchPersonRequest

Object newFetchPersonRequest(id, opt_params)
Parameters
Name Type Description
id String The ID of the person to fetch; can be the standard person ID of VIEWER or OWNER
opt_params Map.<opensocial.DataRequest.PeopleRequestFields|Object> Additional parameters to pass to the request; this request supports PROFILE_DETAILS
Returns
Type Description
Object A request object
Description
Creates an item to request a profile for the specified person ID. When processed, returns a Person object.

opensocial.DataRequest.newRemovePersonAppDataRequest

Object newRemovePersonAppDataRequest(keys)
Parameters
Name Type Description
keys Array.<String> | String 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
Type Description
Object A request object
Description
Deletes the given keys from the datastore for the current VIEWER. When processed, does not return any data.

opensocial.DataRequest.newUpdateAlbumRequest

Object newUpdateAlbumRequest(An, albumId, fields)
Parameters
Name Type Description
An opensocial.IdSpec IdSpec used to specify which people/groups to own the album.
albumId string The album to update.
fields Map<opensocial.Album.Field|object> The Album Fields to update.The following fields cannot be set: MEDIA_ITEM_COUNT, OWNER_ID, ID. Containers implement restrictions.
Returns
Type Description
Object A request object
Description
Updates the fields specified in the params.The following fields cannot be set: MEDIA_ITEM_COUNT, OWNER_ID, ID. Containers implement restrictions.

opensocial.DataRequest.newUpdateMediaItemRequest

Object newUpdateMediaItemRequest(An, albumId, mediaItemId, fields)
Parameters
Name Type Description
An opensocial.IdSpec IdSpec used to specify which people/groups own the album/media item.
albumId string The album containing the media item to update.
mediaItemId string The media item to update.
fields Map<opensocial.MediaItem.Field|object> The Album Fields to update.The following fields cannot be set: ID, CREATED, ALBUM_ID, FILE_SIZE, NUM_COMMENTS. Containers implement restrictions.
Returns
Type Description
Object A request object
Description
Updates the fields specified in the params.The following fields cannot be set: ID, CREATED, ALBUM_ID, FILE_SIZE, NUM_COMMENTS. Containers implement restrictions.

opensocial.DataRequest.newUpdatePersonAppDataRequest

Object newUpdatePersonAppDataRequest(key, value)
Parameters
Name Type Description
key String The name of the key. This may only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-).
value Object The value, must be valid json
Returns
Type Description
Object A request object
Description
Creates an item to request an update of an app field for the current VIEWER. When processed, does not return any data. App Data is stored as a series of key value pairs of strings, scoped per person, per application.

opensocial.DataRequest.send

send(opt_callback)
Parameters
Name Type Description
opt_callback Function The function to call with the data response generated by the server. The callback function will not be called until after the existing callstack has completed execution.
Description
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.

opensocial.DataRequest.ActivityRequestFields

The values needed to handle activity paging.

opensocial.DataRequest.ActivityRequestFields.FIRST

<static> Member of: opensocial.DataRequest.ActivityRequestFields.FIRST When paginating, the index of the first item to fetch; specified as a number.

opensocial.DataRequest.ActivityRequestFields.MAX

<static> Member of: opensocial.DataRequest.ActivityRequestFields.MAX The maximum number of items to fetch, specified as a number; defaults to 20.

opensocial.DataRequest.AlbumRequestFields

The values needed to handle activity paging.

opensocial.DataRequest.AlbumRequestFields.FIRST

<static> Member of: opensocial.DataRequest.AlbumRequestFields.FIRST When paginating, the index of the first item to fetch; specified as a number.

opensocial.DataRequest.AlbumRequestFields.MAX

<static> Member of: opensocial.DataRequest.AlbumRequestFields.MAX The maximum number of items to fetch, specified as a number; defaults to 20.

opensocial.DataRequest.DataRequestFields

opensocial.DataRequest.DataRequestFields.ESCAPE_TYPE

<static> Member of: opensocial.DataRequest.DataRequestFields.ESCAPE_TYPE How to escape person data returned from the server; defaults to HTML_ESCAPE. Possible values are defined by EscapeType. This field may be used interchangeably with the string 'escapeType'. Use of this function is deprecated in favor of us using the ESCAPE_TYPE request field.

opensocial.DataRequest.FilterType

The filters available for limiting person requests.

opensocial.DataRequest.FilterType.ALL

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

opensocial.DataRequest.FilterType.HAS_APP

<static> Member of: 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.IS_FRIENDS_WITH

<static> Member of: 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 following fields defined: - idSpec The idSpec that each person must be friends with. This field may be used interchangeably with the string 'isFriendsWith'.

opensocial.DataRequest.FilterType.TOP_FRIENDS

<static> Member of: 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.MediaItemRequestFields

The values needed to handle activity paging.

opensocial.DataRequest.MediaItemRequestFields.FIRST

<static> Member of: opensocial.DataRequest.MediaItemRequestFields.FIRST When paginating, the index of the first item to fetch; specified as a number.

opensocial.DataRequest.MediaItemRequestFields.MAX

<static> Member of: opensocial.DataRequest.MediaItemRequestFields.MAX The maximum number of items to fetch, specified as a number; defaults to 20.

opensocial.DataRequest.PeopleRequestFields

opensocial.DataRequest.PeopleRequestFields.APP_DATA

<static> Member of: opensocial.DataRequest.PeopleRequestFields.APP_DATA An array of strings, specifying the app data keys to fetch for each of the Person objects. This field may be used interchangeably with the string 'appData'.

opensocial.DataRequest.PeopleRequestFields.ESCAPE_TYPE

<static> Member of: opensocial.DataRequest.PeopleRequestFields.ESCAPE_TYPE How to escape Person fields and app data returned from the server; defaults to HTML_ESCAPE. Possible values are defined by EscapeType. This field may be used interchangeably with the string 'escapeType'.

opensocial.DataRequest.PeopleRequestFields.FILTER

<static> Member of: opensocial.DataRequest.PeopleRequestFields.FILTER How to filter the people objects; defaults to ALL. Possible values are defined by FilterType. This field may be used interchangeably with the string 'filter'.
The following example returns the owner's friends who have the current application installed: 
function response(data) {
  output(data.get("req").getData().size());
  gadgets.window.adjustHeight();
};
 
function request() {
  var req = opensocial.newDataRequest();
  var idspec = opensocial.newIdSpec({'userId':'OWNER', 'groupId':'FRIENDS'});
  var params = {
    'filter' : 'hasApp'
  };
  req.add(req.newFetchPeopleRequest(idspec, params), "req");
  req.send(response);
};
 
request();

opensocial.DataRequest.PeopleRequestFields.FILTER_OPTIONS

<static> Member of: 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

<static> Member of: 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'.
Use this to page through groups of friends. The following example starts fetching from the 20th friend: 
function response(data) {
  output(data.get("req").getData().size());
  gadgets.window.adjustHeight();
};
 
function request() {
  var req = opensocial.newDataRequest();
  var idspec = opensocial.newIdSpec({'userId':'OWNER', 'groupId':'FRIENDS'});
  var params = {
    'first' : 20
  };
  req.add(req.newFetchPeopleRequest(idspec, params), "req");
  req.send(response);
};
 
request();

opensocial.DataRequest.PeopleRequestFields.MAX

<static> Member of: 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'.
Use this to page through groups of friends. The following example sets the page size to 5: 
function response(data) {
  output(data.get("req").getData().size());
  gadgets.window.adjustHeight();
};
 
function request() {
  var req = opensocial.newDataRequest();
  var idspec = opensocial.newIdSpec({'userId':'OWNER', 'groupId':'FRIENDS'});
  var params = {
    'max' : 5
  };
  req.add(req.newFetchPeopleRequest(idspec, params), "req");
  req.send(response);
};
 
request();

opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS

<static> Member of: 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

<static> Member of: opensocial.DataRequest.PeopleRequestFields.SORT_ORDER A sort order for the people objects; defaults to TOP_FRIENDS. Possible values are defined by SortOrder. This field may be used interchangeably with the string 'sortOrder'.

opensocial.DataRequest.SortOrder

The sort orders available for ordering person objects.

opensocial.DataRequest.SortOrder.NAME

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

opensocial.DataRequest.SortOrder.TOP_FRIENDS

<static> Member of: 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 (v0.9)
opensocial

opensocial.Activity

opensocial.Address

opensocial.Album

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

opensocial.Name

opensocial.NavigationParameters

opensocial.Organization

opensocial.Permission

opensocial.Person

opensocial.Phone

opensocial.ResponseItem

opensocial.Url

osapi.Request

osapi.BatchRequest

osapi.people

osapi.activities

osapi.appdata

osapi.messages

osapi.http

gadgets

gadgets.io

gadgets.json

gadgets.Prefs

gadgets.util

gadgets.views

gadgets.flash

gadgets.MiniMessage

gadgets.oauth.Popup

gadgets.rpc

gadgets.skins

gadgets.Tab

gadgets.TabSet

gadgets.window

gadgets.i18n

Retrieved from "http://wiki.opensocial.org/index.php?title=Opensocial.DataRequest_%28v0.9%29"

Category: Pages with example code that should be improved

Personal tools