-
Notifications
You must be signed in to change notification settings - Fork 70
OpenSocial Gadgets In The Playground
The IBM Social Business Toolkit Playground now contains a page for experimenting with OpenSocial gadgets. OpenSocial gadgets can be used to integrate apps into IBM Notes Social Edition 9.x, IBM iNotes Social Edition 9.x, and IBM Connections 4.x. One of the more common use cases is for embedded experiences in emails and activity entries. Regardless of your use case for building an OpenSocial gadget the OpenSocial gadget section of the Playground can be used as a place to learn and experiment with OpenSocial gadgets. It also gives you a place to start building and testing your own gadgets before trying them out in IBM's Social Business Platform.
The OpenSocial section of the Playground allows you to test a vast majority of features that developers may want to take advantage of while building gadgets for Notes, iNotes, or Connections. Below is a list of supported OpenSocial features you can use within the Playground.
- gadgets.io.makeRequest - You may use gadgets.io.makeRequest to make API calls.
- Embedded Experiences - You can test and develop embedded experience gadgets from within the Playground.
- OAuth 1.0a and 2.0 - You can use OAuth 1.0a or 2.0 to make API requests
- Actions - You can test any action contributions you gadget makes within the Playground.
- Selection - You can test any selection listeners your gadget adds from within the Playground.
- Open Views - You can test any open views API calls your gadget makes from within the Playground.
- Gadget Preferences - If you gadget uses preferences you can edit and manipulate them from within the Playground.
The key to embedded experience gadgets is the embedded experiences data model. Since in the Playground we don't have an email or activity entry containing the data model we have provided an editor allowing you to manipulate the data model. In the case of the Playground the only thing you need to manipulate is the context property from the data model (obviously the Playground already knows the gadget URL). To edit the data model select the JSON Payload tab in the editors. Then create a JSON object with a context property. For example
{
"context" : {
"foo" : "bar"
}
}Actions contributed from gadgets will be surfaces in the gadgets menu. Click the button in the gadget toolbar to open the drop down menu. Actions contributed by your gadget can be found under the Actions menu in the drop down. If your gadget contributes actions to be invoked on specific type than the actions can be found as sub-menus in the Selections menu. For example if your gadget contributes an action that should be invoked on an person object than you will find your action under the opensocial.Person menu.
If your gadget listens for selection events you can fire those events from the Selection menu in the gadget toolbar drop down. Just select the type of object you want published and the container will file a selection event of that type.
The open views feature allows you to open gadgets and URLs in other parts of the container. However the Playground does not support all the different types specified in the OpenSocial specification. In the Playground we always open the gadget or URL in a modal dialog. However the real-estate of the model dialog is adjusted based on the location you want to open. For example if you want to open a gadget in the sidebar the modal dialog will have a narrow width and nearly take up the entire height to simulate the amount of real estate in a sidebar.
Any preferences that the gadget has can be modified by opening the drop down menu in the gadget toolbar and clicking the Preferences link. Preferences are not persisted in the Playground, for example once you select a different gadget the gadget preferences will be lost.
Before you install the Playground on Domino 9.x you must have the Domino OpenSocial Component installed on your Domino server. For more information on how to install the OpenSocial Component on your Domino server see this technote. After the OpenSocial Component is installed you can then install the Playground as you normally would after downloading the SDK from OpenNTF.
If you have a fresh version of the IBM Social Business Toolkit Playground and there are no gadgets in the OpenSocial section, you can import sample gadgets into the Playground. There are two locations to import gadgets from.
- The OpenSocial Explorer project.
- The SDK sample app.
To import the gadgets follow the below steps.
- Log into the Playground with an ID that has manager access.
- On the left hand side click the Import OpenSocial Gadgets link.
- Click the New Import Source... button at the top of the page.
- In the Source Name field of the Import Source dialog type OpenSocial Explorer.
- In the Source Type drop down select GitHub Repository.
- In the Location field enter https://api.github.com/repos/OpenSocial/explorer/contents/gadget-specs/src/main/specs.
- In the User field enter your GitHub user name.
- In the password field enter your GitHub password.
- Click Save to save the import source.
- Click the New Import Source... button again.
- In the Source Name field of the Import Source dialog type SBT SDK.
- In the Source Type drop down select GitHub Repository.
- In the Location field enter https://api.github.com/repos/OpenNTF/SocialSDK/contents/samples/j2ee/snippets/com.ibm.sbt.sample.web/src/main/webapp/samples/gadgets.
- In the User field enter your GitHub user name.
- In the password field enter your GitHub password.
- Click Save to save the import source.
You should not have both gadget import sources in the view. For each source click the Import from Source link to begin the import process. While the import is in progress you will see a status message at the top of the page telling you which gadgets are being imported and then a success message once the import completes. Now if you go back to the OpenSocial gadgets section of the Playground you should see several gadgets in the tree on the left hand side.
The OpenSocial container in the Playground will take advantage of the OAuth information for the different endpoints configured in your current environment. This means as you switch environments within the OpenSocial section of the Playground the gadgets will use the OAuth information setup for whatever environment you have select. This is useful for testing against different development and production environments or even testing against different versions of products. However for OAuth 2.0 you will need to create additional keys and secrets in Connections for the gadgets to use. The gadgets cannot use the keys and secrets you may have already configured for the other parts of the Playground due to a different OAuth 2.0 callback URL.
To configure OAuth keys and secrets for the different endpoints in a given environment
- Login with a user ID that has manager access to the Playground.
- Click the Manage link at the top of the page.
- Click Runtime Environments in the outline on the left.
- Select the environment you want to configure.
When registering for OAuth 1.0a or 2.0 keys with various providers you may be asked to provide an OAuth callback URL. The OAuth callback URLs used for the Playground are listed below.
- OAuth 1.0a Callback: http://<Domino server host name>/sbtos/gadgets/oauthcallback
- OAuth 2.0 Callback: http://<Domino server host name>/sbtos/gadgets/oauth2callback
In the IBM Connections tab of the environment you will notice there are 3 fields specific to gadgets.
- OpenSocial Gadget OAuth2 Service Name
- OpenSocial Gadget OAuth2 - Consumer Key
- OpenSocial Gadget OAuth2 - Consumer Secret
If you do not change the OAuth service name of the gadgets you import into the Playground you do not need to fill our the OpenSocial Gadget OAuth2 Service Name field. However if you do change the service name in the sample gadgets than you will need to specify that service name in this field. Enter the consumer key and secret you generated to use for gadgets in the other two fields. Again, this cannot be the same consumer key and secret you use for the other samples in the Playground.
For more information on registering for an OAuth 2.0 key and secret in Connections refer to the Connections documentation. If you are using the IBM Collaboration Quick Start For Social Business there is a script you can run called generateOAuthKey.sh that will do this for you.
Gadgets using the IBM SmartCloud APIs can only use OAuth 1.0a due to limitations with the SmartCloud OAuth 2.0 provider. You will notice there are not separate OAuth 1.0a consumer key and secret fields for gadgets. This is because with OAuth 1.0a we are able to reuse the same OAuth 1.0a key and secret you use for the other samples in the Playground. The only field that is specific to gadgets in this section is the OAuth Service Name For OpenSocial Gadgets. Just like in the Connections section, if you do not change the OAuth service name in the sample gadgets than you can leave this field blank. However if you do change it than specify the new service name in this field.
Gadgets using the DropBox APIs use OAuth 1.0a. You will notice there are not separate OAuth 1.0a consumer key and secret fields for gadgets. This is because with OAuth 1.0a we are able to reuse the same OAuth 1.0a key and secret you use for the other samples in the Playground. The only field that is specific to gadgets in this section is the OpenSocial Gadgets OAuth 1.0a Service Name. You may leave this field blank unless you change the service name used by the DropBox gadgets.
To create OAuth 1.0a keys and secrets see the DropBox Developer Page.
Gadgets using Google APIs use OAuth 2.0. There are 3 fields in the Google section that are specific to gadgets.
- OpenSocial Gadgets OAuth2 Service Name
- Consumer Key For OpenSocial Gadgets
- Consumer Secret For OpenSocial Gadgets
You may leave the service name field blank if you do not change the service name used the sample gadgets using the Google APIs. Enter your Google key and secret you generated after registering the app in the Google Developer Console. For more information on how to get an OAuth 2.0 key and secret from Google see their developer documentation. In addition you must also enable the app to use the contacts APIs.