编写您自己的小工具

使用入门向您介绍小工具。接下来要创建您自己的小工具。本文档将告诉您如何进行创建。

目录

  1. 基本步骤
  2. 小工具分析
    1. 定义内容
    2. 定义用户使用偏好
    3. 定义小工具使用偏好
  3. 记住:小工具是公共的
  4. 从此处去向何处

基本步骤

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

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

小工具分析

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

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

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

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

定义内容

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

创建小工具最简单的方法:仅需将 HTML(或者 JavaScript 或 Flash)放置到 <Content> 部分即可。有经验的网络开发人员可以阅读“选择 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>) 部分介绍了可在小工具运行时转换为用户界面控件的用户输入字段。用户使用偏好将被永久存储。

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

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

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

Userprefs 控件

在运行小工具时转换为用户界面控件的用户使用偏好在 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。它在用户界面中显示为复选框。
  • 用户使用偏好 mycolorenum 数据类型。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>

如需所有 JavaScript 函数的列表,请参阅“JavaScript 参考”。

用户使用偏好替换变量

您可以使用 <ModulePrefs><UserPref> 部分中 __UP_userpref__ 格式的替换变量,其中 userpref 与用户使用偏好的 name 属性匹配。小工具运行时,对应的用户使用偏好的字符串值会替换为未转义的变量。例如,在本摘录中,用户在运行时为 projects 用户使用偏好提供的值会被替换为 title_url 字符串中的 __UP_projects__

<Module>
  <ModulePrefs title="Build Monitor"
             title_url="http://www.example.com/build/status.php?__UP_projects__"/>
  <UserPref name="projects" display_name="project(s)"/>
  <Content ... />
</Module>

您可以在“用户使用偏好示例”中查看有关该内容的其他示例。

以下是使用用户使用偏好替换变量的一般准则:

  • 对于 <ModulePrefs> title 属性,请使用 __UP_name__。这是 HTML 转义的
  • 对于 <ModulePrefs> title_url 属性,请使用 __UP_name__。这是网址转义的
  • <Content> 部分中的 HTML 中,请使用 __UP_name__。这是 HTML 转义的。
  • <Content> 部分中的 JavaScript 代码中,请使用 gadgets.Prefs() 函数。

共享用户使用偏好

您可以使用 shareable-prefs 功能,以便让多个用户可以编辑小工具的用户使用偏好。这样,用户可以共享该小工具并看到彼此的编辑。例如,家庭成员可以共享一个杂物列表小工具,每个人都可以添加自己喜欢的东西。用户使用偏好数据是小工具语句中由 iGoogle 托管的部分。有关 Userprefs 的详细信息,请参阅《小工具 API 开发人员指南》。

要在多个用户之间共享小工具的 Userprefs,该小工具必须在 <ModulePrefs> 部分包括 <optional feature="shareable-prefs"/> 行。例如,该小工具使用 list 数据类型 Userprefs 填充杂物列表。

共享该小工具

以下是该小工具的代码:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs 
    title="Our Grocery List" 
    scrolling="true"> 
    <optional feature="shareable-prefs"/> 
   </ModulePrefs>
  <UserPref name="mylist" 
    display_name="Add items" 
    datatype="list" />
  <Content type="html">
  <![CDATA[ 
    <div id="content_div" style='color: #CC0099; font-family: serif; font-size: 120%;'></div>

  <script type="text/javascript"> 
    // Get userprefs
    var prefs = new gadgets.Prefs();
    // Get the list
    var items = prefs.getArray("mylist");  
    var html = "";
    // If there are no items in the list yet, display message.
    if (items.length == 0)
    {
      html += "Edit the userprefs to add items to the list.";
    }
    else {
      for (var i = 0; i < items.length ; i++) {
        var term = (items[i]);
        html += term + "<br />";
      }
    }
    document.getElementById("content_div").innerHTML = html; 
  </script>
  ]]> 
  </Content>
</Module>

将支持可共享的用户偏好的小工具添加到 iGoogle 后,您就可以让它成为可协作的小工具,如下所示。

步骤 1:点击您要共享的小工具上的三角形并选择“共享该小工具”。

共享该小工具

步骤 2:如果您是 Gmail 用户,请挑选您要与之共享的好友或键入他们的电子邮件地址。

共享该小工具

步骤 3:决定您是希望好友能够编辑您的小工具内容,还是仅通过其 iGoogle 页面查看小工具内容。

  • 如果选择“查看和编辑我的内容”,您的好友能够编辑该小工具的 Userprefs。他们所做的更改会反映在您所用的小工具版本,以及该小工具的任何其他共享版本中。
  • 如果选择“查看我的内容”,则您的好友无法修改该小工具,甚至无法修改他们本地的副本。只有您能够修改该小工具,并且您所做的更改会反映在该小工具的所有共享版本中。

点击“发送邀请”。您的好友会收到您邀请他们将该小工具添加到他们自己的 iGoogle 页面的电子邮件。

共享邀请

然后,您授权可编辑该小工具的好友便可以修改该小工具的 Userprefs,并将他们所做的更改发布到该小工具的所有共享版本中。

定义小工具使用偏好

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

<Module>
<ModulePrefs title="Today's Network Traffic" title_url="http://www/~rowan/gadgets/stats/"
height="200" author="Jane Smith" author_email="xxx@google.com"/>
<Content ...>
... content ...
</Content>
</Module>

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

如需 <ModulePrefs> 属性的完整列表,请参阅“参考”。

记住:小工具是公共的

请记住没有私有小工具。在公共网站上发布小工具后,人们便可以查找和查看小工具。请确保不要包括个人信息,如您的电话号码或个人电子邮件地址。

如果不希望公开小工具,该怎么办?Google 鼓励小工具作者共享他们的规范。然而,如果您希望在准备好发布小工具前最小化小工具的公共可见性,以下提示可供使用:

  • 请勿将小工具提交至内容目录或将其发布至类似 googlemodules.comhotmodules.com 的目录。
  • 如果人们找不到您的小工具,他们不太可能猜到此类网址。有些细节可避免被搜索引擎搜索到:
    • 确保您的网络服务器不提供包含您的文件的文件列表(这也避免了用户窥探)。
    • 确保没有指向您的小工具的网络超链接

从此处去向何处

如果您准备编写更复杂的小工具,请转至“开发基础”或返回至文档主页,以获取各个部分和主题的概述。

返回页首