Gadgets API 开发人员工具

Gadgets API

• 提交小工具

---

• API 概述
• ▾小工具。* 开发人员指南
  • 使用入门
  • 编写您自己的小工具
  • 开发基础
  • 开发人员工具
  • 创建用户界面
  • 处理远程内容
  • 国际化
  • 非英语小工具
  • 发布小工具
  • XML 参考
• 小工具。* API 参考
• ▸更多小工具

---

• 常见问题解答
• 网上论坛
• 条款

开发人员工具

本文档提供了编程、调试和托管小工具的一般准则。

目录

1. 编程和调试提示
   1. 从基本框架开始
   2. 研究现有小工具
   3. 使用 Firefox JavaScript 控制台
   4. 确认您的假设
   5. 其他工具
2. 通过 Google 小工具编辑器进行托管
   1. 文件菜单命令
   2. 通过 GGE 发布您的小工具
3. 在 Google 代码上进行托管
   1. 创建新项目
   2. 校验项目
   3. 上传文件

编程和调试提示

部分小工具开发过程（或任意代码开发过程）解释了为何事情不总是按预期方向发展。本部分介绍了一些避免问题以及在发生问题时修正问题的基本技巧。

从基本框架开始

从基本框架开始是编程的一个基本原则。先构建一个基本的框架小工具，然后逐步编写。在每一阶段都进行测试，然后再进行下一阶段。使用该方法可以更轻松地了解您所做的更改在何时引起的问题。

研究现有小工具

作为小工具开发人员，您可用的最佳资源之一是现有小工具。访问内容目录并查看与您尝试执行的代码非常类似的小工具源代码。

使用 Firefox JavaScript 控制台

在开发过程中，您可以使用 Firefox 网络浏览器在 iGoogle 上测试您的小工具。如果小工具运行不正常，请打开 JavaScript 控制台（“工具”>“JavaScript 控制台”），选择“错误”，然后向下滚动以查看您的小工具是否有 JavaScript 语法错误。在每次测试之前，请务必清理控制台以清除旧的错误消息。

如果您使用其他类型的浏览器，请寻找您的浏览器支持的 JavaScript 控制台或调试器。

确认您的假设

在开发过程中确认您的假设可为您节省大量时间并减少大量无用功。是否确定变量具有您设想的值？是否确定数组包含元素？“看起来运行不正常”的函数是否有可能完全不响应调用？您可以通过在程序的不同点打印出状态消息来测试您的假设。例如，以下小工具具有print()函数，如果debug标记有非零值，该函数可将调试消息写入到debug_div：

<?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>

请注意：请参阅MiniMessages以获得有关小消息 API 的描述，它使您可以修改在小工具中显示的消息的行为和外观。

其他工具

以下 Firefox 插件可以帮助您在开发过程中更细致地洞察您的小工具：

• Firebug提供调试工具和 DOM 检查。
• Web Developer向浏览器添加包含网络开发人员工具的菜单和工具栏。

通过 Google 小工具编辑器进行托管

如果您没有权限访问服务器以存储小工具 XML 文件，那么可以使用 Google 小工具编辑器 (GGE)，它是快速编辑和托管小工具的出色工具。要使用 GGE，请确保您使用 Google 帐户登录（否则您将无法保存小工具）。例如，如果您将“Hello, world!”消息更改为“Hello, gadget developers!!”并使用“文件”>“另存为”以新名称保存小工具规范，GGE 将以您指定的名称为您托管新的小工具规范：

请注意：GGE 尚不完全支持gadgets.*API，因此并非所有功能都能使用。您可以使用 GGE 来编辑和托管文件，但无法预览小工具。

文件菜单命令

“编辑”标签具有一个“文件”下拉菜单，其中包括以下命令。GGE 使用您的Google 帐户来标识属于您的文件，因此您必须登录才能使用其中大部分命令。

命令 说明

