Google Gadgets API 入門 (3)

2007-01-07 Google Gadgets API 入門 (3)

■[Google Gadgets] Google Gadgets API 入門 (3)

今回はユーザ・プリファレンス置換変数やユーザ・プリファレンスを取得/設定する方法について解説します。

ユーザ・プリファレンス置換変数

Gadget プリファレンスの値（<ModulePrefs> の属性値）にユーザ・プリファレンスで設定された値を利用することができます。以下の Gadget では、ユーザ・プリファレンスとして「名前」を設定することが可能になっています。そして、そこで設定された値が Gadget プリファレンスの値（<ModulePrefs> の title 属性の値）に反映されています：

この Gadget の Gadget-Spec は以下のようになっています：

<?xml version="1.0" encoding="UTF-8" ?>

<Module>
  <ModulePrefs title="こんにちは__UP_name__さん"
               title_url="http://www.example.com/userpage?name=__UP_name__" />
  <UserPref name="name" display_name="名前" default_value="ゲスト" />
  <Content type="html">
  <![CDATA[ <p>ユーザ・プリファレンス置換変数の使用例</p> ]]>
  </Content>
</Module>

Gadget プリファレンスの値（<ModulePrefs> の属性の値）に「__UP_<name>__」という文字列（<name> はユーザ・プリファレンスの名前）が含まれている場合、その部分が対応するユーザ・プリファレンスの値に置き換えられます。この「__UP_<name>__」のことを「ユーザ・プリファレンス置換変数」と呼びます。上の例では <ModulePrefs> の title と title_url の値にユーザ・プリファレンス置換変数が使用されています。

ユーザ・プリファレンスの取得/設定

以下の画像は前回の記事で使用した、ユーザ・プリファレンスの値をユーザが入力するときの様子を表したものです：

この画像では、入力した値が Gadget のコンテンツとして表示されています。このようにユーザ・プリファレンスを取得するには、Google Gadgets API が提供している JavaScript ライブラリを使用します。上の画像で示した Gadget の Gadget-Spec は次のようになっています：

<?xml version="1.0" encoding="UTF-8" ?>

<Module>
  <ModulePrefs title="Hello User Preferences" />
  <UserPref name="name" display_name="名前" default_value="ゲスト" />
  <UserPref name="flag" display_name="フラグ" datatype="bool" />
  <UserPref name="color" display_name="色" default_value="red" datatype="enum">
    <EnumValue value="red"   display_value="赤" />
    <EnumValue value="green" display_value="緑" />
    <EnumValue value="blue"  display_value="青" />
  </UserPref>
  <Content type="html">
  <![CDATA[
<script language="JavaScript">
var prefs = new _IG_Prefs(__MODULE_ID__)
var name  = prefs.getString("name")
var flag  = prefs.getBool("flag")
var color = prefs.getString("color")
document.write("名前：" + name + "<br />")
document.write("フラグ：" + flag + "<br />")
document.write("色：" + color + "<br />")
</script>
  ]]>
  </Content>
</Module>

ユーザ・プリファレンスを取得するには、最初に「new _IG_Prefs(__MODULE_ID__)」として prefs オブジェクト（ユーザ・プリファレンスにアクセスするためのオブジェクト）を作成します。引数の __MODULE_ID__ は実行している Gadget の識別子のためのプレースホルダです。そして、ユーザ・プリファレンスには、作成した prefs オブジェクトを通してアクセスします。prefs オブジェクトには以下の関数が含まれています：

_IG_Prefs(module_id)	prefs オブジェクトのコンストラクタです。引数 module_id には __MODULE_ID__ を指定します。
getString(name)	name に指定された名前のユーザ・プリファレンスの値を string 型として取得します。
getInt(name)	name に指定された名前のユーザ・プリファレンスの値を number 型として取得します。
getBool(name)	name に指定された名前のユーザ・プリファレンスの値を boolean 型として取得します。
set(name, value)	name に指定された名前のユーザ・プリファレンスの値を value に設定します。この関数を使用するには setprefs ライブラリを必要とします。
dump()	document.writeln() によって有効なユーザ・プリファレンスの値が全て出力されます。この関数はデバッグのために使用します。

set(name, value) に関する注意

set(name, value) を使用するには、次回以降に説明する Feature-specific ライブラリの一つである setprefs ライブラリの使用を宣言する必要があります。ここでは、Gadget-Spec に「<Require feature="setprefs" />」という一文を入れなければならない、ということだけ覚えておいてください。以下に例を示します：

<Module>
  <ModulePrefs ...>
    <Require feature="setprefs" />
  </ModulePrefs>
  ...
</Module>

次回予告

次回は、Google Gadgets API が提供する他の JavaScript 関数の紹介を行います。

紅孔雀