-
Notifications
You must be signed in to change notification settings - Fork 71
Building Your Own OpenSocial Container
The APIs and functionality in this page are very much experimental and are subject to change. The functionality provided by the SBT to build your own OpenSocial container should be considered a preview to developers. Of course we welcome your feedback.
To add the ability to render OpenSocial gadgets in the Playground the team has built an application which leverages Apache Shindig to render OpenSocial gadgets. This is the same technology used within Notes, iNotes and Connections to render gadgets within those applications. The application the team built is extensible in that any web application running on the Domino server can register to also render OpenSocial gadgets.
In order to render Opensocial gadgets you must be using Domino 9.x and have the OpenSocial Component installed on the server. For more information on how to install the OpenSocial Component see this technote. You also need the SDK installed in your Domino server. At the very least you will need to install at least 2 plugins from the SDK on your Domino server, com.ibm.sbt.opensocial.domino and com.ibm.sbt.opensocial.domino.explorer. These can be found in the redist/domino folder in the download from OpenNTF. If you want to render gadgets in an XPages app you will also need to install com.ibm.xsp.opensocial.
If your app consists of OSGi bundles than you will need to add a dependency on com.ibm.sbt.opensocial.domino.
If your app is an XPage app than you should can do a couple of things depending on how your XPage is designed.
- If you have an XPage library that you are using with your XPage app it may make sense to add a dependency on com.ibm.sbt.opensocial.domino to your XPage library.
- If you do not have an XPage library than you can add the XPage library com.ibm.xsp.opensocial.
After you have added a dependency to the correct plugin/library, you need to tell the app about the container(s) you want to register to render gadgets. You can do this in one of two ways. In either case you will need to provide an implementation of com.ibm.sbt.opensocial.domino.container.ContainerExtPoint. You can find more about this interface below.
You can use an Eclipse extension point to register your container. This is good for static containers that will not be changing (like being added and removed dynamically by the application). The name of the extension point is com.ibm.sbt.opensocial.domino.container. Here is an example of how you can use this extension point in your plugin.xml file.
<extension
point="com.ibm.sbt.opensocial.domino.container">
<container
class="com.acme.opensocial.MyContainerExtPoint">
</container>
</extension>The second way to register your container(s) is with the class com.ibm.sbt.opensocial.domino.containerContainerExtPointManager. This class contains two methods called registerContainers and unregisterContainers which allow consumers to register and unregister OpenSocial containers. Both methods take a Java Collection of classes which implement ContainerExtPoint Using ContainerExtPointManager is useful if your application will be dynamically creating and destroying containers.
Your implementation of the ContainerExtPoint interface is the most important piece of code you will write when implementing an OpenSocial Container in your app. This class will tell the OpenSocial implementation on Domino everything about your container. This is likely one of the interfaces that will evolve over time, you have been warned :)
The first and easier method you will need to implement is the getId method. This method needs to return an id for your container which is going to be unique amongst all other containers on the Domino server. This includes other copies of the same app running on the same server.
The getContainerConfig method basically contains configuration for your container. Currently you should not need to modify the configuration so for this reason we have provided a default implementation of OpenSocialContainerConfig (the return type) that you can use. Just create a new implementation of com.ibm.sbt.opensocial.domino.config.DefaultContainerConfig and return that.
These two methods provide OAuth client data for your container to the OpenSocial implementation on Domino. These interfaces also are likely to change in the future, you have been warned :) They must return an instance of com.ibm.sbt.opensocial.domino.oauth.DominoOAuthStore and com.ibm.sbt.opensocial.domino.oauth.DominoOAuth2Store For more information on these interfaces see below.
The DominoOAuthStore interface is used to provide the OpenSocial implementation on Domino information about the OAuth 1.0a clients your container will support. It currently has a single method to retrieve OAuth client information which returns a com.ibm.sbt.opensocial.domino.oauth.DominoOAuthClient. The client contains the OAuth 1.0a consumer key and secret. It is important that you also specify a key type. This can be one of HMAC_SYMMETRIC, RSA_PRIVATE, or PLAINTEXT. Which one you should specify is dependent on the OAuth provider you are using. For convenience there are a couple of subclass of DominoOAuthClient which have certain information filled out for you already.
- com.ibm.sbt.opensocial.domino.oauth.clients.SmartCloudOAuthClient - This class can be used for SmartCloud OAuth 1.0a client information. The only thing you need to do is specify a consumer key and secret from SmartCloud when creating a new instance.
- com.ibm.sbt.opensocial.domino.oauth.clients.DropBoxOAuthClient - This class can be used for DropBox OAuth 1.0a client information. The only thing you need to do is specify a consumer key and secret from DropBox when creating a new instance.
The DominoOAuth2Store is used to retrieve OAuth 2.0 client information for your container.
It currently has a single method to retrieve client information which returns a com.ibm.sbt.opensocial.domino.oauth.DominoOAuth2Client. The DominoOAuth2Client has a few more methods than the DominoOAuth1Client due to the different types of OAuth flows in the 2.0 spec. However almost all OAuth 2.0 providers you will want to connect to from a gadget use a certain configuration.
- Grant Type - Most OAuth 2.0 providers use the CODE grant type. You can set the grant type using the setGrantType method.
- Authorization Header or URL Parameter - OAuth providers will accept the OAuth 2.0 access token in either a authorization header or URL parameter or both. Depending on the OAuth 2.0 provider you are connecting to you will want to set useAuthorizationHeader or useURLParameter accordingly.
- Client ID and Secret - As with OAuth 1.0a you will need an OAuth 2.0 client ID and secret from the OAuth 2.0 provider. Use the appropriate setter methods to set the ID and secret.
As with the DominoOAuthClient, DominoOAuth2Client has a couple of sub-classes which set defaults for common OAuth 2.0 providers.
- com.ibm.sbt.opensocial.domino.oauth.clients.ConnectionsOAuth2Client - This class can be used for Connections OAuth 2.0 client information. You just have to specify the client ID and secret as well as the authorization and token URLs in the constructor. See this wiki page for more information on how to obtain an OAuth 2.0 client ID and secret as well as what the authorization and token URLs are for Connections.
- com.ibm.sbt.opensocial.domino.oauth.clients.GoogleOAuth2Client - This class can be used for Google OAuth 2.0 client information. You just have to specify the client ID and secret. For more information on how to obtain an OAuth 2.0 client ID and secret see Google's developer documentation.
The second part of implementing and OpenSocial container is the client side JavaScript code to render a gadget. The OpenSocial implementation on Domino provides you with all the JavaScript you will need to render gadgets. To load the JavaScript into your page include the following script tag.
<script type="text/javascript" src="sbtos/gadgets/js/container:embedded-experiences:open-views:actions:selection.js?c=1&debug=1&container=mycontainer"></script>This assumes your app is running at the root of the Domino server. Also note the last query parameter, container. The value of the this parameter must match the id of the container you registered with the OpenSocial implementation. (The value of getId in your implementation of ContainerExtPoint.) Next you must get a security token to use with your container.
A security token identifies the current user and container within the OpenSocial implementation on Domino. To get a security token you need to issue a simple GET request to a servlet. Below are the details.
Request GET /sbtos/container/stgen
Query Parameters
| Parameter Name | Description |
|---|---|
| c | The ID of the container. |
| d | The domain of the container. |
| i | The app ID. Any unique ID for your app will do. |
| m | The module ID, should always be 0. |
| u | The app url. |
Response You will get a JSON response back from the servlet which looks like
{
"token":"notes%2F%2Frbaxter-macpro%40renovations%2F__85257BC0006BB913.nsf%2F0%2F2F023E051050A52805257C45007225F6%3FOpenDocument:AbcB929dqKlGc_NPtgFaPlG2ef-XEm39pJ2iey65Fw_sFk6rzW0tiHv6GeDwE2awHI5l8cRGIIu3poshUGijmkHkR2NNnP2EqyefvC5msmqBHFdB1rjs5UeVhl_FaePbbqc6FdBuCN18h0tzf7OMWz4K-pH7osg1eWC3nao6-D_hGp1Sqn8OGo2FrlQ0tHtuO3qRoLVLUWn-n21kuED7RHcVdClMabJhn_lK25Myvm5z_nDUy4KxDV0s7JVKl4MzhU7y2d7C91Qd86iqGPuxJPwKsawehm0mBCU8YXigVWx_46bDi8yKiJB3nTq6WeJCoHZ3qjtD-FmWg0oNNqDcWdpyjEl7YMs9COqEUwpyuRrBPIERt9RtfAa14dLPJuGAE4k_xyleyapuwzcnn96E7IOMwu9785LIWdSsYThXgnv6apaWKcYMxBW5nvq-G2kXA13ZG4M95140i7FTVfIxWwEsdfmAcpkcih81uBrz3rQyeynt_ShIOE8X-TL0WWqlFZYQmA_gMIzBA4EiGZrA-B6x-g8",
"ttl":3600
}The final step is to create a container object in your client side JavaScript and use it to render a gadget. Below is a Dojo Module which constructs the container JavaScript object and uses it to render a gadget.
define(['dojo/_base/declare', 'dojo/_base/lang'],
function(declare, lang) {
return declare([],{
constructor : function(response) {
this.token = response.token;
this.ttl = response.ttl;
var config = {};
config[osapi.container.ContainerConfig.RENDER_DEBUG] = '1';
config[osapi.container.ContainerConfig.GET_CONTAINER_TOKEN] = lang.hitch(this, 'getContainerToken');
this.container = new osapi.container.Container(config);
this.site = this.container.newGadgetSite(document.getElementById('gadgetSite'));
},
getContainerToken : function(result) {
result(this.token, this.ttl);
},
renderGadget : function(url) {
this.container.closeGadget(this.site);
var renderParams = {};
renderParams[osapi.container.RenderParam.HEIGHT] = '100%';
renderParams[osapi.container.RenderParam.WIDTH] = '100%';
this.container.navigateGadget(this.site, url, {},
renderParams);
}
});
});