Google 协作平台的小工具

在 Google，小工具是可嵌入到网页和其他应用（包括 Google 协作平台）中的 HTML 和 JavaScript 应用。借助这些小工具，您可以将网站外部和动态内容（例如小型应用和数据库驱动的列表）与文字和图片结合起来，从而提供无缝的用户体验。

每个 Google 协作平台网页都是一个可能的小工具容器。此外，Google 协作平台提供了 Data API，可与 Google 小工具结合使用，从而创建功能强大的应用。这意味着，作为一名小工具开发者，您可以利用传统版 协作平台 API 为其他 Web 开发者及其受众群体构建引人入胜的工具，也可以自己使用。

当您构建适用于 Google 协作平台的小工具后，数百万活跃用户即可使用它。您只需将自己的小工具提交给我们，它就会展示在相应位置，以便用户轻松地浏览、配置您的小工具并将其添加到他们的网站中。

现在，您知道了 {sites_name_short} 是一个很棒的小工具分发平台，还等什么呢？立即开始为 Google 协作平台构建小工具！

网站小工具概述

一般来说，小工具是一些小实用程序，可生成外部信息或将外部信息提取到网页中。简单来说，小工具就是一个很小的 .xml 文件，它可以检索信息，并能够同时在多个网页中使用这些信息。在 Google 协作平台中，添加小工具会生成一个 iframe，作为这些外部信息的渠道。一些小工具的功能不仅限于此，即通过其他网站的信息的 iframe。

更高级的小工具会收集动态内容，并为 Google 协作平台网页中的交互式应用提供支持。请参阅示例小工具。

小工具包含以下组件：

• 小工具规范文件 - 一种封装 HTML 和 JavaScript 函数的 .xml 文件。
  
• 容器页面 - 在其中插入小工具的网页，在本例中为 Google 协作平台。
  
• 外部数据源 - 这是可选内容，可能与 .xml 文件位于同一位置，但小工具规范通常通过 HTTP 对其进行调用，以便提供其结果。

网站的所有查看者都可以使用专为 Google 协作平台打造的小工具。它们往往具有互动性，侧重于提取动态内容而不是展示，并且与网站内容相辅相成。

日历小工具就是一个很好的区别示例。默认情况下，Google 协作平台中的个性化日历小工具可能会显示已登录用户的日历，而 Google 协作平台中的日历小工具可能允许协作者从各种针对特定地点的日历中进行选择。

借助协作平台小工具，您可以在单个页面显示来自外部来源（例如来自不同但相关的性能信息中心的实时图表）的多条信息，以及直接在协作平台中发布的说明文本。这样可以节省视觉版面，同时在同一视图中收集有关同一主题的不同信息。利用小工具，您还可以包含 Google 协作平台安全检查会阻止的动态内容。

警告：使用旧版 Gadget API 构建的小工具可以在 Google 协作平台中运行，但不受官方支持。内置小工具和基于 Feed 的小工具同样不受支持。因此，Google 建议您使用当前的 Gadgets.* 构建所有 Google 协作平台小工具。API 来创建这些实例。有关说明，请查看以下帖子：
http://igoogledeveloper.blogspot.com/2009/09/more-things-change-more-they-stay-same.html

示例小工具

下面是一个简单但热门的“包含”小工具，只不过是一个用于传递其他网络内容的 iframe：

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Include gadget (iframe)" title_url="http://sites.google.com/"
          description="Include another web page in your Google Site"
          thumbnail="https://www.gstatic.com/sites-gadgets/common/images/sites-icon-gadget-thumb.png"
          screenshot="https://www.gstatic.com/sites-gadgets/common/images/sites-icon-gadget-ss.png"
          height="800" width="600" author="Google">
    <Require feature="dynamic-height"/>
  </ModulePrefs>
  <UserPref name="iframeURL" display_name="URL to content" required="true"/>
  <UserPref name="scroll" display_name="Display scrollbar" default_value="auto" datatype="enum">
    <EnumValue value="auto" display_value="Automatic"/>
    <EnumValue value="no" display_value="No"/>
    <EnumValue value="yes" display_value="Yes"/>
  </UserPref>
  <Content type="html" view="default,canvas">
  <div id='dest'><img src="http://www.google.com/ig/images/spinner.gif"></div>
  <script type="text/javascript">
  gadgets.util.registerOnLoadHandler(doRender);

  function doRender(){
    // setup variables
    var prefs = new gadgets.Prefs();
    var iframeURL = prefs.getString('iframeURL');
    var scroll = prefs.getString('scroll');
    var height = 800;
    var width = 600;

    if (gadgets.window) {
      var viewport = gadgets.window.getViewportDimensions();
      if (viewport.width) {
        var width = viewport.width;
      }
      if (viewport.height) {
        var height = viewport.height;
      }
    }

    var iframe = document.createElement('iframe');
    iframe.setAttribute('width', width + 'px');
    iframe.setAttribute('height', height + 'px');
    iframe.setAttribute('frameborder','no');
    if(scroll){
      iframe.setAttribute('scrolling', scroll);
    }
    iframe.setAttribute('src', iframeURL);

    // set the slideshow to the placeholder div
    var dest = document.getElementById('dest');
    dest.innerHTML = '';
    dest.appendChild(iframe);
  }
  </script>
  </Content>
