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.

[dr34mc0d3r]

im new to ning. I read this article and i dont understand - "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."

is there a ning documentation for me to read?

[Vaibhav Thukral]

check out: http://docs.ning.com/page/page/show?id=492524%3APage%3A2131

I'm still unable to get this to work...

[Peter Daams]

The current sample code doesn't work.

To make it work add this to the start of the script tag:

_IG_RegisterOnloadHandler(sayHello);

and remove the opensocial.registerOnloadHandler(sayHello); line.

[Diego]

Oops! Sorry about that -- we'll fix this asap. In the meantime, Peter's answer is correct.

d

[Luc]

Where is "the URL box of your profile page,"

I've got the XML file ready for testing but I'm not sure where to post it.

Thanks

[Thomas David Baker]

Hi Luc,

There's two questions here, I think. Correct me if I've misunderstood.

The first is where can you put the XML file for your gadget. This can be on any website you have access to. If you have web hosting with an ISP they probably provide an ftp upload facility. If you are the owner of a Ning network with decentralized code you can upload it using sftp or via the "Edit Your Source Code" link on the Manage tab. If you don't have anywhere like this to upload to you could create a Ning network especially to hold your gadgets, or sign up for some free web hosting.

The second question is how do you input this URL so that the gadget actually shows up.

If you're on a network that has enabled Gadgets then you can visit your profile by clicking the "My Profile" tab. The Gadgets box will appear under the Latest Activity box in the center column. Click on Edit in the title bar of that box to reveal the area to input the URL.

If you are the network creator and want to enable Gadgets, click on the Manage tab and then the link to the Features page. On there, drag Gadgets to the location you want and click Save. When you next visit the homepage you will see the Gadgets box. Click on Edit in the title bar and you will the area to input the URL.

Let us know if you get stuck!

Thanks,

Tom

[Luc]

Thanks Tom, that did it!

[Spike Washburn]

Your API reference link in this article is returning a 404.

[Diego]

Thanks Spike - fixed that.

[Thezza]

Hi - we have successfully created a gadget that works on Orkut, now we would like to test it on Ning. We have followed the instructions and our gadget shows up, however it seems that UserPref's are not supported? How would a user be able to edit the User Preferences?

[Thomas David Baker]

Hi Thezza,

What's the URL for your app? Let me know and I'll work out what's happening there.

Thanks!

Tom

[Thezza]

Hi Tom, thanks for your help! Here's the URL: http://arsenalnation.ning.com/opensocial/standings.xml. We have tested this on Orkut and it works fine (well, most of the time), but it seems that the UserPref params are not recognized on Ning, not even the default setting (that's why it displays 'widget error'). Not sure what we are missing?