学步园

一、什么是Google Gadgets以及它的使用环境

Google Gadgets (Google 小工具)，是一些比较实用的工具，这些工具运行在不同的浏览器里。Google网站对它的解释是：

“Google 小工具是一种用 HTML 构建的小型应用程序，通过 JavaScript、Flash 或 Silverlight 可获得动态行为。由于小工具可在多个站点和平台上运行，因此不同的位置中有特定的标签和库。所有这些都是核心 Google 小工具 API 的扩展，用来提供附加功能。”

1、最简单小工具示例

最简单的小工具仅有几行代码。该小工具显示信息“Hello, world!”：

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>  
<ModulePrefs title="hello world example" />   
<Content type="html">     
  <![CDATA[ 
       Hello, world!
     ]]>
  </Content> 
</Module>

请注意“Hello World”实例的以下内容：

小工具是在 XML 中指定的。第一行是 XML 文件起始的标准方式。这必须是文件的第一行。

<Module> 标签表示该 XML 文件包含小工具。

<ModulePrefs> 标签包含有关小工具的信息，如标题、说明、作者和其他可选功能。

<Content type="html"> 行表示小工具的内容类型是 HTML。

<![CDATA[ ...insert HTML here... ]]> 用于在小工具的内容类型为 html 时装入 HTML。它表明文本位于 CDATA 部分中的小工具解析器不应视为 XML。CDATA 部分通常包含 HTML 和 JavaScript。

</Content> 标识内容部分的结束。

</Module> 标识小工具定义的结束。

 

2、小工具中包含什么？

小工具 API 包含一些简单的构建快：XML、HTML 和 JavaScript。您仅需基本了解 HTML 便可开始使用。我们将教给您编写小工具所需了解的关于 XML 的所有内容。然后，当您编写更复杂的小工具时，如果您还不熟悉 JavaScript，您可能还想了解一些 JavaScript。

XML 是常用的标记语言。它以人和计算机都能读写的方式介绍了结构化数据。

XML 是用于编写小工具规范的语言。小工具仅是一个 XML 文件（放置在互联网上 Goolge 能找到的某个位置）。指定小工具的 XML 文件包含有关如何处理和提交小工具的说明。XML 文件可包含小工具的所有数据和代码，也可以包含找到元素其他内容的位置的引用（网址）。

HTML 是用于格式化互联网上的页面的标记语言。小工具的静态内容通常是用 HTML 编写的。HTML 看起来与 XML 类似，但它用于格式化网络文档而非介绍结构化数据。

JavaScript 是可用于向小工具添加动态行为的脚本语言。

3、小工具都用在什么地方？

Google网站上也对这些小工具的使用场合做了一些说明：

1、小工具可在 Orkut 上使用。

2、小工具可在 Google Maps (Mapplet) 上使用。

3、小工具可在 iGoogle 上使用。

4、小工具可通过 Google AdSense 运行。

5、小工具可在 Google 日历上使用。

而且可运行小工具的位置列表在不断扩展：

Google 产品

• iGoogle
• Google Apps 启动页面
• Google 桌面
• Google Maps
• Google 工具栏新增！
• Orkut 新增！
• Blogger
• Google 日历

第三方产品和站点

• MyAOL
• IBM websphere 门户网站
• RedHat JBoss 门户网站
• SUN 门户网站
• BEA Weblogic 门户网站

其他站点

• 任意网页

二、编写Google Gadget所用的代码结构

一个小工具就是一个XML文件，下面援引Google网站中对小工具代码中的XML结构进行解释：

以下部分介绍了用于指定小工具的 XML 文件的结构和内容。

1、小工具使用偏好

XML 文件中的 <ModulePrefs> 部分指定了小工具的特征，如标题、作者、首选大小等等。例如：

<Module>
<ModulePrefs title="Developer Forum" title_url="http://groups.google.com/group/Google-Gadgets-API"
height="200" author="Jane Smith" author_email="xxx@google.com"/>
<Content ...>
... content ...
</Content>
</Module>

小工具的用户不能更改这些属性。

下表列出了 <ModulePrefs> 属性：

