RoamAbout Developer

We call applications that run on our platform "Widgelets". A Widgelet that you need to register for each app you want to deploy consists of the following:

a) Your app icon(s)

- One or more icons which would appear on the RoamAbout tray. Click here to see icon guidelines.

b) Widgelet code

- A small javascript code that runs on the client browser and responds to events such as click on app icons to launch the service. For example : currently in most of our apps, a click on the app icon opens an overlay with the corresponding service.

c) Call back URL

- Your web service for the app logic will be hosted at your own servers. You register the call back URL to where the web service is hosted.

Widgelet Code Sample

function App_init() {
                var dinfo = {
                visible:true, 
                 iconIndex: 0,
                        tooltip: "Tool Tip"
                };
                RoamAbout.setAttribute("display", dinfo);
        }

This is the first function that gets called when the widgelet loads. It will decide which icon and its respective tooltip to show in the tray when initialized.

        function App_getDisplayInfo() {
                return RoamAbout.getAttribute("display");
        }

This function is invoked by RA platform to get the apps details that was initialized in the App_init function.

        function App_handleClick() {
RoamAbout.getSelection(function(status, data, context) {
selectionReceived(status, data, context);}, null, 120);
                return 0;
        }

This function gets called whenever the user clicks the app icon in the tray, so here the developer can call any of the platform APIs namely getSelection, getLocation, etc...


        function App_notify(notification) {
                if (notification == RA_notification_overlayClosed)
                        overlayId = null;
                        return 0;
        }

This function is invoked by RA platform whenever the user closes the overlay using close icon or when a page gets refreshed. So it is used to intimate the app widgelet that the overlay is closed.

        function selectionReceived(status, data, context) {
         if (overlayId != null) {
        	RoamAbout.destroyOverlay(function(status, data, context)
        	{overlayDestroyed(status, data, context);}, null,
	        overlayId);
     	 }
	     else {
        	var query = "?keyword="+data;
            RoamAbout.createOverlay(function(status, data, 
            context) {overlayCreated(status, data, 
            context);}, null, 500, 300, query);
    	 }
        }

This is the callback function that is part of getSelection API which is called within App_handleclick function. So after receiving the current selection from RA platform, it will call this function with the selected content in the data parameter.

        
        function overlayCreated(status, data, context) {
                    overlayId = data;
        }

This is the callback function to create the overlay. RA platform sends an overlay id after creating the overlay to this function as data parameter.


        function overlayDestroyed(status, data, context) {
                 overlayId = null;
        }

This is the callback function to destroy the overlay. RA platform call this function after destroying the overlay and then notifies it.