Core JavaScript Library
You manage gadget logic using JavaScript. To include JavaScript code in your gadget use the following template:
<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Hello world example" />
<UserPref name="title" display_name="Gadget Title"
default_value=" Hello world example"
datatype="string" />
<Content type="html">
<![CDATA[
<script type="text/javascript">
// Your JavaScript code here...
</script>
]]>
</Content>
</Module>
You'll use the Google Gadget API core JavaScript library frequently. Possibly the most important function in this library is
_IG_RegisterOnloadHandler, which is the event-handler function called when the gadget is loaded. It takes a single argument—the function it should invoke when the page loads. Here's an example:
<Content type="html">
<![CDATA[
<script type="text/javascript">
function init()
{
alert("hello, world!");
}
// Call the init function on page load
_IG_RegisterOnloadHandler(init);
</script>
]]>
</Content>
This gadget uses
_IG_RegisterOnloadHandler to call the
init function, which displays "hello, world!" as soon as the page gets loaded.
Another useful Google Gadget API feature is the _IG_Prefs class, which you use to retrieve user preferences programmatically:
var prefs = new _IG_Prefs();
var title = prefs.getString("title");
alert(title);
The preceding code retrieves the
title user preference and displays it using the JavaScript
alert method. In addition to
getString, you can use
getInt and
getBool to retrieve integer and Boolean user preferences, respectively. You can also set preferences as well as retrieve them, for example:
var prefs = new _IG_Prefs();
prefs.set("title", "The New Title Here");
To use this setter method you need to include the
setprefs library in your gadget. You do this through a
Require XML element—a child of
ModulePrefs, for example:
<ModulePrefs title="The title">
<Require feature="setprefs"/>
</ModulePrefs>
There are many other JavaScript libraries you may find useful. They fall under the name "Feature-Specific JavaScript Libraries." For example, you could include the JavaScript library used to build tabbed applications. You'd include that library using the following code:
<ModulePrefs title="The title">
<Require feature="tabs"/>
</ModulePrefs>
The preceding code would let you use the _IG_Tabs class and its methods to build very nice tab-based gadgets. I won't go into any more detail about this and other feature-specific JavaScript libraries in this article since that discussion would require an article of its own.
Instead, I'll briefly discuss useful features in the core JavaScript libraries. For example, if you want to retrieve the content at a URL as plain text, HTML or JSON (read more on JSON
here) you can use the _IG_FetchContent function as follows:
<Content type="html">
<![CDATA[
<script type="text/javascript">
function init()
{
_IG_FetchContent(
"http://www.some-content.to-display.com",
callbackFunc);
}
function callbackFunc(responseText)
{
_gel("mainContainer").innerHTML = responseText;
}
// Call the init function on page load
_IG_RegisterOnloadHandler(init);
</script>
<div id="mainContainer"></div>
]]>
</Content>
As you can see
_IG_FetchContent takes two arguments. The first is the URL to fetch the content from. The second is the callback function to call when the content gets retrieved. This is necessary since
_IG_FetchContent is asynchronous so it does return immediately after its call. In the previous example the callback function displays the HTML code retrieved from that fictitious URL within the
mainContainer div tag.
Of course, you're free to handle the retrieved content any way you'd like. For example, you might use this scenario to display a random funny quote whenever the gadget gets loaded. Note also the use of another core function,
_gel, which is just a shorthand "get-element" wrapper around the more verbose
document.getElementById JavaScript function. There are other useful wrapper functions. You'll see some of them later on. The others can be inspected by pointing your browser to the
Official API Reference.
In addition to
_IG_FetchContent, the core API provides two other functions used for similar purposes:
- _IG_FetchXmlContent(URL, func): Fetches the XML content at the specified URL. When it's ready, calls the function specified in the func parameter. Like _IG_FetchContent(), it is asynchronous.
- _IG_FetchFeedAsJSON(URL, func, num_entries, get_summaries): Fetches the RSS/Atom feed content at URL asynchronously and returns it as a JSON object. When it's ready, calls func. It fetches, at most, the number of feed entries specified by num_entries (the default is 3, the possible range is 1-100), and optionally fetches summaries for each entry depending on the value of get_summaries—the default is false.
I used the
_IG_FetchFeedAsJSON method to develop the DevX RSS feed-reader gadget discussed next.
Previous Page
