Curated on 08th March 2012

Writing Google Gadgets – A Tutorial – Part 01

We will start small and simple and then gradually move onto
more useful and advanced features in these tutorials. Along the way, we will
evolve a gadget from ground up to a user configurable, comprehensive gadget. We
will use WSO2 Gadget Server as the hosting environment to test the gadget,
along the way. WSO2 Gadget
Server adheres to the Google Gadget Specification [1], thus, allows hosting
gadgets written for Google gadget container.

Google Gadgets Basics

The source code of a gadget is written in XML. In other words, a gadget is an XML document. The root element of a gadget is <Module>.
And a gadget consists of three main sections:

1. Gadget Preferences: Specifies characteristics of the gadget. Wrapped with <ModulePrefs> XML element. Mandatory.
2. User Preferences: Defines controls that allow users to specify settings for the gadget. Wrapped with <UserPrefs> XML element. Optional.
3. Content Section: Specifies the content of the gadget, often using HTML and JavaScript programming logic. Wrapped with <Content> XML element. Mandatory.

The following diagram portrays the overall gadget structure, which consists of the three main sections described above.

You can find more information on the anatomy of a gadget on Google gadget basics documentation page [2].

Basic Gadget Example – Hello Gadget

Here is a sample gadget that demonstrates the three elements of a gadget.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
    <ModulePrefs title="Hello Example" />
    <UserPref name="Name" display_name="Your Name" default_value="World" />
    <Content type="html">
     <![CDATA[
       Hello, <span id="nameSpan"> Name goes here </span>
       <script type="text/javascript">
          var prefs = new gadgets.Prefs();
          document.getElementById('nameSpan').innerHTML = prefs.getString("Name");
      </script>
      !
     ]]>
    </Content>
</Module>

In this gadget, we set the gadget title in the gadget preference section on line 3. The title is "Hello Example".

On line 4, we set a user preference with the preference name being "Name", display name being "Your Name" and default value being "World".

In the content section, we print a greeting message, based on the value set by the user for Name preference field.

We have a span with the ID "nameSpan", preceded by "Hello," on line 7.

From lines 8 to 11 we have some JavaScript logic to pick the name
preference value, and set the "nameSpan" with the preference value.

As the default value for "Name" is "World", the gadget would greet with "Hello, World!" when it loads initially, and if the user sets the name preference, would greet accordingly.

Hello Gadget in Action

The following figure shows how the gadget behaves in action. This simple gadget is capable of picking the user settings and greets the user accordingly. Later in this tutorial series, we will explore in more detail, how to make use of user preferences and make gadgets configurable.

To try this gadget with WSO2 Gadget Server, you can upload the gadget to the gadget repository, on Gadget Server management console, by going to

Home > Manage Gadget Server > Gadget Repository > Add / Modify Gadget

You can find documentation on uploading a gadget to gadget repository [3], adding the gadget to the portal [4] and if you are a newbie to WSO2 gadget server – how to install [5] on WSO2 developer portal.

Pulling Information from the Web into a Gadget

Now that we know the basic structure of a gadget, let’s move on to a more useful use case.

One of the common use cases is to pull information from the Web and display information within a gadget.
Often we might want to extract some useful information from the Web URL, and display on the gadget, rather than showing the Web data as they are.
However, before diving into the complex case, let’s look at the simple case of pulling a page and displaying as it is.

Content Type URL Gadgets

The simplest way to fetch content from a URL and display is to set the <Content> elements "type" attribute to "url" and provide
the URL location with the "href" attribute. Following is a sample where WSO2 mailing list information is fetched from MarkMail [6] and displayed on a gadget.

<?xml version="1.0" encoding="UTF-8"?>
<Module>
    <ModulePrefs title="MarkMail WSO2 Lists">
    </ModulePrefs>
    <Content type="url" href="https://wso2.markmail.org/search/?q="/>
</Module>

This gadget, once deployed with WSO2 Gadget Server will render like following.

The gadget renders successfully, but there is a problem. The content is clipped, and there is no way to see the full content.

We can try setting "height" attribute and "scrolling" attribute on the content element:

    <ModulePrefs title="MarkMail WSO2 Lists" height="350" scrolling="true" />
 

Now the height setting has worked, and we can see the graph on the top left hand side of the original page within the gadget. However, we do not still see scrolling. This is due to an issue [7] in the Apache Shinding engine that is used as the core engine of WSO2 Gadget Server. Hopefully this would be fixed in the near future.
A workaround would be to use larger height, and view the gadget in the maximized mode. Yet, since the main objective is not to load the page as it is, let’s move on and look at more useful forms of this gadget.

Google gadget API documentation on URL content type [8] might provide more details on URL content type, if you are interested in.

Content Type HTML Gadgets

The "Hello" gadget given earlier in this tutorial, used <Content> element's "type" attribute as "html".

    <Content type="html">

This content type is what we have to use when we want to pull information from the Web, process it, and extract information that we need and display within the gadget, using various visualization forms that we need.
One point that must be kept in mind when using "html" content type gadget, is that, it must include a CDATA section, within element and any HTML that we write must go within that section. This in fact was done in the Hello gadget sample we used earlier as well:

   <Content type="html">
     <![CDATA[
       Hello, <span id="nameSpan"/>
       <script type="text/javascript">
          var prefs = new gadgets.Prefs();
          document.getElementById('nameSpan').innerHTML = prefs.getString("Name");
      </script>
      !
     ]]>
    </Content>

Another important aspect to note is that with URL content type gadgets, the gadget engine triggers the pulling of content from the URL given. However, when we use HTML content type gadgets, we have to write our own logic, to pull the Web URL into the gadget. Though this might sound complex, there are built-in mechanisms and APIs that we can use to pull a URL content and this also yields flexibility to make our lives easy, when processing the pulled content.

Google gadget API documentation on HTML content type [9] might provide more details on HTML content type, if you are interested in.

Pulling Information into a Gadget with makeRequest

Google gadget API provides a call named "makeRequest" [10] to fetch content from a URL. Let’s look at a sample, where we fetch WSO2 Carbon and Stratos SVN commits data from MarkMail and display them content in the gadget.

This gadget, has a

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
    <ModulePrefs title="WSO2 Carbon and Stratos SVN Data from MarkMail" />
    <Content type="html">
          <![CDATA[
          <div id="contentDiv"></div>
          
          <script type="text/javascript">
            
              function getHtml() {    
                  var parameters = {};  
                  parameters[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;  
                  var url = "https://markmail.org/browse/org.wso2.carbon-commits";  
                  gadgets.io.makeRequest(url, processResponse, parameters);
              };
            
              function processResponse(response) {  
                   document.getElementById('contentDiv').innerHTML = response.text;
              };
            
              gadgets.util.registerOnLoadHandler(getHtml);
        
         </script>
          ]]>
    </Content>
</Module>

    <ModulePrefs title="WSO2 Carbon and Stratos SVN Data from MarkMail">
        <Require feature="dynamic-height" />
    </ModulePrefs>

              function processResponse(response) {  
                   document.getElementById('contentDiv').innerHTML = response.text;
                   gadgets.window.adjustHeight();
              };