Developer Tools

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

Contents

1. Programming and Debugging Tips
   1. Start Small
   2. Study Existing Gadgets
   3. Use the Firefox JavaScript Console
   4. Confirm Your Assumptions
   5. Additional Tools
2. Hosting through the Google Gadgets Editor
   1. File Menu Commands
   2. Publishing Your Gadget from GGE
3. 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.

Study Existing Gadgets

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.

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 through the Google Gadgets Editor

If you do not have access to a server to store your gadget XML files, the Google Gadgets Editor (GGE) is a great tool to quickly edit and host gadgets. To use GGE, make sure that you are logged in with a Google account (or else you cannot save your gadget). For example, if you change the message "Hello, world!" to "Hello, gadget developers!!" and use File > Save As to save the gadget spec under a new name, GGE will host the new gadget spec for you under the name you specified:

File Menu Commands

The Edit tab has a drop-down File menu that includes the following commands. GGE uses your Google account to identify the files that belong to you, so you must be logged in to use most of these commands.

Publishing Your Gadget from GGE

The Publish command on the File menu gives you the following options for publishing your gadget:

• Add to my iGoogle page - This adds your gadget to your iGoogle page. This is the simplest way to test your gadget during development.
• Publish to iGoogle Directory - Takes you to the iGoogle submit page with your gadget URL pre-filled in the form. You can use the submit form to submit your gadget to the iGoogle content directory. Your gadget won't be submitted unless you click Send. This is the final step in gadget development, once your gadget is tested and polished. You do not need to take this step to use your gadget and share it with your friends. This option is for gadget developers who want to make their gadgets available to a mass audience.
• Add to a webpage - This takes you to the syndication creator page.

The URL for your gadget is provided in the upper right corner of GGE. You can get the full URL by clicking the link.

While you are developing and testing your gadget, we recommend that you test it in as many different environments as possible. Then once your gadget is tested and polished, you can choose to distribute it to a mass audience by submitting it to the iGoogle content directory.

Hosting on Google Code

The easiest way to host gadget specs and gadget resources is through GGE. 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