Google Gadget API Usage

One common use case is to pull information from the Web and display that within a gadget. Often, we 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.

If you a beginner in authoring gadgets, refer to the Google Gadget Basics tutorial also.

Content Type URL Gadgets

The simplest way to fetch content from a URL and displaying it is to set the <Content> element's type attribute to url and provide the URL location with the href attribute. Given below is a sample where the WSO2 mailing list information is fetched from MarkMail (http://wso2.markmail.org/search/?q=) and displayed on a gadget.

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

This gadget, once deployed in the WSO2 Gadget Server, will render as follows:

The gadget renders successfully, but there is a problem. The content is clipped and there is no way to see the full content. To fix this, we can set the "height" and "scrolling" attributes on the content element as follows:

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

After deploying in the Gadget Server:

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 still do not see scrolling. The reason is an issue in the Apache Shinding (https://issues.apache.org/jira/browse/SHINDIG-180), which is the core engine of the WSO2 Gadget Server. Hopefully this will be fixed in the near future. In the meantime, we suggest using a larger height as a workaround and viewing 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.

Note:
For more information on URL content type, refer to the URL section of the Google gadget API documentation: http://code.google.com/apis/gadgets/docs/fundamentals.html#URL

Content Type HTML Gadgets

The content type html is used when we pull information from the Web, process and extract it to be displayed within the gadget with various visualization forms.

<Content type="html">

One point to be kept in mind when using html content type gadgets is that, they must include a CDATA section. Any HTML code that we write must go within this section. For example,

<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 point is that, with URL content type gadgets, the gadget engine pulls 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 offering a lot of flexibility when processing the pulled content.

Note:
For more information on HTML content type, refer to the HTML section of the Google gadget API documentation here: http://code.google.com/apis/gadgets/docs/fundamentals.html#HTML

Pulling Information into a Gadget with makeRequest

Google gadget API provides a call named "makeRequest" 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 the content in the gadget.

Note:
For information on "makeRequest," refer to the Google gadget API documentation here: http://code.google.com/apis/gadgets/docs/reference/#gadgets.io.makeRequest

This gadget, has a HTML element defined in the content section, fetches content from a mailing list archive URL and fills in the div content with the fetched data.

<?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 = "http://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>

The data fetching and filling in the div is done using JavaScript logic. There are two functions, one that gets the HTML from the URL and one that process the response.
In line 21, we register the getHtml function, to be triggered on the loading of the gadget.
Within getHtml, in line 12, we set the request parameter saying that the content type is TEXT. It means that we expect the content in text format.
In line 14, we make the request to fetch with the mailing list URL, the name of the callback function into which "makeRequest" feeds the content, and the request parameters.
When "makeRequest" receives the fetched content, "processResponse" will be called with the response object, and the text field will have the received HTML as text. So we can use that text and set the
element’s innerHTML as seen in line 18.

Here is the output of this gadget:

We still see that the content is clipped. The fix is to adjust the height of the gadget dynamically when content gets updated. For this, we can use a combination of the dynamic-height feature and a call to adjustHeight API.

Dynamic Height with Google Gadgets

There are two changes to be made to the gadget.

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

Update the <ModulePrefs> to require dynamic-height feature.

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

Update the precessReponse JavaScript function to call adjustHeight, right after setting the <div> element’s content.

Now we can see the full content in the gadget as follows:

Note:
For more information on dynamic height settings, refer to the Google gadget API documentation here: http://code.google.com/apis/gadgets/docs/ui.html#Dyn_Height

This gadget still displays content from the URL as it is. But we might want to process and present this data in a more appealing format, like a graph. We explore how to use a third-party JavaScript library and content from MarkMail, to come up with more colorful gadgets in the second part of this tutorial: Making your Gadget Visually Appealing.