属性	说明
title	提供小工具标题的可选字符串。该标题显示在 iGoogle 的小工具标题栏中。如果该字符串包含用户使用偏好替换变量，并且您打算将小工具提交至 iGoogle 内容目录，您还应提供 directory_title 以用于目录显示。
directory_title	提供应对 iGoogle 内容目录中的小工具显示标题的可选字符串。应仅包含要显示的文字文本，而不包含用户使用偏好替换变量。这是因为 iGoogle 内容目录显示小工具的静态视图，所以不能进行必要的替换以生成合理的标题。例如，如果小工具的标题是“Friends for __UP_name__”，则目录不能执行替换以为“ __UP_name__”提供合理的值。所以您仅将directory_title设置为“朋友”即可。
title_url	提供小工具标题链接至的网址的可选字符串。例如，您可以将标题链接至与小工具相关的网页。
description	描述小工具的可选字符串。
author	列出小工具作者的可选字符串。
author_email	提供小工具作者的电子邮件地址的可选字符串。您可以使用任何电子邮件系统，但是鉴于会收到大量垃圾邮件，因此不应使用个人电子邮件地址。一种方法是在小工具规范中使用 helensmith.feedback+coolgadget@gmail.com 形式的电子邮件地址。 Gmail 会省略加号 (+) 后的所有内容，所以该电子邮件地址可解释为 helensmith.feedback@gmail.com。 您可以在此处创建 Gmail 帐户。
author_affiliation	表示作者所属机构的可选字符串（如“Google”）。该属性对于包含在 iGoogle 内容目录中的小工具来说是必需的。
author_location	作者的地理位置，例如“美国加利福尼亚州山景城”。
screenshot	给出小工具屏幕截图的网址的可选字符串。该图片必须位于不能被 robots.txt 拦截的公共网站上。PNG 是首选格式，GIF 和 JPG 也可接受。小工具屏幕截图的宽度应为 280 像素。屏幕截图的高度应为使用小工具时的“正常”高度。有关屏幕截图指导方针的更多讨论内容，请参阅“发布至 iGoogle 内容目录”。
thumbnail	给出小工具缩略图的网址的可选字符串。该图片必须位于不能被 robots.txt 拦截的公共网站上。PNG 是首选格式，GIF 和 JPG 也可接受。小工具缩略图应为 120x60 像素。有关缩略图指导方针的更多讨论内容，请参阅“发布至 iGoogle 内容目录”。
height	指定小工具运行所在区域的高度的可选正整数。默认高度为 200。
width	指定小工具运行所在区域的宽度的可选正整数。默认宽度为 320。
scaling	指定在调整浏览器大小时是否保持小工具纵横比（高宽比）的可选布尔值。可自动纵向伸缩的小工具应将该属性设置为 True，而高度固定的小工具应将该属性设置为 False。默认为 True。
scrolling	内容超出给定空间时提供纵向和/或横向滚动条的可选布尔值。如果为 False，则会按照给定（这并不表示宽度不可组态）的高度和宽度修剪内容。默认为 False。
singleton	指定用户是否可从目录中多次添加小工具的布尔值。默认为 True，这意味着默认情况下，小工具仅能添加一次。无论如何选择，目录均可处理该属性。例如，iGoogle 内容目录通过对已添加的小工具灰显文本“已添加”来处理 singleton="true"。请注意，对该属性的更改可能不会立即被目录接受。 该属性不会阻止用户通过开发人员小工具或“按网址添加”来多次添加小工具。因此，您仍然需要编写小工具来支持多次添加实例。
author_photo	对于作者页面，是至照片（首选 70x100 PNG 格式，但也支持 JPG/GIF）的网址。
author_aboutme	对于作者页面，是个人说明（请尽量保持在 500 个字符内）。
author_link	对于作者页面，是至您的网站、博客等的链接。
author_quote	对于作者页面，是您想要包含的摘录（请尽量保持在 300 个字符内）。

2、使用库

要使用某些小工具 API 功能（如动态高度或存储状态），您需要使用 <Require> 标签（在 <ModulePrefs> 内）来加载相应的 JavaScript 库。<Require> 标签有一个必需的属性，feature，其值指定了功能库。例如：

<ModulePrefs title="Set Userprefs Demo"> <Require feature="dynamic-height"/> <Require feature="setprefs" /> </ModulePrefs>

有关功能库的详细信息，请参阅“JavaScript 参考”。

3、指定区域

您可以使用 <ModulePrefs> 下的 <Locale> 标签来指定小工具所支持的区域。您也可以用它来指定消息包，如小工具与 i18n 中所述。

例如，该代码段指定了两个不同的区域：

