OpenSocial Social Gadget Specification 2.0opensocial-and-gadgets-spec@googlegroups.comThis document defines additional APIs to add social capabilities to a Core Gadget container.
General
OpenSocialsocial networkingRESTXMLExtensible Markup LanguageJSONJavaScript Object NotationAtomDomain name examples use RFC2606.The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
RFC2119.OpenSocial provides three ways for gadgets to access social data. First, the JavaScript API contains methods in the osapi.* namespace which map to the services defined in the Social API Server Specification. Second, Data Pipelining is a declarative syntax for specifying the social data a gadget will need, allowing the container to prefetch data for faster gadget rendering. Third, Templating provides several tags to accomplish common tasks, like displaying the UI for selecting friends from a list.For an overview of the patterns used in the following reference, see the introduction to the JavaScript API Reference in Service object with functions that map to the
People service.<static> { osapi.Request } osapi.people.get(params)Builds a request to retrieve information from the
People service. When no parameter is specified, the container MUST use the
default values, returning the the viewer's information.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method.A osapi.Request to retrieve information from the People service. Executing this request MUST return a Person object or a Collection of Person objects.<static> { osapi.Request }
osapi.people.getViewer(params)A convenience over osapi.people.get() that builds a
request to retrieve the viewer, as specified in the security token,
from the People service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method, except that the value for the userId parameter is set to '@viewer'.A osapi.Request to retrieve information from the People service. Executing this request MUST return a Person object representing the viewer.<static> {
osapi.Request }
osapi.people.getViewerFriends(params)A convenience over osapi.people.get() that builds a
request to retrieve the viewer's friends, as specified in the security
token, from the People service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method, except that the value for the userId parameter is set to '@viewer' and the groupId parameter is set to "@friends".A osapi.Request to retrieve information from the People service. Executing this request MUST return a Collection of Person objects representing the viewer's friends.<static> { osapi.Request }
osapi.people.getOwner(params)A convenience over osapi.people.get() that builds a
request to retrieve the owner, as specified in the security token,
from the People service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method, except that the value for the userId parameter is set to '@owner'.A osapi.Request to retrieve information from the People service. Executing this request MUST return a Person object representing the owner.<static> {
osapi.Request }
osapi.people.getOwnerFriends(params)A convenience over osapi.people.get() that builds a
request to retrieve the owner's friends, as specified in the security
token, from the People service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method, except that the value for the userId parameter is set to '@owner' and the groupId parameter is set to "@friends".A osapi.Request to retrieve information from the People service. Executing this request MUST return a Collection of Person objects representing the owner's friends.A Person request, the most basic example:
osapi.people.getViewer().execute(function(result) {
if (!result.error) {
alert('Your name is ' + result.displayName + '!');
}
});A Person request with a JSON request parameter object
specifying which fields to retrieve:
osapi.people.getViewer({fields: ['displayName', 'birthday']}).execute(function(result) {
if (!result.error) {
alert('Your name is ' + result.displayName + '!');
alert('Your birthday is ' + result.birthday + '!');
}
});
A simple example to request the owner's friends:
osapi.people.get({userId: '@owner', groupId: '@friends'}).execute(function(result) {
if (!result.error) {
alert('You have ' + result.totalResults + ' friends');
}
});
An example that illustrates all available request
parameters:
var params = {
userId: "@owner",
groupId: "@friends",
fields: "@all",
count: 10,
startIndex: 0,
startPage: 0
};
osapi.people.get(params).execute(function(result) {
if (!result.error) {
alert('You have ' + result.totalResults + ' friends');
}
});
Service object with functions that map to the
Activities service.<static> { osapi.Request } osapi.activities.get(params)Builds a request to retrieve information from the
Activities service. When no parameter is specified, the container MUST use the
default values, returning the viewer's activities.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Activities service's get method, except that the 'appId' parameter can not be changed from "@app".A osapi.Request to retrieve information from the Activities service. Executing this request MUST return a Activity object or a Collection of Activity objects.<static> { osapi.Request } osapi.activities.get(params)Builds a request to create a new activity using the Activities service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Activities service's create method, except that the 'appId' parameter can not be changed from "@app". This parameter is REQUIRED and MUST contain the 'activity' property.A osapi.Request to retrieve information from the Activities service. Executing this request MUST attempt to create the specified Activity and return the newly-created Activity object if successful.A simple example to retrieve the activities of the viewer's
friends:
osapi.activities.get({userId: '@viewer', groupId: '@friends', count: 20}).execute(myCallback);
An example illustrating all available request parameters for
osapi.activites.get():
var params = {
userId: "@me",
groupId: "@self",
activityIds = ["YYYYYYY", "ZZZZZZZ"],
fields: "@all",
count: 10,
startIndex: 0,
startPage: 0
};
osapi.activities.get(params).execute(myCallback);
A simple example to create an activity for the
viewer:
osapi.activities.create({userId: '@viewer', activity: {title: 'Hello!', url: 'http://mysite.com'}}).execute(myCallback);
An example illustrating all available request parameters for
osapi.activites.create():
var params = {
userId: "@viewer",
groupId: "@self",
activity: {title: 'Hello!', url: 'http://mysite.com'}
};
osapi.activities.create(params).execute(myCallback);
DiscussionService object with functions that map to the
Activity Streams service.<static> { osapi.Request } osapi.activitystreams.get(params)Builds a request to retrieve information from the
Activity Streams service. When no parameter is specified, the container MUST use the
default values, returning the viewer's ActivityEntries.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Activity Stream service's get method.A osapi.Request to retrieve information from the Activity Streams service. Executing this request MUST return an ActivityEntry object or a Collection of ActivityEntry objects.<static> { osapi.Request } osapi.activitystreams.create(params)Builds a request to create a new ActivityEntry using the Activity Streams service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Activity Stream service's create method. This parameter is REQUIRED and MUST contain the 'activityEntry' property.A osapi.Request to retrieve information from the Activity Streams service. Executing this request MUST attempt to create the specified ActivityEntry and return the newly-created ActivityEntry object if successful.<static> { osapi.Request } osapi.activitystreams.update(params)Builds a request to update information stored in the Activity Streams service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Activity Stream service's update method. This parameter is REQUIRED and MUST include the 'activity' property which includes the id of the ActivityEntry to update.A osapi.Request to retrieve information from the Activity Streams service. Executing this request MUST overwrite the existing activity entries on the server, but does not return any values.<static> { osapi.Request } osapi.activitystreams.delete(params)Builds a request to delete information stored in the Activity Streams service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Activity Stream service's delete method. This parameter is REQUIRED and MUST include the 'activityId' property.A osapi.Request to retrieve information from the MediaItems service. Executing this request MUST remove the specified MediaItems from the server and return them as a JavaScript object.A simple example to retrieve the Activity Streams of the viewer's
friends:
osapi.activitystreams.get({userId: '@viewer', groupId: '@friends', count: 20}).execute(myCallback);An example illustrating all available request parameters for
osapi.activitystreams.get():
var params = {
userId: "@me",
groupId: "@self",
activityId = ["YYYYYYY", "ZZZZZZZ"],
fields: "@all",
count: 10,
startIndex: 0,
startPage: 0
};
osapi.activitystreams.get(params).execute(myCallback);An example to create an ActivityEntry:
var params = {
userId: '@viewer',
groupId: '@self',
activity: {
title: "Eric posted a photo",
published: '2010-04-27T06:02:36+0000',
id: "activity1",
actor: {
id: 'john.doe',
displayName: 'John Doe'
},
verb: 'post',
object: {
id: 'object1',
displayName: 'Frozen Eric',
image: {
url: 'http://www.example.com/ericsalbum/cover.jpg',
width: 400,
height: 300,
duration: 93
}
}
}
};
osapi.activitystreams.create(params).execute(callback);Service object with functions that map to the
AppData service.<static> { osapi.Request } osapi.appdata.get(params)Builds a request to retrieve information from the
AppData service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the AppData service's get method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED, and MUST include the 'keys' property.A osapi.Request to retrieve information from the AppData service. Executing this request MUST return a JavaScript object where each of the requested keys is a property, and each property is populated with the corresponding value that was persisted using the AppData service.<static> { osapi.Request } osapi.appdata.update(params)Builds a request to update information stored in the
AppData service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the AppData service's update method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'data' property.A osapi.Request to retrieve information from the AppData service. Executing this request MUST overwrite the existing AppData on the server, but does not return any values.<static> { osapi.Request } osapi.appdata.delete(params)Builds a request to delete information stored in the AppData service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the AppData service's delete method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'keys' property.A osapi.Request to retrieve information from the AppData service. Executing this request MUST remove the specified key/value pairs from the server and return them as a JavaScript object.A simple example to retrieve, update, and delete a piece of
app data:
osapi.appdata.get({userId: '@viewer', groupId: '@friends', keys: ['gifts']}).execute(myGetCallback);
osapi.appdata.update({userId: '@viewer', data: {gifts: 'a crazed monkey'}}).execute(myUpdateCallback);
osapi.appdata.delete({keys: ['gifts']}).execute(myDeleteCallback)
An example illustrating all available request parameters for
osapi.appdata.get():
var getParams = {
userId: "@viewer",
groupId: "@friends",
keys: ['gifts', 'wishlist']
};
osapi.appdata.get(getParams).execute(myGetCallback);
An example illustrating all available request parameters for
osapi.appdata.update():
var updateParams = {
auth: {"default" : null, "type" : "AuthToken"},
userId: "@viewer",
groupId: "@friends",
data: {gifts: 'a crazed monkey', wishlist: 'a banana peel'}
};
osapi.appdata.update(updateParams).execute(myUpdateCallback);
An example illustrating all available request parameters for
osapi.appdata.delete():
var deleteParams = {
userId: "@viewer",
groupId: "@friends",
keys: ['gifts', 'wishlist']
};
osapi.appdata.delete(deleteParams).execute(myDeleteCallback)
Service object with functions that map to the
Groups service.<static> { osapi.Request } osapi.groups.create(params)Builds a request to create a group via the Groups service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Groups service's create method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'group' property.A osapi.Request to create a group via the Groups service. Executing this request MUST create a group and return the newly created group.<static> { osapi.Request } osapi.groups.get(params)Builds a request to get a group or groups via the Groups service.This method takes one parameter, which is a JavaScript object representing the parameters defined by the Groups service's get method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'message' property.A osapi.Request to get a group or groups via the Groups service. Executing this request MUST return a Group or a Collection of Groups.<static> { osapi.Request } osapi.groups.update(params)Builds a request to update a group via the Groups service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Groups service's update method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'group' property.A osapi.Request to update a group via the Groups service. Executing this request MUST update a group, but does not return any information.<static> { osapi.Request } osapi.groups.delete(params)Builds a request to delete a group via the Groups service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Groups service's delete method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'message' property.A osapi.Request to delete a group via the Groups service. Executing this request MUST delete a group, but does not return any information.Service object with functions that map to the
Messages service.<static> { osapi.Request } osapi.messages.send(params)Builds a request to send a message via the Messages service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Messages service's send method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'message' property.A osapi.Request to send a message via the Messages service. Executing this request MUST send a message, but does not return any information.An example illustrating how to send a message using
osapi.messages.send():
var params = {
message: {
"recipients" : ["example.org:AD38B3886625AAF", "example.org:997638BAA6F25AD"],
"title" : "You have a message from Joe",
"body" : "Some content",
"type" : "EMAIL"
},
};
osapi.messages.send(params).execute(messageSentCallback);
Service object with functions that map to the
Albums service.<static> { osapi.Request } osapi.albums.get(params)Builds a request to retrieve information from the
Albums service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Albums service's get method, except that the 'appId' parameter can not be changed from "@appId".A osapi.Request to retrieve information from the Albums service. Executing this request MUST return a Album object or a Collection of Album objects.<static> { osapi.Request } osapi.albums.get(params)Builds a request to create a new album using the Albums service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Albums service's create method, except that the 'appId' parameter can not be changed from "@app". This parameter is REQUIRED and MUST contain the 'data' property.A osapi.Request to retrieve information from the Albums service. Executing this request MUST attempt to create the specified Album and return the newly-created Albums object if successful.<static> { osapi.Request } osapi.albums.update(params)Builds a request to update information stored in the
Activities service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Albums service's update method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'data' property.A osapi.Request to retrieve information from the Albums service. Executing this request MUST overwrite the existing Albums on the server, but does not return any values.<static> { osapi.Request } osapi.albums.delete(params)Builds a request to delete information stored in the Albums service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Albums service's delete method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'ids' property.A osapi.Request to retrieve information from the Albums service. Executing this request MUST remove the specified Albums from the server and return them as a JavaScript object.Service object with functions that map to the
MediaItems service.<static> { osapi.Request } osapi.mediaItems.get(params)Builds a request to retrieve information from the
MediaItems service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the MediaItems service's get method, except that the 'appId' parameter can not be changed from "@appId".A osapi.Request to retrieve information from the MediaItems service. Executing this request MUST return a MediaItems object or a Collection of MediaItems objects.<static> { osapi.Request } osapi.mediaItems.get(params)Builds a request to create a new media item using the MediaItems service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the MediaItems service's create method, except that the 'appId' parameter can not be changed from "@app". This parameter is REQUIRED and MUST contain the 'data' property.A osapi.Request to retrieve information from the MediaItems service. Executing this request MUST attempt to create the specified MediaItems and return the newly-created MediaItem object if successful.<static> { osapi.Request } osapi.mediaItems.update(params)Builds a request to update information stored in the
MediaItems service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the MediaItems service's update method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'data' property.A osapi.Request to retrieve information from the MediaItems service. Executing this request MUST overwrite the existing MediaItems on the server, but does not return any values.<static> { osapi.Request } osapi.mediaItems.delete(params)Builds a request to delete information stored in the MediaItems service.This method takes a single parameter, which is a JavaScript object representing the parameters defined by the MediaItems service's delete method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'ids' property.A osapi.Request to retrieve information from the MediaItems service. Executing this request MUST remove the specified MediaItems from the server and return them as a JavaScript object.Namespace for top-level people functions.There are cases where a gadget may wish to perform an action that needs
approval by the user or mediation by the container. OpenSocial supports
"request" features that allow the container to decide how to handle the
interaction with the user. Functions like
opensocial.requestCreateActivity, and opensocial.requestPermission allow
the container to inject its own policy decisions into the gadget execution
flow and notify the gadget of the result. Under this specification, it is
equally valid for a container to defer to the user, always approve, always
deny, or use any other method to determine responses to request calls.
Additionally, this allows the container to enforce UI flows in a safe and
integrated way.<static>
opensocial.Environment
opensocial.getEnvironment()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.None.TypeDescriptionopensocial.EnvironmentThe current environment.<static> Boolean
opensocial.hasPermission(permission)Returns true if the current gadget has access to the
specified permission. If the gadget calls opensocial.requestPermission
and permissions are granted then this function must return true on all
subsequent calls.NameTypeDescriptionpermissionopensocial.PermissionThe permission.TypeDescriptionBooleanTrue if the gadget has access for the permission; false if it
doesn't.<static> opensocial.NavigationParameters
opensocial.newNavigationParameters(parameters)Creates a NavigationParameters object. See also:
requestShareApp().NameTypeDescriptionparametersMap.<opensocial.NavigationParameters.Field|Object>Parameters defining the navigationTypeDescriptionopensocial.NavigationParametersThe new NavigationParameters object<static> void opensocial.requestPermission(permissions, reason,
opt_callback)Requests the user to grant access to the specified
permissions. If the container does not support this method the callback
will be called with a opensocial.ResponseItem. The response item will
have its error code set to 'notImplemented'.NameTypeDescriptionpermissionsArray.<opensocial.Permission>The permissions to request from the viewerreasonStringDisplayed to the user as the reason why these permissions are
neededopt_callbackFunctionThe 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.None.Discussion<static> void opensocial.requestShareApp(recipients, reason,
opt_callback, opt_params)Requests that the container share this gadget with the
specified users. 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
sharing request was sent. If there was an error, you can use the
response item's getErrorCode method to determine how to proceed. The
data on the response item will not be set. If the container does not support this method the callback will be called with a opensocial.ResponseItem. The response item will have its
error code set to 'notImplemented'.NameTypeDescriptionrecipientsMap <String|String>A parameter map used to represent the target(s) of the app sharing request, e.g. {"userId": "@owner", "groupId": "@friends"}. reasonopensocial.MessageThe 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_callbackFunctionThe function to call once the request has been processed; either
this callback will be called or the gadget will be reloaded from
scratch. The callback function will not be called until after the
existing callstack has completed execution.opt_paramsopensocial.NavigationParametersThe 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.None.Represents the current environment for a gadget. See also:
opensocial.getEnvironment().String getDomain()Returns the current domain. for example, "orkut.com" or
"myspace.com".None.TypeDescriptionStringThe domainBoolean supportsField(objectType, fieldName)Returns true if the specified field is supported in this
container on the given object type, and returns false otherwise.NameTypeDescriptionobjectTypeopensocial.Environment.ObjectTypeThe object type to check for the fieldfieldNameStringThe name of the field to check forTypeDescriptionBooleanTrue if the field is supported on the specified object typeThe types of objects in this container.
See also:
Environment.supportsField()This field may be used interchangeably with the string
'activity'.This field may be used interchangeably with the string
'activityEntry'.This field may be used interchangeably with the string
'address'.This field may be used interchangeably with the string
'bodyType'.This field may be used interchangeably with the string
'email'.This field may be used interchangeably with the string
'filterType'.This field may be used interchangeably with the string
'mediaItem'.This field may be used interchangeably with the string
'message'.This field may be used interchangeably with the string
'messageType'.This field may be used interchangeably with the string
'name'.This field may be used interchangeably with the string
'organization'.This field may be used interchangeably with the string
'person'.This field may be used interchangeably with the string
'phone'.This field may be used interchangeably with the string
'sortOrder'.This field may be used interchangeably with the string
'url'.Parameters used by RequestShareApp to instruct the container on where
to go after the request is made. It could be used, for example, to specify
where viewers get routed in one of two cases:
After a user gets a shareApp invitation or receives a message a gadget
developer should be able to send that user to a context sensitive
place.After a viewer actually shares an app with someone else the gadget
developer should be able to redirect the viewer to a context sensitive
place.String getField(key, opt_params)Gets the data from the NavigationParameters that is associated
with the specified key.NameTypeDescriptionkeyStringThe key to get data for; see opensocial.NavigationParameters.Field class for supported valuesopt_paramsMap.<opensocial.DataRequest.DataRequestFields|Object>Additional params to pass to the request.TypeDescriptionStringThe datavoid setField(key, data)Sets data for this NavigationParameters associated with
the given key.NameTypeDescriptionkeyStringThe key to set data fordataObjectThe data to setNone.DiscussionThe destinations available for navigation in
requestShareApp and
osapi.message.send.This field may be used interchangeably with the string
'recipientDestination'.This field may be used interchangeably with the string
'viewerDestination'.All of the fields that NavigationParameters can have.
See also:
opensocial.NavigationParameters.getField()A string representing the owner id. This field may be
used interchangeably with the string 'owner'.An optional list of parameters passed to the gadget once
the new view, with the new owner, has been loaded. This field may be
used interchangeably with the string 'parameters'.The gadgets.views.View to navigate to. This field may be
used interchangeably with the string 'view'.The permissions an app can ask for.
See also:
opensocial.hasPermission(),
opensocial.requestPermission()Access to the viewer person object This field may be
used interchangeably with the string 'viewer'.The Social Gadget Specification extends the Data Pipelining capabilities of the Core Gadget Specification by adding support for the following tags:A request to get profile information for a group or list of people. This is
equivalent to using <os:DataRequest> with @method of "people.get".The attributes of this tag are equivalent to the parameters defined by the People service's get method.A Person object or a Collection of Person objects.Example
<os:PeopleRequest key="PagedFriends" userId="@owner" groupId="@friends" startIndex="40" count="20"/>
A request to get the viewer's or owner's profile information. This is equivalent to
using <os:DataRequest> with @method of "people.get", with @userId of either "@viewer" or "@owner".The attributes of this tag are equivalent to the parameters defined by the People service's get method, except that the 'userId' parameter can not be changed from "@viewer" or "@owner".A Person object.Example
<os:ViewerRequest key="Viewer" fields="name, birthday"/>
A request to get activities. This is equivalent to using
<os:DataRequest> with @method of "activities.get".The attributes of this tag are equivalent to the parameters defined by the Activities service's get method, except the 'appId' parameter can not be changed from "@app".A Activity object or a Collection of Activity objects.Example:
<os:ActivitiesRequest key="ViewerActivities" userid="@viewer" startIndex="40" count="20"/>
A request to get activity entries. This is equivalent to using
<os:DataRequest> with @method of "activitystreams.get".The attributes of this tag are equivalent to the parameters defined by the ActivityStreams service's get method, except the 'appId' parameter can not be changed from "@app".A ActivityEntry object or a Collection of ActivityEntry objects.Example:
<os:ActivitiesRequest key="ViewerActivities" userid="@viewer" startIndex="40" count="20"/>
This specification defines a set of tags, known as OpenSocial Markup Language (OSML) tags, that extend the templating capabilities of the Core Gadget Container specification.To use OSML tags, you need to add the "osml" feature to your gadget spec:
<Require feature="osml">
OSML tags are a strict subset of OpenSocial Templating, you can
also use tags if you use the "opensocial-templates" feature:
<Require feature="opensocial-templates">
The reason for separate require features is that templates may not
be supported on all views for all containers, due to processing and/or
latency costs. OSML tags must be supported in all views.An OSML tag is invoked much like an OpenSocial template. It needs to be
surrounded by a <script> tag with @type="text/os-template":
Welcome, <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"><os:Name person="${Viewer}"/></script>!
An implementing Container MUST support at least the tags listed in this
section. A Container MAY support additional tags - an effort will be made to
make such support as consistent as possible across different Containers, and
tags that are deemed useful may be adopted into this specification in the
future.Inline tag to show a person's name. If a profile URL is available it
will be linked to. The tag may display additional container bling (i.e.
more information on hover), but must do so without breaking up text
flow.Attributes:
@person {Object} The person object. (required)Example
<script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup">Welcome, <os:Name person="${Viewer}"/></script>
Tag to show a UI that chooses from a list of people, and set a form
field with the associated value.Attributes:
@group {Object} An array of person objects.@inputName {string} Name of the form input element that will contain
selected id(s). Containers can provide a default here. (optional)@multiple {boolean} Allow multiple selections? (optional)@max {number} Maximum number of people that can be selected.
(optional)@var{string} Name of the top level DataContext variable that is set
with the selected person object (or array of objects). (optional)@onselect {string|function} Client side script function to invoke when
a selection is made. The function will get the selected person object (or
array of objects) as a parameter. (optional)Example
<form action="/top_friends.php" method="POST">
Select your top 8 friends:
<script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup">
<os:PeopleSelector group="${ViewerFriends}" multiple="true" max="8" inputName="top8"/>
</script>
</form>
Block level tag to show information about a person in the style of the
container, usually with an image.Attributes:
@person {string|Object} The person object or DataContext key referring
to a person object. (required)Example
My best friend is:<br/>
<script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"><os:Badge person="${TopFriend}"/></script>
The combination of tags, templates, and proxied content leads to a number
of combinations for developer to use.Here are a few common use cases and how developers might handle them.
This is for informational purposes only - it doesn't extend the proposal,
but hopefully clarifies a few use cases.OpenSocial data will be posted on the developer server and flow control
will be handled on the developers own server, in PHP, JSP, ASP, or the
language of the developer's choice.
Example Gadget XML
<Content href="http://developer.com/canvas" xmlns:os="http://ns.opensocial.org/2008/markup">
<os:PeopleRequest userId="@viewer" groupId="@friends" fields="name,birthday" key="ViewerFriends">
</Content>
Example PHP
<?php
// Some code that pulls POST param into $ViewerFriends here
foreach ($ViewerFriends as $friend) {
if ($friend['birthday']) {
echo "<div>".$friend['name']."'s birthday is".$friend['birthday']"</div>";
}
}
?>
Tags can be inserted into the output and will be processed by the
container or JavaScript on the client side.
Example Gadget XML
<Content href="http://developer.com/canvas" xmlns:os="http://ns.opensocial.org/2008/markup">
<os:PersonRequest userId="@owner" key="Owner"/>
</Content>
Example PHP
<?php // Let the Container know that the Owner object is needed for post-processing ?>
<script type="text/os-data" xmlns:os="http://ns.opensocial.org/2008/markup">
<os:PersonRequest userId="@owner" key="Owner"/>
</script>
<?php
// Some code that pulls POST param into $Owner
echo "High score for <script type=\"text/os-template\" xmlns:os=\"http://ns.opensocial.org/2008/markup\">"
. "<os:Name person=\"${Owner}\"></script> is " . getHighScore($Owner['id']);
?>
PHP Output
<script type="text/os-data" xmlns:os="http://ns.opensocial.org/2008/markup">
<os:PersonRequest userId="@owner" key="Owner"/>
</script>
High score for
<script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"><os:Name person="${Owner}"></script>
is 100
Final Container output after OSML is processed
High score for John Doe is 100
Remove "Non-Tags" sectionRemove Appendix A, Deprecated JavaScript APIIncorporate ActivityStreams 1.0 into OpenSocialKey words for use in RFCs to Indicate Requirement LevelsHarvard UniversityReserved Top Level DNS NamesIBMOpenSocial Core Gadget Specification