打开	打开先前创建的小工具并通过 GGE 保存。
保存	保存正在编辑的小工具规范。如果以前没有保存过小工具，系统会提示您输入小工具的名称。当您在 GGE 中保存小工具时，GGE 会自动为您托管该小工具。在您发布小工具之前，需要将其托管在公共服务器上，并且 GGE 可以托管小工具并向您提供多种发布小工具的方式。
另存为	以输入的名称保存您正在编辑的小工具。
重命名	重命名正在编辑的小工具。仅在保存了小工具后才可用。
上传	使您可以浏览小工具资源的文件系统，并将它们保存到 GGE 环境中。可以上传小工具规范，也可以上传其他小工具资源（如图片文件）。将资源上传到 GGE 中之后，GGE 将托管它们。这使您可以通过引用它们的GGE 网址将其导入到小工具规范。
发布	“发布”菜单项向您提供以下选项以发布小工具： 添加到我的 iGoogle 页面 发布到 iGoogle 目录 添加到网页 仅在保存了小工具后该命令才可用（保存可以使 GGE 托管您的小工具）。有关详细信息，请参阅通过 GGE 发布您的小工具。
删除	显示您的 GGE 小工具列表并使您可以选择和删除它们。

通过 GGE 发布您的小工具

“文件”菜单上的“发布”命令向您提供以下选项以发布小工具：

• 添加到我的 iGoogle 页面- 这会将小工具添加到您的 iGoogle 页面。这是在开发过程中测试您的小工具的最简单方式。
• 发布到 iGoogle 目录- 将您转至 iGoogle 提交页面，并在表单中预填入小工具网址。您可以使用提交表单将您的小工具提交到iGoogle 内容目录。除非点击“发送”，否则不会提交您的小工具。如果您的小工具已经测试并修改，那么这已是小工具开发中的最后一步。您不需要执行此步骤便可使用您的小工具并将其与朋友共享。该选项适用于希望使其小工具对大量受众可用的开发人员。
• 添加到网页- 这将使您转至联合创建者页面。gadgets.*或 OpenSocial API 尚不支持联合。

GGE 的右上角提供了您的小工具的网址。可以通过点击该链接来获得完整的网址。

当开发和测试您的小工具时，我们建议您在尽可能多的不同环境中对其进行测试。测试并修改了您的小工具之后，您便可以选择将其分发给大量受众（通过将其提交到iGoogle 内容目录）。

在 Google 代码上进行托管

最轻松的托管小工具规范和小工具资源的方法是通过GGE。对于需要功能更完整的资源控制系统的开发人员，建议将您的小工具在 Google 代码上进行托管：http://code.google.com/hosting。该免费服务可以向作为小工具开发人员的您提供很多好处。其主要好处之一是通过 Subversion 进行版本控制，Subversion 是一种开源版本控制系统。使用 Subversion，您可以跟踪小工具的更改并保留不同的版本。可获得全部版本历史记录，其使您可以回滚或分析版本之间的差异。要了解有关 Subversion 的详情，请参阅Subversion book。

要在 Google 代码上托管您的小工具，首先要安装一个桌面程序（“Subversion 客户端”），它使您可以下载文件并将文件保存到code.google.com（“Subversion 库”）。大多数 Subversion 客户端都具有图形化用户界面，与命令行界面相比，它可以使您更轻松地与 Subversion 进行交互。可以根据您的操作系统选择不同的客户端。确保安装与您的系统兼容的客户端。下面是我们推荐的一些客户端：

• TortoiseSVN是一种易于使用的适用于 Windows 的 Subversion 客户端，可以将功能直接集成到 Windows Explorer 中。
• AnkhSVN是一种 Visual Studio 插件，可在 IDE 内部提供 Subversion 访问。
• ZigVersion是一种针对 Mac OS X 构建的 Subversion 客户端。
  
• RapidSVN是一种跨平台的 GUI Subversion 客户端。该客户端支持所有三种主要操作系统：Windows、Mac OS X 和 Linux。

此处是一个客户端和插件的完全列表。

在您的计算机上安装了 Subversion 之后，请遵循以下步骤开始使用 Google 代码来托管您的项目。

创建新项目

要创建新项目，请执行以下步骤：

1. 访问http://code.google.com/hosting并使用您的 gmail 帐户登录。如果您尚无帐户，请创建一个帐户。
2. 点击“创建新项目”。
3. 填写新项目的字段：
   • 为您的项目创建小写名称，例如my-gadgets。请记住，项目名称将成为项目网址的一部分且以后不能再更改。
   • 书写总结和说明。
   • 选择开源许可证。要了解详情，请访问开源许可证。
   • 可选步骤：分配标签以帮助其他用户找到您的项目。