<ModulePrefs ...> <Locale lang="en" country="us" /> <Locale lang="ja" country="jp" /> </ModulePrefs>

“lang”（语言）和“country”属性都是可选的，但您必须为每个 <Locale> 至少指定一个属性。如果您忽略了任一属性，则值等于“*”和“ALL”。如果您指定了国家/地区而未指定语言，则将认为您的小工具支持与该国家/地区相关的所有语言。类似地，如果您指定了语言而未指定国家/地区，则将认为您的小工具支持与该语言相关的所有国家/地区。

语言的有效值是 ISO639-1 两位语言代码，国家/地区的有效值是 ISO 3166-1 alpha-2 代码。

有一些常用语言规则的例外情况：

• 简体中文： lang="zh-cn"（通常，country=“cn”）。
• 繁体中文：lang="zh-tw"（中国台湾和香港特别行政区通常分别是 country=“tw”或“hk”）。

下表列出了 <Locale> 属性：

属性	说明
lang	表示与区域相关的语言的可选字符串。
country	表示与区域相关的国家/地区的可选字符串。
messages	指向消息包的网址的可选字符串。消息包是包含给定区域的翻译字符串的 XML 文件。有关详细信息，请参阅“小工具和国际化”。
language_direction	设置小工具方向的可选字符串。其值可以是“rtl”（从右到左）也可以是“ltr”（从左到右）。默认为“ltr”。该属性允许您创建既支持从左到右语言又支持从右到左语言的小工具。有关该主题的更多讨论内容，请参阅“创建双向小工具”。您也可以与language_direction配合使用以下替换变量： __BIDI_START_EDGE__：当小工具处于 LTR 模式时，该值为“左”；当小工具处于 RTL 模式时，该值为“右”。 __BIDI_END_EDGE__：当小工具处于 LTR 模式时，该值为“右”；当小工具处于 RTL 模式时，该值为“左”。 __BIDI_DIR__：当小工具处于 LTR 模式时，该变量的值为“ltr”；当小工具处于 RTL 模式时，其值为“rtl”。 __BIDI_REVERSE_DIR__：当小工具处于 LTR 模式时，该变量的值为“rtl”；当小工具处于 RTL 模式时，其值为“ltr”。

如果您不指定 <Locale>，则仅默认为美国 + 英语。

4、指定兼容性要求

不是所有的小工具都能在所有环境中运行。小工具可能需要特殊的浏览器或软件。您可以使用 <MayRequire> 标签来提供有关小工具的特殊要求的信息。例如：

<ModulePrefs ...> <MayRequire type="plugin" value="quicktime"/> <MayRequire type="browser" value="firefox" min_version="1.06"/> <MayRequire type="platform" value="windows"> This gadget uses a Windows API. </MayRequire> </ModulePrefs>

下表列出了 <MayRequire> 属性：

属性	说明
type	表示要求类型的必选字符串。支持的类型包括"platform”、"browser"和"plugin"。
value	提供类型值的必选字符串。例如 type="plugin" value="flash"。
min_version	表示必选项的最小版本号的可选字符串。
cdata	提供要求相关的附加信息的可选字符串。

5、用户使用偏好

某些小工具需要给用户一个提供用户特定信息的途径。例如，天气小工具可能要求用户提供其邮政编码。XML 文件中的用户使用偏好 (<UserPref>) 部分介绍了可在小工具运行时转换为用户界面控件的用户输入字段。

下表列出了 <UserPref> 属性：

属性	说明
name	用户使用偏好必需的“符号”名称；如果未定义display_name，则在编辑期间对用户显示。必须仅包含字母、数字和下划线，即，常规表达式 ^[a-zA-Z0-9_]+$。必须是唯一的。
display_name	在编辑窗口中显示在用户使用偏好旁边的可选字符串。必须是唯一的。
urlparam	作为内容 type="url" 的参数名称传送的可选字符串。
datatype	表示该属性的数据类型的可选字符串。可以是string、bool、enum、hidden（不可见或用户不可编辑的字符串）、list（由用户输入生成的动态数组）或location（用于基于 Google 地图的小工具）。默认为 string。
required	表示该用户使用偏好是否为必需的可选布尔变量（true 或 false）。默认为 false。
default_value	表示用户使用偏好的默认值的可选字符串。

可使用用户使用偏好 JavaScript API 来从小工具访问用户使用偏好，例如：

