Writing Your Own Gadgets

Getting Started introduces you to gadgets and the Google Gadgets Editor, which lets you edit gadgets and preview your changes without even leaving the developer guide. The next step is creating your own gadgets. This document tells you how.

Contents

1. Basic Steps
2. Adding the Developer Gadget
3. Anatomy of a Gadget
   1. Defining Content
   2. Defining User Preferences
   3. Defining Gadget Preferences
4. Remember: Gadgets are Public
5. Where to Go From Here

Basic Steps

Here are the basic steps you follow to create and deploy a gadget:

1. Use the Google Gadgets Editor (GGE) or any text editor to write your gadget specification, and host it on a public web server. The easiest way to do this is through GGE. When you save a gadget in GGE, it is automatically hosted in the GGE environment.
2. In GGE, choose File > Publish.
3. In the Publish Your Gadget dialog, choose Add to my iGoogle page. If you don't already have an iGoogle page, you must create one as described in Getting Started.
4. Go to http://www.google.com/ig, and make sure you are logged in. You will see the gadget you just published to iGoogle.

See Google Gadgets Editor: Get Started Now for additional publishing options available through GGE.

You can use File > Upload to upload gadget resources into GGE. Once they are hosted on GGE, you can use them in your gadgets. For example, to upload an image you want to include in a gadget:

1. Choose File > Upload, and browse to your image file in the file system.
2. Click Upload to upload the file.
3. One you've uploaded the file, you can get its full URL by clicking the file name in the upper right corner of GGE. For example: http://hosting.gmodules.com/ig/gadgets/file/114770342902047654452/myimage.jpg. You can use this URL to reference the image file in your gadget spec.

If you are not authoring, hosting, and publishing your gadget through GGE, you must find another way to host it on an external server. An alternative is Google Code hosting. You can add any gadget to iGoogle directly by typing the gadget's URL into the Add by URL text box in the iGoogle content directory.

Adding the Developer Gadget

The developer gadget acts a "command center" for all of the gadgets on your iGoogle page. In addition to listing all the gadgets that you're running, it lets you add, view, and manage gadgets. The developer gadget gives you features that you will need if you're doing gadget development. For example, it lets you add gadgets that are "broken," which is useful when you are actively changing a gadget.

To add the developer gadget, click here:

In the developer gadget you can click on individual gadget links to view their XML specifications. This is a good way to see how other gadgets are implemented.

You don't need to worry about advanced developer gadget features for now. They are discussed in more detail here. But one feature you may want to take advantage of right away is the Cached checkbox. By default, gadget specifications are cached. You should uncheck Cached for gadgets while you are working on them. This lets you see your edits instead of the cached gadget.

Anatomy of a Gadget

Once you understand how to edit and publish gadgets, you're ready to include more advanced features in your gadget specifications. The XML gadget specification consists of 3 major parts:

• Content Section. The <Content> section is where the real work of your gadget happens. It is where you specify the type of gadget, your programming logic, and often the HTML elements that determine the appearance of your gadget.
• User Preferences. The <UserPrefs> section defines controls that allow users to specify settings for the gadget. For example, a personalized greeting gadget might provide a text field for users to specify their names.
• Gadget Preferences. The <ModulePrefs> section in the XML file specifies characteristics of the gadget, such as title, author, preferred sizing, and so on.

Note: Within the XML attributes in a gadget spec, you need to "escape" (that is, properly encode) certain characters so that they will be interpreted correctly. For more information, see Escaping Special Characters.

When writing a gadget, you should start with the <Content> section.

Defining Content

The <Content> section represents the "brains" of a gadget. The <Content> section defines the type of content, and either holds the content itself or has a link to external content. The <Content> section is where the gadget attributes and user preferences are combined with programming logic and formatting information to become a running gadget.

The easiest way to create your gadget is to simply place HTML (and optionally, JavaScript or Flash) into the <Content> section. Experienced web developers can read Choosing a Content Type for other options relating to access control, remote hosting, using alternative scripting languages, and other topics. Here's a simple sample gadget. This gadget displays a clickable photograph that opens a photo album in a new HTML page:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Go to Photo Album" height="250" scaling="false" />
  <Content type="html">
  <![CDATA[ 
    <div style="text-align:center"><a
      id="Riggs" title="My Photo Album" target="_blank" 
      href="http://picasaweb.google.com/doc.examples/ShelfBoy">
      <img border="0" alt="Photo" src="http://doc.examples.googlepages.com/Riggsie-OP.jpg" 
      title="Click Here."></a>
    </div>
  ]]> 
  </Content>
</Module>

This is the running gadget:

Defining User Preferences

Some gadgets need to give users a way of supplying user-specific information. For example, a game gadget might allow users to enter a preferred level of difficulty. The user preferences (<UserPref>) section in the XML file describes the user input fields that are turned into user interface controls when the gadget runs. User preferences are stored persistently.

For example, this gadget displays a personal greeting based on the time of day. It lets users specify the following:

• A name to use in the greeting. The name is also displayed in the title bar.
• A background color.
• Whether to display a photo.

This is an example of the running gadget:

This is what the gadget looks like when the user clicks edit to modify the user preferences:

The user preferences that get turned into user interface controls in the running gadget are defined in the XML specification as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="250" />
  <UserPref name="myname" display_name="Name" required="true" />
  <UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/Rowan-headshot.jpg"/>
  <UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
  <UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" >
    <EnumValue value="Red" />
    <EnumValue value="Aqua" />
    <EnumValue value="Lime" />
    <EnumValue value="Yellow" />
    <EnumValue value="Pink" />
    <EnumValue value="Orange" />
    <EnumValue value="White" />
  </UserPref> 

Note the following:

• Line 3 of the file contains the text title="Preferences for __UP_myname__". When you run the gadget, the value supplied for the user preference myname is dynamically substituted for __UP_myname__.
• The myname user preference is marked as "required." If the user tries to run the gadget without supplying a value for this field, the user preferences edit box remains open until a value is provided.
• The user preference mychoice has a bool data type. This is displayed in the user interface as a checkbox.
• The user preference mycolor has an enum data type. The list of EnumValues specifies the choices that appear in a drop-down menu in the user preferences edit box.

Here is the JavaScript that displays the greeting for the gadget:

<Content type="html"> 
<![CDATA[ 
  <div id="content_div" style="font-size:12pt; padding:5px;">
  <script type="text/javascript">

    // Get userprefs
    var prefs = new _IG_Prefs();

    // Based on user input, display personal greeting
    function displayGreeting (){
      // Create Date object
      var today = new Date();
      // Get current time.
      var time = today.getTime();
      var salutation;

      // Based on the time of day, display an appropriate greeting
      var hour = today.getHours();
      if (hour < 12)
        salutation = "Morning";
      else if (hour > 17)
        salutation = "Evening";
      else salutation = "Afternoon";

      // Build HTML string to display message
      var html = "";
      var element = document.getElementById('content_div');
      element.style.height=250;

      // Set the background color according to the mycolor userpref
      element.style.backgroundColor=prefs.getString("mycolor"); 

      // Display a greeting based on the myname userpref
      html += "<br><h2>Good " + salutation + ", " + prefs.getString("myname") + "!!!</h2><br>"; 

      // If the "Show Photo?" checkbox is checked, display photo.
      if (prefs.getBool("mychoice")==true)
      {
        html += '<img src="' + prefs.getString("myphoto") + '">'; 
      }
      _gel("content_div").innerHTML = html;
    }
    _IG_RegisterOnloadHandler(displayGreeting);
  </script>
]]> 
</Content>

For a list of all the <UserPref> attributes, see the Reference.

User preferences are accessed from your gadget using the user preferences JavaScript API, for example:

<script type="text/javascript">
  var prefs = new _IG_Prefs();
  var someStringPref = prefs.getString("StringPrefName");
  var someIntPref = prefs.getInt("IntPrefName");
  var someBoolPref = prefs.getBool("BoolPrefName");
</script>

For a list of all of the JavaScript functions, see the Reference.

Note: If you store sensitive private user data in a gadget's user preferences, we suggest that you use the locked-domain feature.

User Preference Substitution Variables

You can use a substitution variable of the format __UP_userpref__ in the <ModulePrefs> or <UserPref> sections, where userpref matches the name attribute of a user preference. When the gadget runs, the string value of the corresponding user preference is substituted for the variable, unescaped. For example, in this excerpt, the value the user supplies at run time for the projects user preference is substituted for __UP_projects__ in the title_url string:

<Module>
  <ModulePrefs title="Build Monitor"
             title_url="http://www.example.com/build/status.php?__UP_projects__"/>
  <UserPref name="projects" display_name="project(s)"/>
  <Content ... />
</Module>

You can see another example of this in the user preferences sample.

Here are the general guidelines for using user preference substitution variables:

• For the <ModulePrefs> title attribute, use __UP_name__ . This is HTML-escaped.
• For the <ModulePrefs> title_url attribute, use __UP_name__ . This is URL-escaped.
• In HTML within the <Content> section , use __UP_name__ . This is HTML-escaped.
• In JavaScript code within <Content> section, use the _IG_Prefs() function.

Defining Gadget Preferences

The <ModulePrefs> section in the XML file specifies characteristics of the gadget, such as title, author, preferred sizing, and so on. For example:

<Module>
  <ModulePrefs title="Today's Network Traffic" 
     title_url="http://www/~rowan/gadgets/stats/" 
     height="200" 
     author="Jane Smith" 
     author_email="xxx@google.com"/> 
  <Content ...>
   ... content ...
  </Content> 
</Module>

The users of your gadget cannot change these attributes.

For a full list of the <ModulePrefs> attributes, see the Reference.

Remember: Gadgets are Public

Remember that there is no such thing as a private gadget. Once you publish your gadget on a public website, people can find it and view it. Be sure not to include personal information, such as your telephone number or personal email address.

What if you don't want your gadget to be public? We encourage gadget authors to share their specifications. However, if you want to minimize your gadget's public visibility before you are ready to release it, here are some tips:

• Don't submit your gadget to the content directory or post it to directories like googlemodules.com or hotmodules.com.
• If people can't find your gadget, it's unlikely that they'll guess the URL. There are some subtleties to avoid getting crawled by search engines:
  • Make sure your web server doesn't provide a file listing that includes your file (this also avoids users snooping).
  • Make sure there are no web hyperlinks to your gadget

Where to Go From Here

When you're ready to write more complex gadgets, go to Development Fundamentals, or back to the documentation home page for an overview of sections and topics.

Don't forget to test your gadget using the Gadget Checker. This will help avoid common errors by catching problems with XML formatting and validity, HTML syntax, client-side latency, unused features, missing elements, and more.

Back to top