This developers guide describes how to use the legacy gadgets API. For new development,
you should use the gadgets.* API.
The simplest gadget is just a few lines of code. This gadget displays the message "Hello, world!":
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="hello world example" />
<Content type="html">
<![CDATA[ Hello, world! ]]> </Content>
</Module>
Scroll down to the Google Gadgets Editor (GGE) to see a version of "Hello World" that can be edited and previewed live. This is a great way to learn about gadget development.
Note the following about the "Hello World" example:
<Module> tag indicates
that this XML file contains a gadget.<ModulePrefs> tag
contains information about the gadget such as its title, description,
author, and other optional features.<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. The gadgets API consists of a few simple building blocks: XML, HTML, and JavaScript. To get started, all you need is a basic understanding of HTML. We will teach you all you need to know about XML to write gadgets. Later, as you write more sophisticated gadgets, you will probably want to learn some JavaScript if you're not familiar with it already.
XML is a general purpose markup language. It describes structured data in a way that both humans and computers can read and write.
XML is the language you use to write gadget specifications. A gadget is simply an XML file, placed somewhere on the internet where Google can find it. The XML file that specifies a gadget contains instructions on how to process and render the gadget. The XML file can contain all of the data and code for the gadget, or it can have references (URLs) for where to find the rest of the elements.
HTML is the markup language used to format pages on the internet. The static content of a gadget is typically written in HTML. HTML looks similar to XML, but it's used to format web documents rather than to describe structured data.
JavaScript is a scripting language you can use to add dynamic behavior to your gadgets.
Note: Gadgets were formerly called modules, which is why the word "Module" appears throughout the API.
The easiest way to get started writing gadgets is to use the Google Gadgets Editor (GGE). GGE lets you edit gadget specs and click Preview to see the live results of your changes, without even leaving the Developer Guide. You can also use GGE to save, host, and publish gadgets. See File Menu Commands for a list of the operations you can perform in GGE.
By default, GGE contains the gadget specification for "Hello World." Change the message "Hello, world!" to something else, and click Preview to see the result.
Note: GGE does not yet support the gadgets.* API.
The Popular Gadgets and API Examples links let you open sample gadgets in GGE, where you can edit them and preview the results. You can also see the list of samples through the File > New command.
To add GGE to your iGoogle page, click here:
The Edit tab has a drop-down File menu that includes the following commands. GGE uses your Google account to identify the files that belong to you, so you must be logged in to use most of these commands.
| Command | Description |
|---|---|
| New | Displays a dialog that lets you choose an existing gadget to use as a starting point for writing your own gadget. You can use the drop-down menu in the dialog to choose gadgets from either "Popular Gadgets " or "API Examples". "API Examples" lists some of the sample gadgets from this Developer Guide. You can also paste the spec from an existing gadget into the Edit tab. |
| Open | Opens a gadget you previously created and saved through GGE. |
| Open from URL | Opens the gadget spec specified by the URL. |
| Save | Saves the gadget spec you are editing. If you have not saved the gadget before, prompts you for the gadget's name. When you save a gadget in GGE, GGE automatically hosts it for you. A gadget needs to be hosted on a public server before you can publish it, and GGE hosts the gadget and gives you multiple ways of publishing it. |
| Save As | Saves the gadget you are editing under the name you provide. |
| Rename | Renames the gadget you are editing. Only available after the gadget is saved. |
| Upload | Lets you browse the file system for gadget resources and save them into the GGE environment. This could be a gadget spec, or other gadget resources like image files. Once you upload resources into GGE, GGE hosts them. This makes it possible for you to import them into your gadget spec by referencing their GGE URLs. |
| Publish | The Publish menu item gives you the following options for
publishing your gadget:
The command is only available after the gadget is saved (saving causes GGE to host your gadget). For more information, see Publishing Your Gadget from GGE. |
| Delete | Displays a list of your GGE gadgets and lets you select and delete them. |
The Publish command on the File menu gives you the following options for publishing your gadget:
The URL for your gadget is provided in the upper right corner of GGE. You can get the full URL by clicking the link.
While you are developing and testing your gadget, we recommend that you test it on your iGoogle page and on other web pages. Then once your gadget is tested and polished, you can choose to distribute it to a mass audience by submitting it to the iGoogle content directory.
Use this "Getting Started" guide to get an introduction to gadgets and experiment with GGE. When you're ready to take the next step, go to Writing Your Own Gadgets. From there you can go to Development Fundamentals, or back to the documentation home page for an overview of sections and topics.