</Module>

请参阅使用入门：小工具*。API - 了解小工具标记和预期内容的完整说明。

托管您的小工具

无论您的小工具是什么，其文件都必须位于万维网上才能找到和使用。任何可通过 HTTP 访问的在线位置无需身份验证即可。请注意，您的小工具必须在公共目录中发布才能被选中。否则，用户必须直接插入网址来嵌入该网址。

以下是您的小工具托管选项：

• App Engine - 能够存储小工具需要的所有文件。确实需要进行一些设置，即创建项目和上传后续文件。但可以轻松扩展到大量用户。您可以创建一个应用来存储您的所有小工具，再创建一个应用来提供静态文件，包括一个类似如下的 app.yaml 文件：

  application: <your app name>
  version: 1
  runtime: python
  api_version: 1
  
  handlers:
  - url: /.*
    static_dir: static
  

  如果您将所有小工具文件放在静态目录中，则可编辑本地目录中的文件，并在您每次做出更改时将其部署到 App Engine。如果您有一个文件 /static/gadget.xml，其网址将是：http://<您的应用名称>.appspot.com/static/gadget.xml

• 您选择的任何在线位置 - 完全在您控制范围之内，但也由您承担全部责任。如果您的服务器出现服务中断，可能会导致小工具用户中断。

构建小工具

小工具只是 HTML 以及（可选）封装在 XML 中的 JavaScript、Flash 或 Silverlight。小工具开发者指南提供了关于构建您自己的小工具的所有必要详细信息。此外，OpenSocial 模板也可以用于快速构建小工具中的社交应用。

以下是构建 Google 协作平台小工具的大致步骤：

1. 确定托管小工具的位置。请参阅托管您的小工具 部分，了解各个选项的说明。
2. 使用您选择的文本编辑器创建一个将用作规范的新 .xml 文件。
3. 确定内容类型（HTML 或网址），然后在小工具 .xml 文件中进行指定，如下所示：
   <Content type="html">
   这几乎总是 HTML，因为它假定所有内容都直接在 .xml 文件中提供。但是，如果您打算在单独的文件中提供内容，请使用网址内容类型。有关两者区别的完整说明，请参阅选择内容类型。
4. 在小工具 .xml 文件或规范调用的单独文件中创建内容。查看查看示例小工具部分，了解检查现有小工具的方法。
5. 定义可由用户更改的小工具的基本首选项。有关说明，请参阅定义用户偏好设置。如需提供更高级的配置，请参阅允许高级用户配置部分。
6. 定义只有小工具作者可以更改的模块偏好设置。有关详情，请参阅定义小工具偏好设置。
7. 测试小工具。有关说明，请参阅测试小工具部分。

嵌入您的小工具

您可以将 Google 小工具嵌入 Google 协作平台网页，方法是从 Google 协作平台小工具目录（与 iGoogle 小工具目录同步）中选择该小工具，或直接添加其网址。

要在 Google 协作平台中嵌入小工具，请执行以下操作：

1. 转到将包含新小工具的“网站”页面。
2. 打开相应页面进行修改。
3. 选择“插入”>“更多小工具”。
4. 搜索该小工具，然后从左侧的类别中选择该小工具，或者点击通过网址添加小工具并将网址粘贴到 .xml 文件中。然后点击添加。
   提示：您可以使用同一个“通过网址添加小工具”方法嵌入来自 iGoogle 和其他任何在线平台的小工具。
5. 指定小工具的尺寸，从可用设置中选择，然后点击确定。该小工具即会添加到您的网页中。
6. 保存该网页，以便在网站中查看和测试您的小工具。

测试您的小工具

构建小工具后，您应该在使用之前进行全面测试，并允许他人这样做。通过创建一个或多个测试 Google 协作平台并嵌入您的小工具，手动测试您的小工具。请参阅嵌入小工具部分了解具体步骤。小工具的功能和外观取决于包含它的网站。因此，调试小工具的最佳方法是在实际 Google 网站的上下文中进行测试。请尝试在各种 Google 协作平台主题之间切换，以确保您的小工具在每个主题中都能正确显示。

