Getting Started introduces you to gadgets. The next step is creating your own gadgets. This document tells you how.
Basic Steps
Here are the basic steps you follow to create and deploy a gadget:
- Use any text editor to write your gadget specification, and host it on a public web server.
- Add your gadget to a site that has the ability to run gadgets.
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>
Specifying a DOCTYPE
You can include an arbitrary DOCTYPE in your gadget spec. Gadgets that do not specify a DOCTYPE are rendered in quirks mode by default.
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.
Note: For a more general purpose persistence mechanism that isn't tied to userprefs, see the OpenSocial persistence API.
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 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 ofEnumValues
specifies the choices that appear in a drop-down menu in the user preferences edit box.
Here is the complete gadget, including the JavaScript that displays the greeting for the gadget:
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Preferences for __UP_myname__" height="400"/> <UserPref name="myname" display_name="Name" default_value="Rowan"/> <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> <Content type="html"><![CDATA[ <div id="content_div"></div> <script type="text/javascript"> // Get userprefs var prefs = new gadgets.Prefs(); function displayGreeting () { // Get current time var today = new Date(); var time = today.getTime(); var html = ""; // Based on the time of day, display an appropriate greeting var hour = today.getHours(); var salutation = "Afternoon"; if (hour < 12) { salutation = "Morning"; } else if (hour > 17) { salutation = "Evening"; } // Set the background color according to the mycolor userpref 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><FONT SIZE=6>Good " + salutation + ", " + prefs.getString("myname") + "!!!<br><br></FONT>"; // If the "Show Photo?" checkbox is checked, display photo. if (prefs.getBool("mychoice") == true) { html += '<img src="' + prefs.getString("myphoto") + '">'; } element.innerHTML = html; } // Pass the userprefs for this module instance to the function // (allows users to include multiple module instances on their page) gadgets.util.registerOnLoadHandler(displayGreeting); </script> ]]> </Content> </Module>
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 gadgets.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 JavaScript 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 thegadgets.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.
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.