Google Gadgets (3)：用户设置

毫无疑问，一些 Gadget 需要用户提供一些信息才能按照用户所期望的运行，比如一个 RSS 阅读器需要用户指定 RSS 源的地址，一个"推箱子"游戏可能需要用户指定开始的关卡(这样可以不用每次都从第一关开始)，等等。这些 "设置" 是在 XML 文件中用 <UserPref> 标签指定的，当 Gadget 运行的时候，它们被解析成 <input> 标签。各个用户的设置是永久保存的，并且不会被泄露出去(当然，如果在 Gadget 里面使用，这些数据还是有被泄露的可能。这就是为什么加载第三方 Gadget 时会出现警告的原因)。

我们来看一个例子。这个 Gadget 会根据当前的时间显示一句祝福语(和某些论坛的功能类似)。它需要用户设置以下内容：

• 需要祝福的人的名字(为了表现一种 "亲切感" ，这个名字也会显示在 Gadget 的标题栏中)；
• 为了和主题保持一致，用户可以指定这个 Gadget 的背景颜色；
• 是否显示一幅图片。

这个 Gadget 运行起来的效果类似这样：

Preferences for __UP_myname__
Good Morning, Rowan!!!
	由 Google 强力驱动的小工具

当用户选择 "修改设置" (在 Gadget 的标题栏右边的下拉箭头里)，将会看到类似于这样的选项：

要达到这样的效果， XML 的写法是这样的：

 1<?xml version="1.0" encoding="UTF-8" ?>
 2<Module>
 3  <ModulePrefs title="Preferences for __UP_myname__" height="250" />
 4  <UserPref name="myname" display_name="Name" required="true" />
 5  <UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/Rowan-headshot.jpg"/>
 6  <UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
 7  <UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" >
 8
 9    <EnumValue value="Red" />
10    <EnumValue value="Aqua" />
11    <EnumValue value="Lime" />
12    <EnumValue value="Yellow" />
13    <EnumValue value="Pink" />
14    <EnumValue value="Orange" />
15
16    <EnumValue value="White" />
17  </UserPref> 

注意：

• 第3行的 __UP_myname__ 会被动态替换成用户设置中的 myname 。
•  myname 这个设置被 "required" 关键字标记为 "必须的"，这使得只有用户指定了它的值以后，这个 Gadget 才会正确运行。Google 会提示用户对该选项进行设置。 
• bool 型变量(如 mychoice )会被解析为 checkbox 。 
• enum 型变量(如 mycolor )会被解析成 <select> 标签，每个 <EnumValue> 标签指定的值会被解析成这个 <select> 中的一个 <option> 标签。

下面是这个 Gadget 所使用的 <Content> 内容(即 HTML 和 JavaScript 语句)：


 1<Content type="html"> 
 2<![CDATA[ 
 3
 4
 5  <div id="content_div" style="font-size:12pt; padding:5px;">
 6
 7  <script type="text/javascript">
 8
 9    // Get userprefs
10    var prefs = new _IG_Prefs();
11
12    // Based on user input, display personal greeting
13    function displayGreeting (){
14      // Create Date object
15      var today = new Date();
16      // Get current time.
17      var time = today.getTime();
18      var salutation;
19
20
21      // Based on the time of day, display an appropriate greeting
22      var hour = today.getHours();
23      if (hour < 12)
24        salutation = "Morning";
25      else if (hour > 17)
26        salutation = "Evening";
27      else salutation = "Afternoon";
28
29
30      // Build HTML string to display message
31      var html = "";
32      var element = document.getElementById('content_div');
33      element.style.height=250;
34
35      // Set the background color according to the mycolor userpref
36      element.style.backgroundColor=prefs.getString("mycolor"); 
37
38      // Display a greeting based on the myname userpref
39      html += "<br><h2>Good " + salutation + ", " + prefs.getString("myname") + "!!!</h2><br>"; 
40
41
42      // If the "Show Photo?" checkbox is checked, display photo.
43      if (prefs.getBool("mychoice")==true)
44      {
45        html += '<img src="' + prefs.getString("myphoto") + '">'; 
46      }
47      _gel("content_div").innerHTML = html;
48    }
49    _IG_RegisterOnloadHandler(displayGreeting);
50  </script>
51]]> 
52</Content>

简单点说，要在 Gadget 里获取用户的设置，只需要按照这样来使用 JavaScript 脚本：

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

之后就可以正确地使用这些设置了。