Google Gadgets API - Getting Started

Google Gadgets API Developer Guide
Google Gadgets HomeSubmit a GadgetGoogle Gadgets for Your Page
Developer Guide
Resources
Developer FAQDeveloper ForumGoogle CodeTerms and Conditions
Search Gadgets Docs

Getting Started
Welcome to the Google Gadgets API! This document walks you through creating your first Google Gadget. This document is intended for people who want to use the Google Gadgets API to write gadgets. Gadgets are so easy to create that they are a good starting point if you are just learning about web programming.
Contents
"Hello, World"What‘s In a Gadget? Writing Your Own GadgetsAdding the Developer GadgetHosting GadgetsCreating a Gadget SpecDefining ContentDefining User PreferencesDefining Gadget Preferences
Gadget Scratch PadWhere to Go From Here
The easiest way to start learning about this API is to see an example. The following gadget simply displays the message "Hello, world!":






You can see the actual gadget specificationhere.
To run this example:
Go tohttp://www.google.com/ig. To add a gadget, you must have a personalized homepage. If you don‘t already have one, you must create one by clicking Make it your own. Then sign in with an existing Google Account, or create a new one. Once you have a personalized homepage, you can add gadgets to it by clicking Add stuff in the upper right corner. This takes you to thecontent directory. You can use the content directory to search for gadgets and add them to your homepage. Click Add by URL (next to the "Search Homepage Content" button). In the Add by URL text box, enter "hello.xml", and click Add. Click Back to homepage, where you will see that the gadget has been added.
The text "hello.xml" is shorthand for the URLhttp://www.google.com/ig/modules/hello.xml. You can put the URL for any gadget specification in the Add by URL text box, including ones that you or your friends write (as long as they are posted on a public web server).
Note the following about the "Hello World" example:
Gadgets are specified in XML. The first line is the standard way to start an XML file. This must be the first line in the file. The tag indicates that this XML file contains a gadget. The tag contains information about the gadget such as its title, description, author, and other optional features. The line indicates that the gadget‘s content type is HTML. 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. signifies the end of the Content section. signifies the end of the gadget definition.
What‘s In a Gadget?
The Google 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.
Writing Your Own Gadgets
To get started writing your own gadgets, we recommend that you copy one of the examples and make a very simple change to it. For example:
Copy the XML specification file (http://www.google.com/ig/modules/hello.xml) for Hello World to a public web server. If you don‘t have access to a public web server, you can use one of the availablealternatives. Use a text editor to change the title and message. Don‘t forget to save the file when you‘re done. Welcome to my first gadget! ]]>
Go tohttp://www.google.com/ig. If you don‘t already have a personalized homepage, you must create one as describedabove. Click Add content. This takes you to thecontent directory. You can use the content directory to search for gadgets and add them to your homepage. Click Add by URL (next to the "Search Homepage Content" button). In the Add by URL text box, type the URL for the XML gadget specification you want to add, and click Add. To figure out what this URL should be, you may have to ask for help from your webmaster.
Adding the Developer Gadget
The developer gadget acts a "command center" for all of the gadgets on your homepage. 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 detailhere. 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.
Hosting Gadgets
If you don‘t have access to a public web server, you can host your gadgets using Google Page Creator. For a more sophisticated hosting solution that includes version control, seeHosting on Google Code.
To host gadgets using Google Page Creator:
Go tohttp://pages.google.com/ and log into your Google account.
If you are a new Google Page Creator user: The first time you use Google Page Creator, you must agree to the Terms and Conditions before you can go any further. After that, you are taken to a page that displays your default Google Page Creator home page in an editor (note that this home page is not related to your personalized homepage). From this page you can click Back to the Page Manager to go to the Page Manager.
If you are not a new Google Page Creator user: When you log into Google Page Creator, the first page it displays is the Page Manager.
In the Page Manager, click the upload link (lower right corner). Type the full path of your gadget specification, or use the Browse button to upload the file to your Google Page Creator base directory. The added file is listed in the "Uploaded stuff" area of the Page Manager. You can delete files by clicking their associated trash can icons. Once you have uploaded your gadget specification, you can reference it using a URL relative to your Google Page Creator base directory.
For example, suppose you have a gadget called "myphonebook.xml," and you upload it to Google Page Creator. You could then add it to your personalized homepage with a URL such as the following:
http://.googlepages.com/myphonebook.xmlRemember: 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? Google encourages 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 thecontent directory or post it to directories likegooglemodules.com orhotmodules.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.
Creating a Gadget Spec
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:
Gadget Preferences. The section in the XML file specifies characteristics of the gadget, such as title, author, preferred sizing, and so on. User Preferences. The 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. Content Section. The 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.
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, seeEscaping Special Characters.
When writing a gadget, you should start with the section.
Defining Content
The section represents the "brains" of a gadget. The section defines the type of content, and either holds the content itself or has a link to external content. The 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 section. Experienced web developers can readChoosing a Content Type for other options relating to access control, remote hosting, using alternative scripting languages, and other topics. Here‘s an example simple gadget. This gadget displays a clickable photograph that opens a photo album in a new HTML page:

title="Click Here.">