Gadgets API

Developer Tools

This document provides general guidelines for programming, debugging, and hosting gadgets.

Contents

  1. Programming and Debugging Tips
    1. Start Small
    2. Use the Firefox JavaScript Console
    3. Confirm Your Assumptions
    4. Additional Tools
  2. Hosting on Google Code
    1. Creating a New Project
    2. Checking Out a Project
    3. Uploading Files

Programming and Debugging Tips

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.

Start Small

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.

Use the Firefox JavaScript Console

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.

Confirm Your Assumptions

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 gadgets.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
document.getElementById("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
document.getElementById("debug_div").innerHTML = debug_html;
}
}
gadgets.util.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.

Additional Tools

The following Firefox add-ons can help you get more fine-grained insight into your gadgets during development:

  • Firebug provides debugging tools and DOM inspection.
  • Web Developer adds to the browser a menu and toolbar containing web developer tools.

Hosting on Google Code

For open source 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 an open source 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:

  • TortoiseSVN is an easy-to-use Subversion client for Windows that integrates functionality directly into Windows Explorer.
  • AnkhSVN is a Visual Studio plug-in offering Subversion access within the IDE.
  • ZigVersion is a Subversion client built for the Mac OS X.
  • RapidSVN is a cross-platform GUI Subversion client.  This client supports all three major operating systems: Windows, Mac OS X, and Linux.

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.

Creating a New Project

To create a new project:

  1. Go to http://code.google.com/hosting and sign in with your gmail account.  If you don't have one yet, create one.
  2. Click Create a new project.
  3. Fill in the fields for your new project:
    • Create a lowercase name for your project, such as my-gadgets. Keep in mind that the project name becomes part of your project's URL and cannot be changed later.
    • Write a summary and description.
    • Choose an open source license. To learn more, visit Open-source license.
    • Optional step: assign labels to help other users find your project.
  4. Verify that all required fields are filled and click Create Project.
  5. You're done!  You are redirected to the Project Home page. Verify that your URL looks something like this: 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.

Checking Out a Project

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:

  1. Create a new folder in Windows Explorer and navigate inside the folder.
  2. Right click and choose SVN Checkout...
  3. Enter your repository URL and click OK. Note that for this step, you must use the version of the repository URL that is preceded by https. This is necessary for read-write access. If you use the version that starts with http, it only gives you read access, and you won't be able to add or commit files.
  4. TortoiseSVN connects to the server and attempts to authenticate you. You are prompted for a username and password. Enter your username and password, check Save authentication, and click OK. If you are not prompted for a username and password, go back to Step 3 and make sure that your respository URL begins with https, not http.

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.

Uploading Files

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:

  1. Create a new file under your <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.
  2. Right click on the file and choose Add....  This simply marks the file as added; at this point the file has not yet been uploaded to the server. If you put the file in a directory that hasn't been added to the repository yet, you also need to add the directory. When you add a directory, all of the files in it get added too. The same rules apply for committing changes. You can't commit a file to the repository if the directory it's in hasn't been committed.
  3. Continue editing the file until you are ready to commit (upload) it.
  4. When you are ready to commit the file, right click on the file and choose SVN Commit...

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.

Back to top

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.