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 的写法是这样的：

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

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

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

< Content  type ="html" >
     <![CDATA[  

    <div id="content_div" style="font-size:12pt; padding:5px;">
        <script type="text/javascript">
            // Get userprefs   
            var prefs = new _IG_Prefs();
            // Based on user input, display personal greeting
            function displayGreeting (){
                // Create Date object   
                var today = new Date();  
                // Get current time.  
                var time = today.getTime(); 
                var salutation;

                // Based on the time of day, display an appropriate greeting  
                var hour = today.getHours();  
                if (hour < 12)      
                    salutation = "Morning";  
                else if (hour > 17)    
                    salutation = "Evening"; 
                else salutation = "Afternoon";

                // Build HTML string to display message 
                var html = "";   
                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><h2>Good " + salutation + ", " + prefs.getString("myname") + "!!!</h2><br>"; 

                // If the "Show Photo?" checkbox is checked, display photo.  
                if (prefs.getBool("mychoice")==true)      { 
                    html += '<img src="' + prefs.getString("myphoto") + '">';     
                }    
                _gel("content_div").innerHTML = html;  
            }  
            _IG_RegisterOnloadHandler(displayGreeting); 
        </script>
     ]]>
</ 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 >