Adding a New Feature to Shindig

When an OpenSocial gadget includes a "feature" it is generally requesting a particular JavaScript API to be made available by OpenSocial as the gadget starts. In this article, we look at how we would go about creating a new feature for a "learning" API and adding the feature to Shindig and using the feature in a Gadget.

This may not be the most elegant approach to adding our feature, to plug in but it does give you a map of the places in the source code where a new feature can be plugged in. It would be nice if eventually, we could come up with a way to do this exclusively with Guice and a small change to the web.xml file in the gadgets web.xml.

First we move into the feature directory:

cd features/src/main/javascript/features

Create a new directory named * learning* and put three files into it.

gadgets['learning'] = (function() {

    return {
       getContextLabel : function() {
            return 'SI124';
        },

        getContextName : function() {
            return 'Social Computing';
        },

        setOutcome : function(data) {
            alert('setOutcome belongs here');
        }
    };

})();

This creates our client code and defines three methods in the client. For now they are simple stubs to keep life simple.

var tamings___ = tamings___ || [];
tamings___.push(function(imports) {
  ___.grantRead(gadgets.learning, 'getContextLabel');
  ___.grantRead(gadgets.learning, 'getContextName');
  ___.grantRead(gadgets.learning, 'setOutcome');
});

This file indicates that we are making the methods available when the gadget Javascript is served through Caja.

<feature>
  <name>learning</name>
  <dependency>globals</dependency>
  <gadget>
    <script src="learning_client.js"/>
    <script src="taming.js"/>
  </gadget>
  <container>
    <script src="learning_client.js"/>
    <script src="taming.js"/>
  </container>
</feature>

This file names your feature and defines the source files to be loaded to provision the feature.

Then edit the file features.txt and add a line:

features/xmlutil/feature.xml
features/com.google.gadgets.analytics/feature.xml
features/learning/feature.xml

There is a way to update features.txt using a script, but for now, lets just plug in directly.

At this point you need to rebuild Shindig. And you might get syntax errors during the build which you need to fix. The Javascript for features is compiled / processed at mvn time so you may encounter syntax errors causes by your JavaScript.

mvn

once it compiles and installs, start Jetty again

mvn -Prun

And navigate to http://localhost:8080/samplecontainer/samplecontainer.html

You should see the “Social Hello World” gadget. Now lets edit this file:

./target/work/webapp/samplecontainer/examples/SocialHelloWorld.xml

And add two lines:

   <Require feature="osapi"></Require>
   <Require feature="learning"></Require>
   <Require feature="settitle"/></Require>
...
   gadgets.window.setTitle('Social Hello World');
   alert(gadgets.learning.getContextLabel());
     var hellos = new Array('Hello World', 'Hallo Welt', 'Ciao a tutti',
...

The Require tag requests that the container load the new learning feature and then we call the learning feature when the JavaScript starts up in the gadget and you should see the dialog box pop up once you save the SampleHelloworld.xml and do a refresh.

When you change the gadget code you need to make sure that you trill get a fresh copy of the code. Given that different browsers and different browsers settings reload various bits at different time, you may need one or more of these:

• Press Refresh in the Browser
• Press the “Reset All” button
• Clear the browser history if all else fails and your changes don’t seem to be getting reloaded

When you have everything working, you should see the popup loaded as follows:

As a note, since we pugged our alert statement into the Javascript before the Gadget loaded its OpenSocial data and rendered itself, the actual gadget is not yet rendered behind the alert box.

Next up: Adding a Service to osapi and Calling Your New Service From a Feature