Getting Started introduces you to gadgets. The next step is creating your own gadgets. This document tells you how.
Here are the basic steps you follow to create and deploy 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
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.<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.<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.
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>
You can include an arbitrary DOCTYPE in your gadget spec. Gadgets that do not specify a DOCTYPE are rendered in quirks mode by default.
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:
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:
title="Preferences for __UP_myname__". When you run the gadget, the value supplied for the user preference myname is dynamically substituted for __UP_myname__.bool data type. This is displayed in the user interface as a checkbox.enum data
type. The list of EnumValues 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.
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:
<ModulePrefs> title attribute, use __UP_name__ .
This is HTML-escaped.<ModulePrefs> title_url attribute, use __UP_name__ .
This is URL-escaped.<Content> section
, use __UP_name__.
This is HTML-escaped.<Content> section, use the gadgets.Prefs() function.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.
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.
Don't forget to test your gadget using the Gadget Checker. This will help avoid common errors by catching problems with XML formatting and validity, HTML syntax, client-side latency, unused features, missing elements, and more.