Using the OpenSocial API

Version 6

    Overview

     

    Apps have access to data in a Jive community — including data about people, content, places and activity. Your app gets this data through a combination of the OpenSocial API and the Jive Core API. For more on the Jive Core API, see the Using the Jive Core API tutorial. Both of these APIs enable you to use a simple JavaScript interface to interact with the Jive community data.

     

    This tutorial explores the basics of the OpenSocial API and how you can use it with Jive. The OpenSocial API uses a more general terminology that works across different OpenSocial containers, making it easier to take an app written for another OpenSocial container and use it in Jive. You can look at the OpenSocial.org standard way of designing apps as a foundation for building Jive apps. This tutorial tells you which of the OpenSocial features are implemented for use in Jive.

     

    Note: Jive uses the Shindig OpenSocial Container from the Apache Foundation to make OpenSocial available for communicating with a Jive community.

     

    Before You Begin

     

     

    Step 1: Get your friends!

     

    The purpose of this example is to illustrate how easy it is to get information about your social graph simply by using the standard APIs.

     

    <?xml version="1.0" encoding="UTF-8" ?>
    <Module>
        <ModulePrefs title="Simple Social Hello World">
        <Require feature="opensocial-1.0"/>
        <Require feature="osapi"/>
        <Require feature="dynamic-height"/>
        <Require feature="minimessage"/>
    </ModulePrefs>
    <UserPref name="work_location" display_name="Where do you work" datatype="string" default_value="" required="false" />
    <UserPref name="participant" display_name="Participating in challenge" datatype="bool" default_value="" required="false" />
    <UserPref name="defaultModeOfTransportation" display_name="How do you get to work?" datatype="enum" default_value="" required="false">
          <EnumValue value="bicycle" display_value="Bicycle (15 points)" />
          <EnumValue value="bus" display_value="Bus (10 points)" />
          <EnumValue value="car" display_value="Car (1 points)" />
          <EnumValue value="carpool" display_value="Carpool (5 points)" />
          <EnumValue value="walk" display_value="Walk (20 points)" />
          <EnumValue value="train" display_value="Train (10 points)" />
    </UserPref>
    <Content type="html" view="home,canvas">
      <![CDATA[
          <script  type="text/javascript">
          function init() {
            osapi.people.getViewer().execute(function(viewerData) {
               if (!viewerData.error) {
                  var viewerDiv = document.getElementById('current_user_id'),
                      viewerThumbnailImg = document.getElementById('viewerThumbnailImg');
                  viewerDiv.innerHTML += viewerData.displayName;
                  viewerThumbnailImg.attributes.getNamedItem("src").nodeValue=viewerData.thumbnailUrl;
                  gadgets.window.adjustHeight();
               };
            });

            osapi.people.getViewerFriends().execute(function(viewerFriends) {
               if (!viewerFriends.error){
                var resultDiv = document.getElementById('result');
                resultDiv.innerHTML = viewerFriends.list.length;
               }
            });

            var workLocationSpan = document.getElementById('workLocationSpan'),
                prefs = new gadgets.Prefs(),
                yourWorkLocation = prefs.getString("work_location");
                workLocationSpan.innerHTML = yourWorkLocation;

          }

          function postActivity(){
            var params = {activity: {title:"Hello Jive!",
                                  body:"Posting to the stream is easy!"}
                      };
             osapi.activities.create(params).execute(myCallback);
          }

          function myCallback(){
            var msg = new gadgets.MiniMessage(__MODULE_ID__);
                msg.createDismissibleMessage("You just posted an activity!");
                gadgets.window.adjustHeight();
          }


          gadgets.util.registerOnLoadHandler(init);
          </script>

          <p>Your display name is: <span id="current_user_id"></span></p>
          <p>Your thumbnail is: <img id="viewerThumbnailImg" src=""></img></p>
          <p>You have <span id='result'></span> friends.</p>
          <p>You work at: <span id='workLocationSpan'></span></p>
          <p><input type="button" value="Post Activity" onclick="postActivity(); return true;"/></p>

          ]]>
    </Content>
    </Module>

     

     

    This application makes two requests to the Jive instance, one to retrieve information about the viewer, osapi.people.getViewer(), and one to get the viewer's friends, osapi.people.getViewerFriends().


    Note: Those already familiar with OpenSocial will recognize that there are optimizations, e.g. Data Pipelining, that can be utilized that avoid making multiple requests to the server.


    There are a few new parts to the gadget that are worth pointing out. First, note that we've added three new features to the application's gadget definition file. These tell the Jive instance to include the necessary JavaScript libraries from OpenSocial. Minimessage is a library that's used to display a small text box within the gadget. It will be used when we post an activity later in the example.


    <Require feature="opensocial-1.0"/>
    <Require feature="osapi"/>
    <Require feature="minimessage"/>


    The next piece of code to look at is the hook that causes our init function to triggered when the page is loaded. This is one of the common "container" APIs that you will use when developing your applications.

     

    gadgets.util.registerOnLoadHandler(init);

     

    The final two pieces of code are the actual OSAPI calls. These are defined by the OpenSocial standard and will retrieve information about the currently logged in user. In OpenSocial, this person is the "viewer".

     

    osapi.people.getViewer().execute(function(viewerData)
    ...
    osapi.people.getViewerFriends().execute(function(viewerFriends)


    The features available using OpenSocial to access Jive data include Person (osapi.people), AppData (osapi.appdata), Preferences (gadget.Prefs), and Activities (osapi.activity). To use these services, you can use the OpenSocial Gadget Specification to find the methods and parameters you need to specify for interacting with the Jive community.


    ServiceDescription
    AppData

    This service stores key/values for a user to store information at the container. Note: Jive provides an extension to AppData that allows you to store MediaItems. Please be aware that this is not part of the OpenSocial standard and therefore, will not be interoperable with other OpenSocial containers.

    Person

    This service provides access to information about people in the Jive Community. For example, look at the class Opensocial.Person to see the fields we use for a person, for example, Jive uses opensocial.Person.Field.ABOUT_ME, but ignores opensocial.Person.Field.FOOD.

    Preferences

    Provides user and system preferences.

    • System settings (apps preferences): Allows admins to save data related to an app that all users can read. This enables configuring of global app settings. This is a Jive specific extension and is not part of the OpenSocial specification.
    • User preferences: Jive supports strings, booleans and Single selection (enums) as preference types. We provide a default UI to show the preferences, or you can provide a custom UI. When using a  custom UI, you need to use scripts to close the preferences dialog. For more on this, see Default User Preferences or Custom User Preferences UI below.
    Activities

    Jive supports the ability to write activities using osapi.activities.create(). Retrieving activities using osapi.activities.get() is not yet supported. However, to retrieve activities, you can use Jive Core API. For more on this, see the Jive Core API tutorial.

     

    Step 2: Working with User Preferences

     

    Often, when you are building a social application, you will want to capture information from the user that can be used in the gadget. One mechanism to do this in OpenSocial is User Preferences, or user prefs for short.. Jive makes it easy to leverage this capability by providing a default editor built into the container. User prefs are added right after the Module Preferences section and before the Content Type.


    Here's an example of how user prefs are defined:

     

    <?xml version="1.0" encoding="UTF-8" ?>

    <Module>

        <ModulePrefs title="Simple Social Hello World">

        <Require feature="opensocial-1.0"/>

        <Require feature="osapi"/>

    </ModulePrefs>

    <UserPref name="work_location" display_name="Where do you work" datatype="string" default_value="" required="false" />

    <UserPref name="participant" display_name="Participating in challenge" datatype="bool" default_value="" required="false" />

    <UserPref name="defaultModeOfTransportation" display_name="How do you get to work?" datatype="enum" default_value="" required="false">

          <EnumValue value="bicycle" display_value="Bicycle (15 points)" />

          <EnumValue value="bus" display_value="Bus (10 points)" />

          <EnumValue value="car" display_value="Car (1 points)" />

          <EnumValue value="carpool" display_value="Carpool (5 points)" />

          <EnumValue value="walk" display_value="Walk (20 points)" />

          <EnumValue value="train" display_value="Train (10 points)" />

    </UserPref>

    <Content type="html">

     

    When you add user prefs, Jive automatically adds a menu option to the application's settings UI.

     

    appSettings.png

     

    When you select the "App Settings" option, the default user prefs dialog box will open. A default UI control will be created based on the type of the user pref, e.g. text box for string, check box for booleans.


    Here's an example of what it looks like:


    appPrefs.png

     

    Step 3: Posting an Activity

     

    OpenSocial provides a simple API to post an activity to a user's stream. This is also accomplished using the OSAPI.

    function postActivity(){

            var params = {userId: "@viewer",

                       groupId: "@self",

                       activity: {title:"Hello Jive",

                                  url:"http://community.jivesoftware.com/docs/DOC-65828",

                                  body:"This is my activity"}

                      };

     

                osapi.activities.create(params).execute(myCallback);

          }

    Step 4: Understanding Jive Extensions

     

    Jive provides several extensions that accomodate many of the common use cases that encountered when building a social application.  Although these help the developer quickly and easily build a social application, they are not part of the OpenSocial standard. Where possible, Jive has taken care to ensure they conform to its programming model.

     

    The following tables identify extensions, features, services, and views that Jive provides beyond the OpenSocial Services. Use the View table to customize how your app appears to users, and use the Feature table to see how you can enhance your app.

     

    Views

     

    When developing your application, there may be scenarios where you will need more real estate within the browser's window. It's a common pattern, for example, to have one representation of your application that's initially displayed to the user, which, because it's often rendered alongside other applications, is confined to a small area within the browser. The user can then "maximize" your application, essentially getting another representation of your app, that, because more screen real estate is available, can provide more function to the user. OpenSocial calls these different representations of your application "views", and several named views are defined as part of the specification.

     

    Jive has extended the specification to make it easier for your users to interact with your application. Specifically, there are custom views for administration, preferences, and about information. The following table outlines different ways you can adjust how users view your app:

     

    ViewDescription
    home

    Shows a small format, rendered in dashboard alongside other apps.

    canvas

    Shows a full-screen view, rendered in the entire screen below main Jive navigation.

    user-prefs

    If present, this view renders a custom preferences UI instead of the standard generated UI

    system-settings

    If present, this view renders a custom admin preferences UI.

    about

    An information page that describes the app and is presented in a small format. Attributes that you can add to the XML include: title, author, author_affiliation, description, MediumIcon (URL, icon of 48x48)

     

    Note: it is possible to have named "subviews". For example, if you application has logic that requires specialized "home" views, you can create a content section with a view named "home.mySpecialHomeView". More information about views can be found in the OpenSocial specification.

     

    Features

     

    The following tables identify extensions, features, services, and views that Jive provides beyond the OpenSocial Services:


    FeatureDescription
    jquery-1.4.2

    The JQuery 1.4.2  library. Simplifies JavaScript development. Used by the Jive-connects  and Jive-core features.

    jive-namespace

    Internal. Adds the jive.namespace() function for creating additional namespaces under jive.*

    jive-connects-v1

    The JavaScript API for Jive Connects. Dependencies: jquery-1.4.2,  jive-namespace

    jive-core-v2

    The JavaScript  API for Jive Core. Dependencies: jquery-1.4.2, jive-namespace

    jive-custom-settings-1.0.0An extension used to close the popover, refresh the app and show a success message. This is typically uses with OpenSocial's setprefs feature.

    jive-storage

    The JavaScript API for binary storage. Adds functionality for uploading binary files via a dialog box.

    You can use the jive-storage extension, which extends JavaScript API for binary storage by specifying  <Require feature="jive-storage-1.0.0"/> and then adding the functionality for uploading binary files using a dialog box.