Library: opensocialreference.js
Overview
Interface for containers of people functionality.
Constructors
Collection of multiple objects with useful accessors. May also represent subset of a larger collection (for example, page 1 of 10) and contain information about the larger collection.
methods
Base interface for all surface objects.
methods
Represents a response that was generated by processing a data request item on the server.
methods
Base interface for all person objects.
methods
This object contains the requested server data mapped to the requested keys.
See also: DataRequest
Creates an item 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();
req.add(req.newFetchPersonRequest(
opensocial.DataRequest.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()...
}
See also: opensocial.newDataRequest()
methods
Namespaces
Namespace for top-level people functions.
methods
opensocial.CreateActivityPriority
opensocial.ContentRequestParameters
opensocial.ContentRequestParameters.MethodType
opensocial.ContentRequestParameters.ContentType
opensocial.ContentRequestParameters.AuthorizationType
opensocial.Activity.Field
opensocial.Activity.MediaItem.Type
opensocial.Activity.MediaItem.Field
opensocial.ResponseItem.Error
Error codes that a response item can return.
All of the fields that a person has. These are the supported keys for the
Person.getField() method.
opensocial.Environment.ObjectType
opensocial.DataRequest.PersonId
Constant person IDs available when fetching person information.
opensocial.DataRequest.Group
Groups available when fetching person information.
opensocial.DataRequest.SortOrder
The sort orders available for ordering person objects.
opensocial.DataRequest.FilterType
The filters available for limiting person requests.
opensocial.DataRequest.PeopleRequestFields
opensocial.DataRequest.ActivityRequestFields
Functions
opensocial.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 member and the request is marked as HIGH priority then this call may open a user flow and navigate away from your gadget.
parameters
Returns true if the current gadget has access to the specified permission.
parameters
returns
| Boolean |
True if the gadget has access for the permission; false if it doesn't |
opensocial.requestPermission(
permissions, reason, opt_callback)
Requests the member to grant access to the specified permissions.
parameters
| Array.<opensocial.Permission> |
permissions |
The permissions to request from the viewer |
| String |
reason |
Displayed to the member 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 |
Attempts to navigate to this gadget on a different surface. If the container supports parameters will pass the optional parameters along to the gadget on the new surface.
parameters
| opensocial.Surface |
surface |
The surface to navigate to |
| Map.<String, String> |
opt_params |
Params to pass to the gadget after it has been navigated to on the surface |
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
Fetches content from the provided URL and feeds that content into the callback function.
parameters
| String |
url |
The URL where the content is located |
| Function |
callback |
The function to call with the data from the URL once it is fetched |
| Map.<opensocial.ContentRequestParameters, Object> |
opt_params |
Additional parameters to pass to the request |
Creates a data request object to use for sending and fetching data from the server.
returns
parameters
| String |
title |
The title of an activity |
| Map.<opensocial.Activity.Field, Object> |
opt_params |
Any other fields that should be set on the activity object; all of the defined Fields are supported |
returns
opensocial.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
returns
Finds the entry with the given ID value, or returns null if none is found.
parameters
| String |
id |
The ID to look for |
returns
Gets the size of this collection, which is equal to or less than the total size of the result.
returns
| Number |
The size of this collection |
Executes the provided function once per member of the collection, with each member in turn as the parameter to the function.
parameters
| Function |
fn |
The function to call with each collection entry |
Returns an array of all the objects in this collection.
returns
| Array.<Object> |
The values in this collection |
Gets the total size of the larger result set that this collection belongs to.
returns
| Number |
The total size of the result |
Gets the offset of this collection within a larger result set.
returns
| Number |
The offset into the total collection |
Gets an ID that can be permanently associated with this activity.
returns
Gets the activity data that's associated with the specified key.
parameters
| String |
key |
The key to get data for; see the Field class for possible values |
returns
Sets data for this activity associated with the given key.
parameters
| String |
key |
The key to set data for |
| String |
data |
The data to set |
Gets the media item data that's associated with the specified key.
parameters
| String |
key |
The key to get data for; see the Field class for possible values |
returns
Sets data for this media item associated with the given key.
parameters
| String |
key |
The key to set data for |
| String |
data |
The data to set |
Returns the name of this surface.
returns
Returns true if the gadget is the primary content on this surface. On a canvas page this is most likely true; on a profile page, it is most likely false.
returns
| boolean |
True if the gadget is the primary content; otherwise, false |
Returns true if there was an error in fetching this data from the server.
returns
| Boolean |
True if there was an error; otherwise, false |
If the request had an error, returns the error code. The error code can be container-specific or one of the values defined by
Error.
returns
| String |
The error code, or null if no error occurred |
If the request had an error, returns the error message.
returns
| String |
A human-readable description of the error that occurred; can be null, even if an error occurred |
Returns the original data request.
returns
Gets the response data.
returns
| Object |
The requested value calculated by the server; the type of this value is defined by the type of request that was made |
Gets an ID that can be permanently associated with this person.
returns
Gets a text display name for this person; guaranteed to return a useful string.
returns
Gets data for this person that is associated with the specified key.
parameters
| String |
key |
The key to get data for; keys are defined in Person.Field |
returns
Returns true if this person object represents the currently logged in member.
returns
| Boolean |
True if this is the currently logged in member; otherwise, false |
Returns true if this person object represents the owner of the current page.
returns
| Boolean |
True if this is the owner of the page; otherwise, false |
Returns the current domain — for example, "orkut.com" or "myspace.com".
returns
Returns the current surface.
returns
Returns an array of all the supported surfaces.
returns
Returns the parameters passed into this gadget.
returns
| Map.<String, String> |
The parameter map |
Returns true if the specified field is supported in this container on the given object type.
parameters
returns
| Boolean |
True if the field is supported on the specified object type |
Returns true if the specified function is supported in this container.
parameters
| String |
functionName |
The function name |
returns
| Boolean |
True if this container supports the function |
Returns true if there was an error in fetching this data from the server.
returns
| Boolean |
True if there was an error; otherwise, false |
Gets the ResponseItem for the requested field.
parameters
returns
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 |
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 |
Creates an item to request a profile for the specified person ID. When processed, returns a
Person object.
parameters
returns
Creates an item to request friends from the server. When processed, returns a
Collection <
Person> object.
parameters
| Array.<String>, String |
idSpec |
An ID, array of IDs, or a group reference used to specify which people to fetch; the supported keys are VIEWER, OWNER, VIEWER_FRIENDS, OWNER_FRIENDS, or a single ID within one of those groups. |
| Map.<opensocial.DataRequest.PeopleRequestFields, Object> |
opt_params |
Additional params to pass to the request |
returns
Creates an item to request global app data. When processed, returns a Map<String, String> object.
parameters
| 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" |
returns
Creates an item to request instance app data. When processed, returns a Map<String, String> object.
parameters
| 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" |
returns
Creates an item to request an update of an app instance field from the server. When processed, does not return any data.
parameters
| String |
key |
The name of the key. This may only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-). |
| String |
value |
The value |
returns
Creates an item to request app data for the given people. When processed, returns a Map<
PersonId, Map<String, String>> object.
parameters
| Array.<String>, String |
idSpec |
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 |
| 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" |
returns
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(-). |
| String |
value |
The value |
returns
Creates an item to request an activity stream from the server.
When processed, returns an object whose "activities" property is a Collection<Activity> object.
parameters
| Array.<String>, String |
idSpec |
An ID, array of IDs, or a group reference used to specify which people's activities to fetch; the supported keys are VIEWER, OWNER, VIEWER_FRIENDS, OWNER_FRIENDS, or a single ID within one of those groups. |
| Map.<opensocial.DataRequest.ActivityRequestFields, Object> |
opt_params |
Additional parameters to pass to the request |
returns
Default taming is to return obj itself. Depending on other taming decisions, it may be more appropriate to return an interposed wrapper.
parameters
Objects
If the activity is of high importance, it will be created even if this requires asking the member for permission. This may cause the container to open a member flow which may navigate away from your gagdet.
If the activity is of low importance, it will not be created if the member has not given permission for the current app to create activities. With this priority, the requestCreateActivity call will never open a member flow.
Access to the viewer person object
The method to use when fetching content from the URL; defaults to
MethodType.GET. Specified as a
MethodType.
The type of content that lives at the URL; defaults to
ContentType.HTML. Specified as a
ContentType.
The data to send to the URL using the POST method. Specified as a String Defaults to null.
The HTTP headers to send to the URL. Specified as a Map. Defaults to null.
If the content is a feed, the number of entries to fetch; defaults to 3. Specified as a Number.
If the content is a feed, whether to fetch summaries for that feed; defaults to false. Specified as a Boolean.
opensocial.ContentRequestParameters.MethodType.PUT
opensocial.ContentRequestParameters.MethodType.DELETE
opensocial.ContentRequestParameters.MethodType.HEAD
A string ID that can be permanently associated with this activity.
A string ID associated with this activity that was generated by the posting app externally.
The string ID of the member who this activity is for.
A string specifying the application that this activity is associated with.
A string specifing the title of the stream.
A string specifying the stream's URL.
A string specifying the stream's source URL.
A string specifying the URL for the stream's favicon.
A string specifying the title of an activity; the only field that is guaranteed to display when rendering.
A string specifying the full text of an activity.
A string specifying the URL that represents this activity.
Any photos, videos, or images that should be associated with the activity. Higher priority ones are higher in the list. The data has type
Array< MediaItem>.
A string specifying the time at which this activity took place in milliseconds since the epoch.
The MIME type of media, specified as a String.
A string specifying the URL where the media can be found.
This container does not support the request that was made.
The gadget can never have access to the requested data.
The request was invalid. Example: 'max' was -1.
The request encountered an unexpected condition that prevented it from fulfilling the request.
A string ID that can be permanently associated with this person.
A string containing the person's name.
Person's photo thumbnail URL, specified as a string.
Person's profile URL, specified as a string.
Person's age, specified as a number. Not supported by all containers.
Person's gender, specified as a string. Not supported by all containers.
When used will sort people by the container's definition of top friends.
When used will sort people alphabetically by the name field.
Retrieves all friends with any data for this application.
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.
A sort order for the people objects; defaults to TOP_FRIENDS. Possible values are defined by
SortOrder.
How to filter the people objects; defaults to ALL. Possible values are defined by
FilterType.
When paginating, the index of the first item to fetch. Specified as a Number.
The maximum number of items to fetch; 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. Specified as a Number.