How to write an OpenSocial Gadget, Part 1: Hello World!

[Diego]

An OpenSocial Gadget is simply a small HTML+Javascript application that runs on a site, or "container", that supports the OpenSocial JavaScript API. Any Ning network is such a container.

With Ning's support for OpenSocial, and this guide, you can try your hand at creating OpenSocial Gadgets that can then run with relatively minor changes (or unchanged) on other containers.

API Scope

As of version 0.5, there are three primary areas of functionality in the OpenSocial API:

• People and Friends
• Persistence
• Activities

As long as your Gadget uses only these functions from the API, it should run unchanged across all conformant containers. Additionally, some containers such as Ning may implement some key functions supported by other containers, such as iGoogle or Orkut, to increase compatibility and simplify deployment for application developers.

For detailed information, see the API Reference.

Hello World!

Here is one of the most basic Gadgets you can write:

<?xml version="1.0" encoding="UTF-8" ?><Module><ModulePrefs title="Hello World Example">   <Require feature="opensocial-0.5"/>
 </ModulePrefs>

 <Content type="html">

 <![CDATA[

 <script type="text/javascript">

  function sayHello() {

    document.getElementById('message').innerHTML = 'Hello World!';

  };

  opensocial.registerOnloadHandler(sayHello);

  </script>

  <div id="message"> </div>

  ]]>

  </Content>

</Module>

This example is a basic 'Hello World!' that goes beyond simply outputting text, to use an onLoadHandler call, in the form of opensocial.registerOnloadHandler(sayHello); which will be called as soon as the page loads. When this happens the sayHello function will be called, retrieving the DIV and setting the text to the appropriate value.

A key element in this example is the use of <Require feature="opensocial-0.5"/> as a parameter of the module declaration. This specifies the release of opensocial required by the module. Containers may or may not implement all possible versions of the opensocial API, and when they don't the user will see an error.

Inserting the Gadget into your profile for testing

Testing is easy -- you can simply save your gadget as a file in your network (through SFTP), in a (new) directory opensocial, with the name for example helloworld.xml. Then you can reference it by typing http://networkname.ning.com/opensocial/helloworld.xml into the URL box of your profile page, and presto! Your first opensocial gadget should be up and running.

[Thomas David Baker]

Hi Thezza,

You've bumped up against some limitations of our early version fo the container I'm afraid. We have concentrated on support for <Content type="html"> initially. More support for <Content type="url"> and UserPref coming soon!

Thanks,

Tom

[Thezza]

OK, thank you. It would be great if you could post a reply on this thread once these features are implemented.

[Jeremy Suriel]

Creating new activity question... Just testing writing a new activity and noticed that the google code samples for creating a new activity do not work on ning. specifically, i noticed that the opensocial.newStream function is undefined. Is this something missing, am i missing something, or could you provide an example of how a new activity should be created within ning? for ease of reference, here is the excerpt from the google code developers guide:

function writeActivity() {
var streamTitle = 'Sample code for reading and writing activity stream';
var stream_params = {'url': 'http://samplestream.com' };
var stream = opensocial.newStream('', streamTitle, stream_params);

var title = _gel('title').value;
var link = _gel('link').value;
var activity_params = {'url' : link}
var activity = opensocial.newActivity(stream, title, activity_params)
opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH, getActivities);
}

[Thomas David Baker]

Hi Jeremy,

Thanks for trying out the container. This is still a beta implementation and we haven't added support for the activity stream stuff yet. It's definitely on the list to do very soon, though.

Thanks,

Tom

[Jeremy Suriel]

Hey Tom,

Got it. Thanks for the quick reply.

[Thomas David Baker]

Just to be 100% clear, we do support reading from the stream just not writing to it.

Thanks!

Tom

[Arnaud]

Hi,

This is a nice example. However, the Gadget has to be manually added by a user on his own page. Is there a way the admin of the social network can automatically add a Gadget or anything so it is always present on a user page ?

Sorry if my question is dumb, but i'm new on this...

Thanks,
Arnaud

[Thomas David Baker]

Hi Arnaud!

Currently the Network Creator can add a gadget to the homepage and members can add gadgets to their profiles. We are looking at expanding this range of options fairly soon.

Thanks!

Tom

[Arnaud]

Hi Tom and thank you,

So, do you mean my request is not possible? If not, i thought about turning this gadget into a new feature. Would this make it possible? How? The purpose is to have a mandatory box on every profile that cannot be removed.

Thanks,
Arnaud

[Thomas David Baker]

Hi Arnaud,

With the current configuration it is not possible. If you have access to the source code of your network and you change it there, that would work. You would need to look at iframeWrapper.php and perhaps hardcode the gadget URL there.

Thanks!

Tom

[Arnaud]

Hi again Tom,

I have access to the source code. But i'm not sure about the iframeWrapper. Anyway, hardcoding is the idea...I need by code to be present only on the MY PAGE section. So, is there any instruction that tells if you are on the MY PAGE section or not? if not, any file that is only used by the MY PAGE section.
Also, where can I find the definition of the _user and owner objects? I mean properties + methods.

Thanks,
Arnaud

[Absynt]

Hi Tom

I have problems to go use sftp with ning
I tried sftp [e-mail]
and then giving my passwd : don't work
I tried sftp [e-mail]
and then giving my passwd : don't work

Finally I use the Edit code system.
I create a file named hello.xml and containing your code

I gave as url : http://absynt.ning.com/hello.xml
And it works.

Any idea where is my mistake using sftp ?

Andre