[Download] | [Documentation Home] | [Release Note]

Gadget Authoring

Authoring a gadget is a simple process with a short learning curve. With some amount of xml, HTML and JavaScript knowledge a normal user can start writing gadgets with ease.

What is a Gadget

As mentioned above a gadget is a combination of HTML, XML and Javascript. It can contain many dynamic behaviors and those are simply implemented with Javascript code. The Gadget API provides building blocks to create comprehensive gadgets with greater value.

Hello World Gadget

A HelloWorld gadget code snippet is given below.

                <?xml version="1.0" encoding="UTF-8" ?>
                <Module>
                <ModulePrefs title="hello world example"/>
                <Content type="html">
                <![CDATA[
                Hello, world!
                ]]>
                </Content>
                </Module>
            

Notable Syntax in HelloWorld Code

  • Gadgets are specified in XML. The first line is the standard way to start an XML file. This must be the first line in the file.
  • The <Module> tag indicates that this XML file contains a gadget.
  • The <ModulePrefs> tag contains information about the gadget such as its title, description, author, and other optional features.
  • The line <Content type="html"> indicates that the gadget's content type is HTML.
  • <![CDATA[ ...insert HTML here... ]]> is used to enclose HTML when a gadget's content type is html. It tells the gadget parser that the text within the CDATA section should not be treated as XML. The CDATA section typically contains HTML and JavaScript.
  • </Content> signifies the end of the Content section.
  • </Module> signifies the end of the gadget definition.

SOAP Request Gadget

This gadget allows a gadget author to invoke a SOAP Web Service, without cross domain restrictions from his gadget's Javasript. The SOAP web service need to be startup before deploying such a gadget in gadget server. A SOAPRequest gadget code snippet is given below.
                <?xml version="1.0" encoding="UTF-8" ?>
                <Module>
                <ModulePrefs title="hello world example">
		<Require feature="wso2"/>
	        </ModulePrefs> 
                <Content type="html">
                <![CDATA[
                <div id=response-disp></div>
      
          	<script>
		 function doSOAPCall(){
		       var endpoint = "http://localhost:9763/services/HelloService";
		       var payload = ' <p:greet xmlns:p="http://www.wso2.org/types"> <name>SOAP Request </name> </p:greet>';
		       var operation = "urn:greet";
		      
		       document.getElementById("response-disp").innerHTML = wso2.io.makeSOAPRequest(endpoint, operation, payload);
		    } 
           
            	gadgets.util.registerOnLoadHandler(doSOAPCall);
            	</script> 
                ]]>
                </Content>
                </Module>
            

Notable Syntax in HelloWorld Code

  • Gadgets are specified in XML. The first line is the standard way to start an XML file. This must be the first line in the file.
  • The <Module> tag indicates that this XML file contains a gadget.
  • The <ModulePrefs> tag contains information about the gadget such as its title, description, author, and other optional features.
  • The <Require feature="wso2" > is used to inform the gadget container that this gadget needs an extra feature to invoke function. This type of features are pre-written Javascript code, which will be loaded to the gadget on demand by the gadget container.In this code,it'll required to import the feature 'wso2', inorder to make SOAP request from the gadget.
  • The line <Content type="html"> indicates that the gadget's content type is HTML.
  • <![CDATA[ ...insert HTML here... ]]> is used to enclose HTML when a gadget's content type is html. It tells the gadget parser that the text within the CDATA section should not be treated as XML. The CDATA section typically contains HTML and JavaScript.
  • JavaScript 'doSOAPCall' function defines three parameters required to invoke makeSOAPRequest function such as endpoint(Url of SOAP service ),payload and operation.Then by using "wso2.io.makeSOAPRequest(endpoint, operation, payload)" method,SOAP service end point is invoked.Finally the response from the invoked SOAP service end point will be displayed inside the gadget.
  • </Content> signifies the end of the Content section.
  • </Module> signifies the end of the gadget definition.

OAuth Support

OAuth support for WSO2 gadgets facilitates allowing signed-in users to access private data from a hosting service to a consumer gadget. Simply this feature allows to communicate with gadget users' services using the OAuth protocol.

You can get more information about writing an OAuth gadget from here.

Following example shows how the OAuth support works for gadgets in WSO2 gadget server.First create a new consumer from Admin console and add OAuth information such as consumer service,consumer key,etc.



OAuth



Then deploy the implemented consumer gadget in the gadget repository and add it in to the portal.Following shows such a consumer gadget which retrieves portal signed-in user's google account contacts data through the Google Data API .



OAuthGadget



After click on the link displayed as 'Personalize this gadget' in the gadget it will direct to the following page.



OAuthGadgetNext



To retrieve back user's personal contacts data to the gadget you have to click on 'Grant Access' button.



OAuthGadgetNext



Then the consumer gadget displays as follow.Click on the displayed link on it.



OAuthGadgetNext



Finally the google account contact details of signed-in user displays in the consumer gadget.



OAuthGadgetNext

Inter Gadget Communication

This feature provides the communication between gadgets while running in the portal.

Inter Gadget Communication has facilitated with the help of publisher and subscriber gadgets.You can find more information about inter gadget communication here.

Gadget Specification

The Google Gadgets Specification describes how the gadgets should be written and rendered in a gadget container. The WSO2 Gadget server is fully compliant with Google Gadget Specification which is now adopted in sites such as Hi5 and Orkut. You can find more information about the specification here

Gadget API

The Gadget API is the same as the Google Gadget API, hence users and developers get the advantage of reusing any Google gadget in the WSO2 Gadget server. When authoring new gadgets for the gadget server it is advised to refer to the new API (gadgets.*). However the WSO2 Gadget server do support both the new (gadgets.*) and legacy APIs.

A comprehensive user guide for the Gadget API can be found here. Note: Certain portal specific features implemented by the portal providers only such as Google Finance for instance are not supported in the WSO2 Gadget Server. These are proprietory gadget features and are not part of the Google Gadget Specification.