中国结

The Google Homepage API provides a way to put third party content onto the Google homepage. The main use of the Googe Homepage API is to create modules (mini-applications) that users can add to their Google personalized homepages. For example, you could create a photo album module, or a module that displays an interactive game. The API is designed to be simple enough that anyone can turn his or her web page or application into a module.

Table of Contents

Introduction

Audience

This document is intended for people who want to use the Google Homepage API to write modules. Modules are so easy to create that they are a good starting point if you are just learning about web programming. The Google Homepage 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 modules. Later, as you write more sophisticated modules, 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 module specifications. A module is simply an XML file, placed somewhere on the internet where Google can find it. The XML file that specifies a module contains instructions on how to process and render the module. The XML file can contain all of the data and code for the module, 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 module is typically written in HTML.

JavaScript is a scripting language you can use to add dynamic behavior to your modules.

"Hello, World"

The easiest way to start learning about this API is to see a simple example. The following module simply displays the message "Hello, world!":

You can see the actual module specification here.

Note the following about this example:

• Modules 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 module.
• The tag contains information about the module such as its title, description, author, and other optional features.
• The line  indicates that the module's content type is HTML.
• insert HTML here... ]]> is used to enclose HTML when a module's content type is HTML. It tells the module parser that the text within the CDATA section should not be treated as XML.
• signifies the end of the Content section.
• indicates the end of the Module definition.

To run this example:

1. Go to http://www.google.com/ig.
2. To add a module, you must have a personalized homepage. If you don't already have one, you must create one by clicking Personalize your Google homepage. Then sign in with an existing Google Account, or create a new one.
3. Once you have a personalized homepage, you can add modules to it by clicking Add Content in the upper left corner.
4. Enter "hello.xml" in the Create a Section text box, and click Go.

The text "hello.xml" is shorthand for the URL http://www.google.com/ig/modules/hello.xml. You can put the URL for any module specification in the Create a Section text box, including ones that you or your friends write (as long as they are posted on a public web server).

Writing Your Own Modules

Getting Started

To get started writing your own modules, we recommend that you copy one of the examples and make a very simple change to it:

1. 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 Google Base.
2. Use a text editor to change the title and message. Don't forget to save the file when you're done.

    
   
     My first module" /> 
       
        Look Ma, no hands!! 
        ]]> 
       
   

3. Go to http://www.google.com/ig. If you don't already have a personalized homepage, you must create one as described above.
4. To add the module you modified, click Add Content in the upper left corner of your homepage.
5. Click Create a Section and enter the URL for the XML module specification in the text field. To figure out what this URL should be, you may have to ask for help from your webmaster.

Adding the Developer Module

The developer module acts a "command center" for all of the modules on your homepage. It lets you add, view, and manage modules. The developer module gives you features you will need if you're doing module development. For example, it lets you add modules that are "broken," which is useful when you are actively changing a module.

To add the developer module, click Add Content > Create a Section and enter "developer.xml" in the text field.

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

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

Hosting Modules Using Google Base

If you don't have access to a public web server, you can put your modules in Google Base:

1. Go to http://base.google.com/ and log in to your Google account.
2. Under Post an item, choose Create your own item type.
3. In the Create your own item type field, type "Module", and click Next.
4. In the Title field, type a simple descriptive title such as "Photo Album Module". This is not the same as your module title, nor is it used in your module. Do not provide attributes ("Details") or Labels.
5. Type (or cut and paste) the XML module specification into the Description field.
6. Click Publish, and wait for Google Base to publish your module. Once it is published, Google Base provides an item URL link.
7. Click the item URL link and copy the URL from your browser's Address field into the Add Content >Create a Section text field or developer module on your personalized homepage.

If your module includes JavaScript code and you want to host it in Google Base, you must include the JavaScript in the section of your XML module spec. In other words, if your JavaScript lives in an external file, you must host your module somewhere other than Google Base.

Information in Google Base (or anywhere in your module spec, for that matter) is public. Be sure not to include personal information, such as your telephone number or personal email address.

NOTE: Google Base processes
tags differently than it does other HTML tags. To to avoid problems, include an extra space between the R and the closing angle bracket:

This extra space is legal and ignored on all browsers supported by the Google Homepage API.

Creating a Module Spec

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

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

When writing a module, you should start with the section.

Defining Content

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

The following table lists the attributes:

These types of content are described in more detail in the following sections.

HTML Content

A module can have the type "html". This means that it contains HTML, possibly with embedded JavaScript, Flash, ActiveX, or other browser objects. The rules for an HTML module are as follows:

• HTML must go within the CDATA section:

 
    HTML here... ]]>

• You cannot use the , , or <span cla