4. 验证是否填写了所有必填字段，然后点击“创建项目”。
5. 已完成！您将被重定向到“项目主页”页面。验证您的网址是否类似于：http://code.google.com/p/<project-name>/

现在，您在code.google.com上拥有一个项目。已使用您的项目名称创建了 Subversion 库。点击“源”标签，然后点击“Subversion 库”链接。

网址应类似于http://<project-name>.googlecode.com/svn/。您应看到三个目录链接：分支、标签和主干。将文件上传到您的项目时，它们在/trunk文件夹进行替换。您可能需要将网址http://<project-name>.googlecode.com/svn/trunk/添加到书签以便以后参考。

校验项目

您需要先校验项目的 Subversion 库中的代码，然后才能上传文件。为了执行该校验，您需要三种信息：库网址（您需要使用以https而非http开头的版本）、用户名和密码。要找到该信息，请转至您项目的“源”标签 (http://code.google.com/p/<project-name>/source)。您应看到以下类似内容：

svn 校验 https://<项目名称>.googlecode.com/svn/trunk/ gadgets-test --username <用户名>

当提示时，请输入您的生成的SVN 密码。

继续时，请在浏览器中保持该页面处于打开状态，以便您可以根据需要检索相应的信息。

根据您所使用的 Subversion 客户端，实际校验的详情可能有所不同，但总体过程是相同的。本部分的说明假设您使用的是TortoiseSVN。

要校验项目，请执行以下步骤：

1. 在 Windows Explorer 中创建新文件夹并在文件夹中浏览。
2. 点击鼠标右键并选择“SVN 校验...”。
3. 输入您的库网址并点击“确定”。请注意，对于这一步，您必须使用以https开头的库网址版本。对于读写访问，这是必需的。如果您使用以http开头的版本，则您仅具有读取权限，而无法添加或提交文件。
4. TortoiseSVN 连接至服务器并尝试对您进行验证。将提示您输入用户名和密码。输入您的用户名和密码，选中“保存验证”，然后点击“确定”。如果未提示您输入用户名和密码，请返回步骤 3 并确保您的库网址是以https而非http开头。

此时客户端将连接并校验您的整个库。已完成！

如果校验成功完成，您应看到一个新的隐藏文件夹/.svn。请勿修改或删除该文件夹。

上传文件

项目经过校验后，您便可以使用 Subversion 命令开始将新文件夹和文件添加到目录。本部分的说明假设您使用的是TortoiseSVN。

要上传文件，请执行以下步骤：

1. 在<project-name>.googlecode.com/svn/trunk/目录下创建一个新文件（例如new-gadget.xml）并保存。可以将文件直接放在/trunk下，也可以放在/trunk下的子目录中。
2. 在文件上点击鼠标右键并选择“添加...”。这仅意味着添加了文件，但在此时文件尚未上传到服务器。如果您将文件放在尚未添加到库的目录中，则还需要添加该目录。添加目录时，还将添加该目录中的所有文件。同一规则也适用于提交更改。如果某个目录尚未被提交，则不能将文件提交到该目录。
3. 继续编辑文件，直至您准备好提交（上传）该文件。
4. 当您准备好提交文件时，请在文件上鼠标右键并选择“SVN 提交...”。

当提示时，请在消息日志中写下可选注释，然后点击“确定”。您的文件应开始传送到服务器。

文件传送到服务器后，提交（上传）即完成，并且立即可从http://<project-name>.googlecode.com/svn/trunk/new-gadget.xml在线获得该文件。请注意，如果只是引用（读取）库中的文件，则应使用以http开头的库网址版本。

您可以在库中创建目录结构，该目录结构将反映在此网址中。例如，如果您在/a/b/c/new-gadget.xml下添加和提交了一个新文件，则将在http://<project-name>.googlecode.com/svn/trunk/a/b/c/new-gadget.xml处托管该文件。

要了解有关托管在 Google 代码上的项目的详情，请访问常见问题解答。

返回页首