在测试您的小工具时，您会不可避免地会发现错误，并且需要对您的小工具 .xml 文件进行更正。在调整 XML 时，您应停用小工具缓存。否则，您所做的更改将不会显示在页面上。除非您指示 Google 协作平台不要缓存小工具规范，否则系统会对其进行缓存。要在开发过程中绕过缓存，请将以下内容添加到包含该小工具的“网站”页面网址末尾（而不是小工具规范 .xml 文件的网址）：

 ?nocache=1

Google 协作平台提供了用于添加和配置小工具的标准用户界面。在添加小工具时，系统会显示预览，并显示所有可配置的 UserPref 参数。测试如何更新各种配置值并将您的小工具添加到测试网站。确认您的小工具在网站上能够按预期运行。您应测试自己定义的任何 UserPref 是否都可以由网站管理员正确配置。

然后，请参阅“发布小工具”的“准备发布”部分，以便进行其他测试。

允许高级用户配置

所有小工具都可能提供设置基本用户偏好设置的功能，通过小工具规范文件的 UserPref 部分完成。这些设置通常会影响尺寸、滚动条、边框、标题和小工具专用设置，如以下屏幕截图所示：

但在很多情况下，与标准 UserPref 组件相比，更高级的偏好设置对小工具而言是更好的选择。偏好设置通常需要包含自定义业务逻辑、验证或选择器等功能。通过小工具的 UserPref 部分生成的接口支持有限数量的数据类型（字符串、枚举等），因此无法验证网址或日期等输入。

此外，在查看器和编辑器相同的容器（如 iGoogle）中，小工具作者可以将配置作为标准视图的一部分进行扩展。在 Google 协作平台中，查看者并非总是编辑者，因此小工具作者无法保证查看用户有权更新首选项。社交容器（如 Google 协作平台）不允许任何用户修改偏好设置，只能允许作者修改。

在 Google 协作平台中，由 UserPref 生成的基本小工具偏好设置界面可替换为配置视图，其中可提供许多其他偏好设置和数据类型，如此处所示的屏幕截图所示：

在插入或修改时，系统会显示配置视图来代替 UserPref 设置，以便您使用自定义界面设置用户偏好设置。您还可以使用自定义输入元素，例如用于选择地图上的位置而不是输入地图坐标。

开发者可以使用标准 setprefs API 将偏好设置保存在此视图中。如需了解更多详情，请参阅小工具 XML 参考和“开发者基础知识”的“保存状态”部分。这些视图允许容器应用提供补充配置信息，并建立在小工具 .xml 规范文件中，其位于 UserPref 部分之后，起始标记类似于：

  <Content type="html" view="configuration" preferred_height="150">

例如，提供上述配置视图的 news.xml 小工具包含此部分：

<Content type="html" view="configuration" preferred_height="300">
<style type="text/css">
  .config-options {
    margin: 10px;
  }
  .label {
    font-weight: bold;
    width: 35%;
    vertical-align: top;
  }
  .gray {
    color:#666666;
  }
  html {
    font-family:arial,sans-serif;
    font-size:0.81em;
    font-size-adjust:none;
    font-style:normal;
    font-variant:normal;
    font-weight:normal;
    line-height:1.5;
  }
  a:link, a:visited, a:active { text-decoration: none }
