This document describes the different options for publishing your gadget. If you use the Google Gadgets Editor (GGE) to create and host your gadgets, it makes publishing your gadgets much easier.
You can put your gadgets in any of the following places:
Not every gadget is suited to every environment. The following table lists the requirements for each environment:
| Target Environment | Requirements |
|---|---|
| iGoogle | There are no special requirements or limitations for users adding gadgets to iGoogle. |
| Other Google properties, such as Google Toolbar and Google Desktop | For some properties the userprefs edit box is not exposed to users, so in those cases the gadget functionality should not be contingent on each user setting preferences in the edit box. |
| iGoogle Content Directory | Developers submitting gadgets to the content directory should follow the guidelines listed in Publishing to the Content Directory. |
| Syndication | The dynamic height and setprefs features do not work under syndication. The userprefs edit box is not exposed to users, so the gadget functionality should not be contingent on each user setting preferences in the edit box. |
Before publishing your gadget, you should test it, bearing in mind the requirements and limitations of the target environment in which the gadget will run.
You should do the following tests for all gadgets:
|
UserPref values.If you are using _IG_FetchContent(), test
what happens if the data source is down or returns an error. You
can simulate this by changing the URL temporarily to another URL.
How a gadget is sized depends to a large extent on where it runs. When gadgets run under syndication, their specified height and width are simply suggestions for site owners, who are free to change them. For iGoogle, width settings are ignored, and the gadget's width is automatically set to 32%.
Dynamic height only works on iGoogle, so you should test your gadget with various sizes under syndication. You can test your gadget in the syndication creator page using a URL with this format:
http://gmodules.com/ig/creator?synd=open&url=[gadget-url]
In designing and testing your gadgets, be prepared for arbitrary widths from 200 pixels to as wide as 600 pixels. For certain gadgets, the width should be even larger. As a general rule, design the gadget to display properly if it's given extra space. For example, maps gadgets should fill their areas, picture gadgets should center themselves in the frame, and text gadgets should float their text to the top (for example, click-for-more-details links that are typically at the bottom should stay close to the content rather than floating to the bottom of the gadget window).
As a general guideline, your gadget should be 180-200px wide for blogs and Google Desktop, and 250px wide for iGoogle. For maximum versatility, your gadget width should scale up to at least 250px for blogs and Google Desktop, and 600px for iGoogle.
If you write a gadget that you expect to experience heavy traffic, there are steps you can take to ensure availability and good performance. If your gadget gets more than 200,000 views per day, or approximately 1-2 requests per second, you should consider following the tips in this section. Even a 50 KB gadget that receives 200,000 requests per day consumes around 300 GB per month in bandwidth.
There are different reasons a gadget might attract a lot of users. It might simply become popular in the content directory. Or, if the gadget is used in a special promotion or advertisement, that might cause it to experience heavy traffic.
Your goal for a high traffic gadget should be to get it to render in 0.25 seconds (250 milliseconds) or less. Use Firebug (Firefox only) to measure this. Improving the responsiveness of your gadget is a sure way to make a positive impact on the user's experience. For tips on optimizing gadget performance, see Optimizing for Heavy Traffic. For management tips, see Managing Heavy Traffic. The general testing guidelines are also especially important for highly popular gadgets.
If you think that your gadget might experience heavy traffic, follow these guidelines:
type=html gadget. Gadgets that are type=url generally
render more slowly than type=html gadgets because
of the poor performance and poor cache support of other hosting
servers._IG_FetchContent(), _IG_FetchXmlContent() and_IG_Get... functions
cache your content for approximately 1-2 hours by default.
You can use the refreshInterval parameter
with thesehttp://www.google.com/ig/directory?url=<gadget-url> to
see the weekly pageviews for your gadget.<img> tags
in your gadget's HTML. This makes your gadget render faster.
If you're using _IG_GetImage()(see code
example)
and inserting the image element directly into the DOM, you
don't need to set the width and height properties. _IG_Get..._IG_GetImage(url):Here is the code for the sample gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Zombies!" height="350" />
<Content type="html">
<![CDATA[
<div id="zombiecontainer"
style="text-align:center;">
</div>
<script type="text/javascript">
var counter = 0;
// Preload the images using _IG_GetImage().
var images = new Array();
images[0] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-0.jpg");
images[1] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-1.jpg");
images[2] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-2.jpg");
images[3] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-3.jpg");
images[4] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-4.jpg");
images[5] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-5.jpg");
images[6] = _IG_GetImage("http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-6.jpg");
// Browse through photos sequentially. When you get to the end of the array, start over.
function browse(){
if (counter == images.length)
{
counter = 0;
}
_gel("zombiecontainer").innerHTML = "";
_gel("zombiecontainer").appendChild(images[counter]);
counter++;
}
browse();
</script>
<br />
<div style="text-align: center;">
<input type=submit value="Next ->" onClick="browse()">
</div>
]]>
</Content>
</Module>
These guidelines can help you manage a high volume gadget:
<username>.feedback+<gadgetname>@gmail.com in
your gadget spec. This helps you to filter the messages
you receive from gadget users. Gmail drops everything after
the plus sign (+), so this email address maps to <username>.feedback@gmail.com.
Note that Gmail has a high quality spam filter. One of the best things about gadgets is that you can write and test them on iGoogle and then use them on other properties, such as Google Desktop and Google Toolbar. Alternatively, you can use syndication to deploy gadgets on Blogger or on your own HTML pages. See Publishing through Syndication for details.
You can add most gadgets to Google Desktop. However, gadgets are not completely interchangeable with Desktop gadgets. To add gadgets to Desktop, you go to the Desktop content directory and add the gadget by its gadget spec URL, as described below.
Google Toolbar gadgets take a different approach. See Adding Gadgets to Google Toolbar for more information.
To add a gadget the Desktop via the Desktop Sidebar:
You can add gadgets to Google Toolbar through the Toolbar gallery. You can access the gallery in any of the following ways:
For information on developing Toolbar gadgets, see the Google Toolbar
API documentation.
A Toolbar gadget is actually a Toolbar custom button that
includes a <gadget> tag that references a gadget
spec.
Once you have designed, implemented, and tested your gadget, you may decide to submit it to Google to be published in the content directory. The submission process is the same if you want your gadget to be listed in the syndication directory. See Syndicated Gadgets for more information. This section lists the general steps you should follow in preparing any gadget to be published.
The Reference lists all of the <ModulePrefs> attributes that you can use to provide "meta" information about your gadget. Here is the information you should include in your gadget spec:
helensmith.feedback+coolgadget@gmail.com in
your gadget spec. Gmail drops everything after the plus sign
(+), so this email address maps to helensmith.feedback@gmail.com.
You can create a Gmail account here. robots.txt.
PNG is the preferred format, though GIF and JPG are also acceptable.
Gadget screenshots should be 280 pixels wide. The height of
the screenshot should be the "natural" height of
the gadget when it's in use. This helps users understand how
much space a gadget will consume on their screen before they
add it to their page. The screenshot should not have any whitespace
above the gadget's blue header bar. Screenshots should show
your full gadget, including its title bar, but nothing else.
Alternatively, you can screenshot the gadget with the edit
window open. Screenshots should not be resized or
cropped. For quality and consistency, Google may take
its own screenshots of a given gadget.robots.txt.
PNG is the preferred format, though GIF and JPG
are also acceptable. Thumbnails should be 120x60 pixels.
They should not include title bars. If you want to be listed on the authors page, you can include these additional fields:
You can find more information here, and an example here.
Make sure you have coded your gadget in a way that minimizes any security risks.
Not all gadgets can run in all environments. A gadget may require a particular browser or software. You can use the <MayRequire> tag under <ModulePrefs> to provide information about special requirements of your gadget. For more information, see Specifying Compatibility Requirements.
You can use <Locale> tags under <ModulePrefs> to specify the locales supported by your gadget. For more information, see Specifying Locales.
To promote your gadget, consider putting an "Add to Google" button on it.
You can submit your gadget to Google here. You can also submit your gadget to the content directory using the GGE File > Publish command. See the FAQ for an explanation of how to find your gadget in the directory, and what determines its placement. For instructions on how to prepare a gadget for syndication, which means that it can run on third party web pages, see Syndicated Gadgets.
If you have submitted multiple versions of a gadget at different URLs and you want to designate one version as the official one, you can use the igoogle-legacy issue tracker to request the change.
Syndication (Gadgets for Your Webpage) makes it possible to deploy gadgets on third party web pages. For example, here is a live gadget running right in this web page:
How was this accomplished? Simply by adding a <script
src ="http://gadget-URL..." </script> statement
to the HTML of this page. For details, read on.
You can open this gadget in the creator page by clicking here. The easiest way to publish a gadget through syndication is by using the GGE File > Publish command, but you can also use the creator page directly.
See the syndication content directory for examples of syndicated gadgets you can add to any web page.
You don't have to do anything special to a gadget to prepare it for syndication. However, to be eligible for syndication, a gadget must conform to the following guidelines:
There is currently no easy way for users to edit userprefs in a syndicated gadget. Site owners can edit the userprefs before deploying the gadget on a web page, but once the gadget is deployed, the userprefs are no longer editable. So, for example, suppose you have a gadget that displays information based on each user entering the name of a city. You would have to give users a way of supplying this information through the gadget UI rather than through userprefs.
This document uses the following example gadget. The gadget displays a user profile that includes a photo, age, and hobbies. It also lets you set the background color:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Card for __UP_myname__" height="400" />
<UserPref
name="myname"
display_name="Name"
default_value="Touki" />
<UserPref
name="myphoto"
display_name="Photo"
default_value="http://doc.examples.googlepages.com/touki.jpg" />
<UserPref
name="myage"
display_name="Age"
default_value="5" />
<UserPref
name="myhobby"
display_name="Hobbies"
default_value="agility, swimming" />
<UserPref
name="mycolor"
display_name="Color"
default_value="Pink"
datatype="enum" >
<EnumValue value="Pink" />
<EnumValue value="Red" />
<EnumValue value="Aqua" />
<EnumValue value="Lime" />
<EnumValue value="Yellow" />
<EnumValue value="Orange" />
<EnumValue value="White" />
</UserPref>
<Content type="html">
<![CDATA[
<div id="content_div" style="font-size:12pt; font-family:Arial, Helvetica; text-align:center; padding:5px;">
<script type="text/javascript">
// Get userprefs
var prefs = new _IG_Prefs();
showCard();
// Display the card showing the user profile
function showCard (){
// Apply userpref-specified background color to the div
var element = document.getElementById('content_div');
element.style.backgroundColor = prefs.getString("mycolor");
// Build HTML string used to display content
var html = "";
html += '<img src="' + prefs.getString("myphoto") + '">';
html += "<br><b>Age: </b>" + prefs.getString("myage");
html += "<br><b>Hobbies: </b>" + prefs.getString("myhobby");
// render HTML string in the div
_gel("content_div").innerHTML = html;
}
</script>
]]>
</Content>
</Module>
To test a gadget under syndication:
http://gmodules.com/ig/creator?synd=open&url=[gadget-url]
For example, you can view the sample gadget in the creator page with this URL:
http://gmodules.com/ig/creator?synd=open&url=http://doc.examples.googlepages.com/baseball-card.xml
The easiest way to test your gadget in the creator page is by hosting your gadget in GGE, and using the GGE File > Publish command.
For testing purposes, if you want to disable caching, you
can add the &nocache=1 parameter
to your URL.
However, you should not use &nocache=1 to
deploy live gadgets, because it can degrade performance.
http://gmodules.com/ig/creator?synd=open&nocache=1&url=http://doc.examples.googlepages.com/baseball-card.xml
The creator page is the tool that site owners use to:
If you're not hosting your gadget in GGE (where you can use the File > Publish command to open your gadget in the creator page), you can use this gadget to open a gadget in the creator page. Enter the URL for your gadget in the text field, and click Syndicate:
When you click here to open the creator page for the sample gadget, this is what you see:
Note the following:
__UP_myname__ substitution
variable, discussed here. <script src="http://gmodules.com/ig/ifr?url=http://doc.examples.googlepages.com/baseball-card.xml&up_myname=Touki
&up_myphoto=&up_myage=&up_myhobby=&up_mycolor=Pink&synd=open&w=320&h=400&title=Card+for+__UP_myname__
&border=%23ffffff%7C3px%2C1px+solid+%23999999&output=js"></script>
This URL includes the following parameters:
up_. h) and width (w)
parameters. The value of these parameters is typically the number of
pixels. However, you can set the gadget width to fill the containing
space by using w=auto.
This is useful for flexible layouts where you don't know the number
of pixels beforehand.title parameter. If you blank out
the Title field in the creator page, the
title parameter is set to &title=.
The effect in the deployed gadget is that the border is clean
and there is no title bar. border parameter.output parameter, which indicates
how the syndicated gadget is rendered. Possible values are js for
JavaScript if the gadget uses <script> tags,
and html for
everything else. You can test your gadget in Blogger. To display a syndicated gadget in Blogger, you must add it to the template, not to the HTML of a particular page. Blogger may truncate the height, so you may have better results with smaller gadgets.
If your gadget includes <Locale> elements,
as described in Internationalization,
the creator page includes a Language menu that contains
all of the languages your gadget supports. When you choose a language,
it's added to the gadget's syndication URL with the &lang parameter.
A &country parameter is included too, and its default
setting is ALL:
<script src="http://gmodules.com/ig/ifr?url=http://examples.com/hello-i18n.xml...&lang=zh-CN&country=ALL...</script>
To change the setting for &country, you manually modify
the URL. If you try to add a language or country for which your gadget
has no corresponding <Locale> element,
changing the URL has no effect.
For a list of the languages and countries supported by iGoogle, see Supported Languages and Countries.
In the creator page, you can select the border that you want to display around your border on the target web page. There are two possible types of borders: image-based, and CSS-based.
An image-based border is referenced by a URL with with
this format http://hostname/some/path/
(must end in
a slash). Such borders
use a set of 9 images:
tl.gif,
tr.gif,
bl.gif, br.gif -- for the 4 cornersl.gif, r.gif, b.gif -- sides and bottomtt.gif -- top, when there's
a titletn.gif -- top, when there's no title The "width x height" dimensions are as follows :
b.gif, tt.giftn.gifl.gif, r.gifbl.gif, br.gif, tl.gif, tr.gif The
default set are in http://www.google.com/ig/images/...,
for example, http://www.google.com/ig/images/br.gif.
Some of the borders provided in the creator page are based on CSS definitions. These borders consist of a set of lines described by CSS parameters, whose format is as follows:
<bgcolor>|<n>px, <n>px <linetype> <color>|<n>px, <n>px <linetype> <color>|...
where colors are either plain names like "black" or RGB values like #000000, and linetypes are standard CSS linetypes, as explained here.
For example, this border prints two black lines against a white background (note that it uses URL escaping):
&border=%23ffffff%7C1px%2C1px+solid+black%7C1px%2C1px+solid+black%7C0px%2C1px+black
You submit a gadget to the syndication directory just as you would submit a gadget to the regular content directory, as described here. Just remember that to be eligible for syndication, a gadget cannot store state.