<script type="text/javascript"> var prefs = new _IG_Prefs(); var someStringPref = prefs.getString("StringPrefName"); var someIntPref = prefs.getInt("IntPrefName"); var someBoolPref = prefs.getBool("BoolPrefName"); </script>

6、枚举数据类型

 

您可以为 <UserPref> datatype属性指定的一个值为enum。enum数据类型在用户界面中显示为选项菜单。您可以使用 <EnumValue> 指定菜单内容。

 例如，该 <UserPref> 允许用户设置游戏的难易级别。显示在菜单中的每个值（简单、中等和困难）是使用 <EnumValue> 标签来定义的。

<UserPref name="difficulty" display_name="Difficulty" datatype="enum" defaultvalue="4"> <EnumValue value="3" displayvalue="Easy"/> <EnumValue value="4" displayvalue="Medium"/> <EnumValue value="5" displayvalue="Hard"/> </UserPref>

下表列出了 <EnumValue> 属性：

属性	说明
value	提供唯一值的必选字符串。除非提供display_value，否则该值显示在用户使用偏好编辑框的菜单中。
display_value	显示在用户使用偏好编辑框的菜单中的可选字符串。如果您不指定display_value，则value显示在用户界面中。

7、内容部分

<Content> 部分定义了内容类型，是包含自身内容还是引用外部内容。<Content> 部分是小工具属性和用户使用偏好与编程逻辑和格式化信息结合成为可运行小工具的地方。有关内容类型的更多讨论内容，请参阅“选择内容类型”。

下表列出了 <Content> 属性：

属性	说明
type	给出内容类型的可选字符串。可能值包括 html 和 url。默认为 html。
href	提供目标网址的字符串。需要 type="url"，而不允许使用其他内容类型。
cdata	可选字符串。对于 HTML，包含要提交至 iFrame 中的原始 HTML。

 

三、编写自己的小工具

1、基本步骤

以下是创建和部署小工具要遵循的基本步骤：

1. 可使用任何文本编辑器来编写小工具规范，并将其托管在公共网络服务器上。
2. 将您的小工具添加至某容器，如 iGoogle 或 Orkut。容器是能运行小工具的应用程序或站点。

2、小工具分析

您理解了如何编辑和发布小工具后，就可以在小工具规范中包含更多高级功能。XML 小工具规范包含 3 个主要部分：

• 内容部分。<Content> 部分是小工具实际工作的地方。在其中可以指定小工具类型、编程逻辑和决定小工具外观的常用 HTML 元素。
• 用户使用偏好。<UserPrefs> 部分定义了允许用户指定小工具设置的控件。例如，个人欢迎小工具可为用户提供文本字段来指定其姓名。
• 小工具使用偏好。XML 文件中的 <ModulePrefs> 部分指定了小工具的特征，如标题、作者、首选大小等等。

注意：在小工具规范中的 XML 属性中，您需要“转义”（即正确编码）某些字符以正确地对其进行解释。有关详细信息，请参阅“转义特殊字符”。

编写小工具时，您应从 <Content> 部分开始。

（1）定义内容

<Content> 部分代表小工具的“大脑”。<Content> 部分定义了内容类型，是包含自身内容还是链接至外部内容。<Content> 部分是小工具属性和用户使用偏好与编程逻辑和格式化信息结合成为可运行小工具的地方。

创建小工具最简单的方法：仅需将 HTML（或者 JavaScript 或 Flash）放置到 <Content> 部分即可。有经验的网络开发人员可以阅读“选择内容类型”以获取与访问控制、远程托管、使用备用脚本语言和其他主题相关的其他选项。

以下是一个简单的示例小工具。该小工具显示了可点击的照片（可在新 HTML 网页中打开相册）：

 

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Go to Photo Album" height="250" scaling="false" />
  <Content type="html">
  <![CDATA[ 
    <div style="text-align:center"><a
      id="Riggs" title="My Photo Album" target="_blank" 
      href="http://picasaweb.google.com/doc.examples/ShelfBoy">      <img border="0" alt="Photo" src="http://doc.examples.googlepages.com/Riggsie-OP.jpg"       title="Click Here."></a>    </div>
  ]]> 
  </Content>
</Module>

 

 

（二）定义用户使用偏好

