This document describes tools that help you write gadgets.
The developer gadget is a special gadget that you can use as the basis for creating your own gadgets. It is a dashboard for viewing all of the gadgets on your iGoogle page, and it also lets you control gadget caching. By default, gadget definitions are cached. You can uncheck the Cached checkbox to override this behavior. This is useful when you're working on a gadget and want to see the results of your edits instead of the cached gadget.
The developer gadget is also a sample gadget in its own right.
To add the developer gadget, click Add content > Add by URL (next to the "Search Homepage Content" button) and enter "developer.xml" in the text field.
The developer gadget (screenshot) lists links for all of the gadgets you are currently running on your iGoogle page. You can use the Add a gadget text box to add a new gadget by providing the URL for the gadget spec.
Part of the gadget development process (or any code development process) is understanding why things don't always work the way you expect them to. This section describes some basic techniques for avoiding problems, and for fixing them when they occur.
A fundamental rule of programming is to start small. Get a basic, skeletal gadget working, and then build it up gradually. Test it at every stage before moving on. Using this approach makes it easier to tell when a change you made introduced problems.
One of the greatest resources available to you as a gadget developer is existing gadgets. Go to the content directory and look at the source code of gadgets that closely resemble what you are trying to implement.
You can use the Firefox web browser to test your gadgets on iGoogle during development. If a gadget isn't working properly, open the JavaScript Console (Tools > JavaScript Console), select Errors, and scroll down to see if your gadget has JavaScript syntax errors. Before each test, remember to clear the Console to flush old error messages.
If you're using a different type of browser, look for a JavaScript console or debugger supported by your browser.
Confirming your assumptions during the development process can save
you a lot of time and wasted effort.
Are you sure that your variable has the value you think it does? Are
you certain that your array contains elements? Is it possible that
the function that "doesn't seem to be working right" isn't
getting called at all? You can test your assumptions by printing out
status messages at different points in your program. For example, the
following gadget has a print() function that
writes debugging messages to debug_div if
the debug flag
has a non-zero value:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Debug Example" height="200"/>
<UserPref name="myname" display_name="Name" required="true" />
<UserPref name="mycolor" display_name="Color" default_value="Pink" datatype="enum" >
<EnumValue value="Blue" />
<EnumValue value="Yellow" />
<EnumValue value="Pink" />
<EnumValue value="Gray" />
</UserPref>
<Content type="html">
<![CDATA[
<div id="content_div" style="font-size:20pt; padding:5px; text-align: center;"></div>
<div id="debug_div" style="font-size:9pt; padding:5px; color: red;"></div>
<script type="text/javascript">
// Get userprefs
var prefs = new _IG_Prefs(); // debug flag. When its value is non-zero, debugging messages are displayed
var debug = 1; // The string containing debugging messages
var debug_html = ""; // Display date
function displayDate (){
// DEBUG: is the function getting called?
print("In displayDate function<br>");
// Create Date object
var today = new Date();
// Get current time
var time = today.getTime();
var content_html = "";
var element = document.getElementById('content_div');
element.style.backgroundColor=prefs.getString("mycolor");
element.style.height=100;
// DEBUG: print out prefs values
print("The background color is " + prefs.getString("mycolor") + "<br>");
print("The name is " + prefs.getString("myname") + "<br>");
content_html += today.toDateString();
// Write content HTML to div
_gel("content_div").innerHTML = content_html;
}
// Outputs debug messages if debug flag has a non-zero value
function print(msg) {
if (debug) {
debug_html += msg;
// Write debug HTML to div
_gel("debug_div").innerHTML = debug_html;
}
}
_IG_RegisterOnloadHandler(displayDate);
</script>
]]>
</Content>
</Module>
Note: See MiniMessages for a description of the MiniMessage API, which lets you modify the behavior and appearance of the messages you display in a gadget.
The following Firefox add-ons can help you get more fine-grained insight into your gadgets during development:
You can use Google Analytics to collect statistics about your gadgets. Typically, you use analytics to track pageviews (that is, every time a gadget renders) or events (for example, every time a user clicks a button in your gadget).
To use analytics:
|
UA-xxxxxxx-x is the unique ID
associated with your analytics account:<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript"> _uacct = "UA-xxxxxxx-x"; urchinTracker(); </script>
This snippet does the following:
urchin.js library into the client browser. _uacct. urchinTracker(), sending data back to Google
Analytics. Normally the way that analytics works is that you would copy this code snippet into every web page that you wanted to track. However, gadgets are a special case. You must follow the instructions below to make analytics work for your gadgets.
Once you get an analytics account as described above, you receive a unique analytics ID. You use this ID to integrate analytics into your gadgets.
To integrate analytics into a gadget:
<Require feature="analytics"/>
_IG_Analytics() function. It
takes two parameters: your analytics ID, and a "pageview path." The
pageview path is a way of uniquely identifying each gadget or action
that you want to track in Google Analytics. The pageview path is used
in analytics reports to distinguish one gadget's statistics from another.
The pageview path does not have to exactly match the gadget's name,
but it should be a name that you can easily recognize in your reports.
In the following excerpt, UA-000000-0 is
the analytics ID, and, /mygadget is the
pageview path: <script>
_IG_Analytics("UA-000000-0", "/mygadget");
</script>
This invokes urchinTracker() and sends data back to analytics.
Here is an example of a gadget that includes analytics. This gadget tracks gadget pageviews and button clicks. Each time the gadget is rendered, a pageview is recorded as /test_analyticslib. Each time a user clicks on the button, a pageview is recorded as /test_analyticslib/click. In this example, you would have to substitute a real analytics ID for UA-xxxxxx-x:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Test Analytics Iframe"> <Require feature="analytics" /> </ModulePrefs> <Content type="html"> <![CDATA[ <script> // Track this gadget using Google Analytics. _IG_Analytics("UA-xxxxxx-x", "/test_analyticslib"); </script> <!-- You can also track JavaScript events. When users click this button, a pageview is sent back to Analytics servers. --> <input onclick="_IG_Analytics('UA-xxxxxx-x', '/test_analyticslib/click')" type=button value="Click Me"/> ]]> </Content>
</Module>
Note the following:
/test_analyticslib.
This is the name by which the gadget's statistics will be listed
in Google Analytics reports._IG_Analytics() within an
event handler function. This gadget uses analytics to track
every time a user clicks the gadget's button.As with all other <Require...> features,
analytics also works with type="url" gadgets.
See Using
JavaScript Libraries with type="url" Gadgets for details.
To view the reports associated with your gadgets, log into Google Analytics. Go to View Reports > Content Summary.
For more information on what you can do with Google Analytics, see the Google Analytics Help.
The easiest way to host gadget specs and gadget resources is through GGE. For developers that need a more full-featured source control system, we recommend hosting your gadgets on Google Code: http://code.google.com/hosting. It's a free service that offers you many benefits as a gadget developer. One of its primary benefits is version control through Subversion, which is an open source version control system. With Subversion, you can track changes and maintain different versions of your gadget. The entire revision history is available, which allows you to roll back or analyze differences between versions. To learn more about Subversion, see the Subversion book.
To host your gadgets on Google Code, the first thing you need to do is install a desktop program ("Subversion client") that allows you to load and save files to code.google.com ("Subversion repository"). Most Subversion clients come with a graphical user interface that provides an easier way of interacting with Subversion than the command line interface. There are different clients to choose from depending on your operating system. Make sure to install one that is compatible with your system. Here are a few clients we recommend:
Here is a full list of clients and plugins.
Once you've installed Subversion on your machine, follow the steps below to get started using Google Code to host your projects.
To create a new project:
my-gadgets. Keep
in mind that the project name becomes part of your project's
URL and cannot be changed later. http://code.google.com/p/<project-name>/ You now have a project on code.google.com. A
Subversion repository has been created using your project name. Click
on the Source tab, and click the Subversion
repository link.
The URL should look something like this: http://<project-name>.googlecode.com/svn/.
You should see three directory links: branches, tags,
and trunk. When you upload files to your
project, they are placed in the /trunk folder.
You may want to bookmark the URL http://<project-name>.googlecode.com/svn/trunk/ for
future reference.
Before you can upload files, you need to check out code from your project's
Subversion repository. In order to perform the checkout, you need
three pieces of information: the repository URL (you need to use the
version that is preceded by https, not http), username,
and password. To find this information, go to your project's Source tab
(http://code.google.com/p/<project-name>/source).
You should see something like this:
svn checkout https://<project-name>.googlecode.com/svn/trunk/ gadgets-test --username <username>When prompted, enter your generated SVN password.
Keep this page open in a browser as you continue so that you can retrieve
the appropriate information as needed.
The details of the actual checkout may vary based on which Subversion
client you are using, but the overall process is the same. The
instructions in this section assume you are using TortoiseSVN.
To check out a project:
At this point the client connects and checks out your entire repository. You're
done.
If your checkout completed successfully, you should see a new hidden
folder, /.svn. Do not modify or
delete this folder.
Once your project is checked out, you can begin adding new folders and files to the directory using Subversion commands. The instructions in this section assume you are using TortoiseSVN.
To upload a file:
<project-name>.googlecode.com/svn/trunk/ directory, and
save it (for example, new-gadget.xml). You can
put the file directly under /trunk, or in a subdirectory
under /trunk. When prompted, write an optional note in the message log and click OK. Your file should begin transmitting to the server.
Once the file is transmitted to the server, the commit (upload)
is complete and the file becomes available online immediately at http://<project-name>.googlecode.com/svn/trunk/new-gadget.xml.
Note that to simply reference (read) files in the repository, you use
the version of the repository URL that starts with http.
You can create directory structures within your repository that will
be reflected in the URL. For example, if you add and commit a
new file under /a/b/c/new-gadget.xml,
the file is hosted at http://<project-name>.googlecode.com/svn/trunk/a/b/c/new-gadget.xml.
To learn more about project hosting on Google Code, visit the FAQ.