</style>
  <img alt="Google Web Elements" src="http://www.google.com/webelements/images/web_elements_logo.gif"/>
  <table class="config-options">
  <tr>
  <td align="left" class="label">Size:</td>
  <td align="left">
  <select id="size" onchange="Update()">
  <option selected="selected" value="300x250">Medium rectangle (300x250)</option>
  <option value="728x90">Leaderboard (728x90)</option>
  </select>
  </td>
  </tr>
  <tr>
  <td align="left" class="label">Select sections:</td>
  <td align="left">
  <table>
  <tbody><tr>
  <td><input type="checkbox" onclick="Update()" id="sec_h" value="h"/> Top Stories</td>
  <td><input type="checkbox" onclick="Update()" id="sec_w" value="w"/> World</td>
  <td><input type="checkbox" onclick="Update()" id="sec_b" value="b"/> Business</td>
  </tr><tr>
  <td><input type="checkbox" onclick="Update()" id="sec_p" value="p"/> Politics</td>
  <td><input type="checkbox" onclick="Update()" id="sec_n" value="n"/> Nation</td>
  <td><input type="checkbox" onclick="Update()" id="sec_e" value="e"/> Entertainment</td>
  </tr><tr>
  <td><input type="checkbox" onclick="Update()" id="sec_t" value="t"/> Technology</td>
  <td><input type="checkbox" onclick="Update()" id="sec_s" value="s"/> Sports</td>
  <td><input type="checkbox" onclick="Update()" id="sec_m" value="m"/> Health</td>
  </tr></tbody>
  </table>
  </td>
  </tr>
  <tr>
  <td align="left" class="label">Or create one:</td>
  <td align="left">
  <input type="text" id="query" onchange="Update()"/>
  <br/>
  <span class="gray">Example: 2010 Olympics</span>
  </td>
  </tr>
  <tr>
  <td colspan="2">
  <div id="preview" style="margin-top:10px;overflow:auto;width:100%;">
  <iframe id="preview_ifr" frameborder="0" marginwidth="0" marginheight="0" border="0"
  style="border:0;margin:0;"
  scrolling="no" allowtransparency="true"></iframe>
  </div>
  </td>
  </tr>
  </table>
  <script type="text/javascript">
  var prefs = new gadgets.Prefs();

  function getSelectedTopics() {
    var selected = [];
    var topics = ['h', 'w', 'b', 'p', 'n', 'e', 't', 's', 'm'];
    for (var i = 0; i < topics.length; i++) {
      if (document.getElementById('sec_' + topics[i]).checked) {
        selected.push(topics[i]);
      }
    }
    return selected.join(',');
  }

  function setSelectedTopics(selected) {
    if (selected && selected.length >= 0) {
      var topics = selected.split(',');
      for (var i = 0; i < topics.length; i++) {
        document.getElementById('sec_' + topics[i]).checked = true;
      }
    }
  }

  function Update() {
    var topic = getSelectedTopics();
    var query = document.getElementById('query').value;
    var size = document.getElementById('size').value;

    var url = 'http://www.google.com/uds/modules/elements/newsshow/iframe.html?rsz=large&' +
        'format=SIZE&element=true';
    var iframe = document.getElementById('preview_ifr');
    url = url.replace(/SIZE/, size);
    if (topic.length > 0) {
      url += '&topic=' + topic;
    }
    if (query.length > 0) {
      url += '&q=' + encodeURIComponent(query);
    }
    iframe.src = url;
    if (size == '728x90') {
      iframe.style.width = '728px';
      iframe.style.height = '90px'
    } else {
      iframe.style.width = '300px';
      iframe.style.height = '250px';
    }
    prefs.set('size', size);
    prefs.set('topic', topic);
    prefs.set('query', query);
    gadgets.window.adjustHeight();
  }

  function Initialize() {
    var size = '__UP_size__';
    if (size.length > 0) {
      document.getElementById('size').value = size;
    }
    var query = '__UP_query__';
    if (query.length > 0) {
      document.getElementById('query').value = query;
    }
    setSelectedTopics('__UP_topic__');
    Update();
  }

  gadgets.util.registerOnLoadHandler(Initialize);
  </script>
  </Content>

您可以在此处找到本示例和其他具有配置视图的 Google 协作平台专用小工具：
https://www.gstatic.com/sites-gadgets/news/news.xml
http://gadgets.pardonmyzinger.org/static/qrcode.xml
https://www.gstatic.com/sites-gadgets/news/youtube_news.xml

遵循 Google 协作平台小工具的最佳做法

用户希望在网络上拥有良好形象的网站。请遵循以下最佳实践，确保您的小工具能够与 Google 协作平台中使用的众多主题无缝融合。如需详细了解如何创建小工具，请参阅小工具概览。本节的其余部分介绍特定于 Google 协作平台小工具的指南。

• 请不要在小工具规范或标题中放置敏感信息，因为公众可以看到您的小工具。例如，请勿包含内部项目名称。
• 为了尽可能降低您的小工具的曝光率，请不要将其提交到 iGoogle 小工具目录或其他任何公开列表服务。而应让所有用户仅通过网址添加该网址。此外，您还可以创建一个仅调用另一个文件来获取其内容的 网址 型小工具（而不是包含所有内容的典型 HTML 类型）。使用此直通选项时，仅会显示第二个文件的网址。有关 HTML 和网址小工具之间的区别，请参阅“开发者基础知识”的“选择内容类型”部分；如需了解其他遮盖小工具的方法，请参阅“编写您自己的小工具”的“小工具是公开的”部分。
• 最重要的是，请在多个不同的网站上测试您的小工具。修改网站的背景颜色、文字颜色和字体，以确保小工具能够与各种模板混合。

返回页首