Representation of an activity.

Note: Activities are currently not supported by MySpace.

Activities are rendered with a title and an optional activity body.

You may set the title and body directly as strings when calling opensocial.createActivity.

However, it is usually beneficial to create activities using Activity Templates for the title and body. Activity Templates support:

• Internationalization
• Replacement variables in the message
• Activity Summaries, which are message variations used to summarize repeated activities that share something in common.

Activity Templates are defined as messages in the gadget specification. To define messages, you create and reference message bundle XML files for each locale you support.

Example module spec in gadget XML:

<ModulePrefs title="ListenToThis">
  <Locale messages="http://www.listentostuff.com/messages.xml"/>
  <Locale lang="de" messages="http://www.listentostuff.com/messages-DE.xml"/>
</ModulePrefs>

Example message bundle:

<messagebundle>
 <msg name="LISTEN_TO_THIS_SONG">
    ${Subject.DisplayName} told ${Owner.DisplayName} to
    listen to a song!
 </msg>
</messagebundle>

You can set custom key/value string pairs when posting an activity. These values will be used for variable substitution in the templates.

Example JS call:

  var owner = ...;
  var viewer = ...;
  var activity = opensocial.newActivity('LISTEN_TO_THIS_SONG',
   {Song: 'Do That There - (Young Einstein hoo-hoo mix)',
    Artist: 'Lyrics Born', Subject: viewer, Owner: owner})

Associated message:

<msg name="LISTEN_TO_THIS_SONG">
    ${Subject.DisplayName} told ${Owner.DisplayName} to listen
    to ${Song} by ${Artist}
</msg>

People can also be set as values in key/value pairs when posting an activity. You can then reference the following fields on a person:

• ${Person.DisplayName} The person's name
• ${Person.Id} The user ID of the person
• ${Person.ProfileUrl} The profile URL of the person
• ${Person} This will show the display name, but containers may optionally provide special formatting, such as showing the name as a link

Users will have many activities in their activity streams, and containers will not show every activity that is visible to a user. To help display large numbers of activities, containers will summarize a list of activities from a given source to a single entry.

You can provide Activity Summaries to customize the text shown when multiple activities are summarized. If no customization is provided, a container may ignore your activities altogether or provide default text such as "Bob changed his status message + 20 other events like this."

• Activity Summaries will always summarize around a specific key in a key/value pair. This is so that the summary can say something concrete (this is clearer in the example below).
• Other variables will have synthetic "Count" variables created with the total number of items summarized.
• Message ID of the summary is the message ID of the main template + ":" + the data key

Example summaries:

<messagebundle>
  <msg name="LISTEN_TO_THIS_SONG:Artist">
    ${Subject.Count} of your friends have suggested listening to songs
    by ${Artist}!
  </msg>
  <msg name="LISTEN_TO_THIS_SONG:Song">
    ${Subject.Count} of your friends have suggested listening to ${Song}
  !</msg>
  <msg name="LISTEN_TO_THIS_SONG:Subject">
   ${Subject.DisplayName} has recommended ${Song.Count} songs to you.
  </msg>
</messagebundle>

Activity Templates may only have the following HTML tags: <b>, <i>, <a>, <span>. The container also has the option to strip out these tags when rendering the activity.

See also: opensocial.newActivity(), opensocial.requestCreateActivity()

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();
  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()

See also: DataRequest

If your gadget just wants to display how much of a smoker someone is, it can simply use:

html = "This person smokes: " + person.getField('smoker').getValue();

This value field will be correctly set up by the container. This is a place where the container can even localize the value for the gadget so that it always shows the right thing.

If your gadget wants to have some logic around the smoker field it can use:

if (person.getField('smoker').getKey() != "NO") { //gadget logic here }

Note: The key may be null if the person's smoker field cannot be coerced into one of the standard enum types. The value, on the other hand, is never null.

See also: opensocial.getEnvironment(),

See also: opensocial.newMessage(), opensocial.requestSendMessage()