Welcome to the gadgets API!
This developers guide is based on the gadgets.* version of the gadgets JavaScript API. The gadgets API has been "renamespaced" into the gadgets.* JavaScript namespace, to provide a cleaner API to program against and support. To learn more about the gadgets.* API, see the reference documentation here. While the gadgets.* API overlaps significantly with the legacy gadgets API (Labs), there are also important differences.
Currently, only some containers (a container is a site or application that runs gadgets) support the gadgets.* API. For a list of containers that support the gadgets.* API, see the OpenSocial container list. Some older containers support only the legacy gadgets API, so be sure to check the documentation for your specific container to see which API is supported. To learn more about different types of gadgets and where they run, see the gadgets API Overview.
All containers support the legacy API, regardless of whether they support the gadgets.* API. However, the gadgets.* API offers many new features that don't exist in the legacy API, so you should use it if you can.
This developers guide is intended for people who want to use the 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.
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>
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.
Every container that runs social gadgets has slightly different characteristics. Here are a few places to start getting some hands-on experience developing social gadgets:
For more general gadget programming information, 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.