某些小工具需要给用户一个提供用户特定信息的途径。例如，游戏小工具可能允许用户输入首选的难易程度。XML 文件中的用户使用偏好 (<UserPref>) 部分介绍了可在小工具运行时转换为用户界面控件的用户输入字段。用户使用偏好是永久存储的。

例如，该小工具按时间来显示个人欢迎。使用户可以指定以下内容：

• 欢迎时使用的名称。该名称也显示在标题栏中。
• 背景颜色。
• 是否显示照片。

这就是当用户点击编辑修改用户使用偏好时小工具的外观。

在运行小工具时转换为用户界面控件的用户使用偏好在 XML 规范中定义，如下所示：

 

 

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="250" />  
<UserPref name="myname" display_name="Name" required="true" />  
<UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>  
<UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>  
<UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" >
    <EnumValue value="Red" />
    <EnumValue value="Aqua" />
    <EnumValue value="Lime" />
    <EnumValue value="Yellow" />
    <EnumValue value="Pink" />
    <EnumValue value="Orange" />
    <EnumValue value="White" />
</UserPref> 

 

 

注意以下内容：

• 文件的第 3 行包含文本 title="Preferences for __UP_myname__"。 运行小工具时，为用户偏好 myname 提供的值将以动态方式替换为 __UP_myname__。
• myname 用户使用偏好标记为“必填”。如果用户尝试运行小工具而不为该字段提供值，则用户使用偏好编辑框会保持打开状态，直到提供值为止。
• 用户使用偏好 mychoice 有 bool 数据类型。它在用户界面中显示为复选框。
• 用户使用偏好 mycolor 有 enum 数据类型。EnumValues 的列表指定了用户使用偏好编辑框的下拉菜单中显示的选项。

以下是一个完整的小工具，包括为小工具显示欢迎的 JavaScript：

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="400"/> 
  <UserPref name="myname" display_name="Name" default_value="Rowan"/>
  <UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
  <UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
  <UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" >
    <EnumValue value="Red" />
     <EnumValue value="Aqua" />
     <EnumValue value="Lime" />
     <EnumValue value="Yellow" />
     <EnumValue value="Pink" />
     <EnumValue value="Orange" />
     <EnumValue value="White" />
   </UserPref>
   <Content type="html"><![CDATA[
   <div id="content_div"></div>
   <script type="text/javascript">
   // Get userprefs
   var prefs = new gadgets.Prefs();

   function displayGreeting () {
     // Get current time
     var today = new Date();
     var time = today.getTime();
     var html = "";
  
     // Based on the time of day, display an appropriate greeting
     var hour = today.getHours();
     var salutation = "Afternoon";
     if (hour < 12) {
       salutation = "Morning";
     } else if (hour > 17) {
       salutation = "Evening";
     }

     // Set the background color according to the mycolor userpref
     var element = document.getElementById('content_div');  
     element.style.height=250;
     // Set the background color according to the mycolor userpref   
     element.style.backgroundColor=prefs.getString("mycolor"); 

     // Display a greeting based on the myname userpref
     html += "<br><FONT SIZE=6>Good " + salutation + ", " +
           prefs.getString("myname") + "!!!<br><br></FONT>";

     // If the "Show Photo?" checkbox is checked, display photo.
     if (prefs.getBool("mychoice") == true) {
       html += '<img src="' + prefs.getString("myphoto") + '">';
     }
     element.innerHTML = html;
   }
   // Pass the userprefs for this module instance to the function
   // (allows users to include multiple module instances on their page)
   gadgets.util.registerOnLoadHandler(displayGreeting); 
  
   </script> 
   ]]>  
  </Content>
</Module>

 

如需所有 <UserPref> 属性的列表，请参阅“参考”。

可使用用户使用偏好 JavaScript API 来从小工具访问用户使用偏好，例如：

<script type="text/javascript">
  var prefs = new gadgets.Prefs();
  var someStringPref = prefs.getString("StringPrefName");
  var someIntPref = prefs.getInt("IntPrefName");
  var someBoolPref = prefs.getBool("BoolPrefName");
</script>

（三）

您可以使用 <ModulePrefs> 或 <UserPref> 部分中 __UP_userpref__ 格式的替换变量，其中 userpref 与用户使用偏好的名称属性匹配。小工具运行时，将相应用户使用偏好的字符串值替换为未转义的变量。例如，在本摘录中，用户在运行时为项目用户使用偏好提供的值替换为标题_网址字符串中的 __UP_projects__。