Google Gadgets API 入門 (2)

2007-01-06 Google Gadgets API 入門 (2)

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

前回は Gadget-Spec の作成から、パーソナライズド・ホームページに追加するまでの一連の作業について解説しました。今回は Gadget 開発に有用な Developer Gadget と、Gadget を定義する XML ファイルである Gadget-Spec について解説します。

Developer Gadget

Gadget を開発するときに便利なツールの一つに Developer Gadget というものがあります（以前は Developer Module と呼ばれていました）。上の画像は Developer Gadget のスクリーンショットです。Developer Gadget はページに組み込まれている Gadget の情報を表示するなどの機能を持ちますが、その中で最も重要となるのが Gadget-Spec のキャッシュの ON/OFF を切り替える機能です。キャッシュが ON になっていると、Gadget を組み込んだときに Gadget-Spec がキャッシュされます。デフォルトでキャッシュは ON になっており、その状態で Gadget-Spec を更新してもページに組み込まれた Gadget に反映されません。そのため、Gadget を開発している間はキャッシュを OFF にしておく必要があります。

Developer Gadget をパーソナライズド・ホームページに追加するには、ボタンをクリックしてください。

Gadget-Spec の構成

Gadget-Spec は以下に示す三つの要素によって構成されます：

Gadget プリファレンス（<ModulePrefs>）
ユーザ・プリファレンス（<UserPref>）
コンテンツ（<Content>）

Gadget プリファレンス（<ModulePrefs>）

前回、Gadget は Gadget-Spec と呼ばれる XML ファイルで定義すると述べました。そして、Gadget に関する情報（Gadget プリファレンス）は Gadget-Spec の <ModulePrefs> の属性で指定します。Gadget プリファレンスでは Gadget の名前や作者の情報などを指定することができます。また、Gadget の利用者はこの情報を書き換えることはできません。

以下に Gadget プリファレンスの指定例を示します：

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

<Module>
  <ModulePrefs title="Hello"
               title_url="http://www.example.com/"
               description="簡単な Gadget のサンプルです。" />
  <Content type="html">
    <![CDATA[ Hello, Google Gadgets! ]]>
  </Content>
</Module>

指定できる属性は多数ありますが、以下によく使われる属性を示します*1：

title	Gadget の名前を指定します。指定した値は Gadget のタイトルバーに表示されます。値には後述する「ユーザ情報置換変数」を含めることもできます。
title_url	Gadget のタイトル文字列（title 属性で設定した値）に設定するリンク URL を指定します。
description	Gadget の説明を指定します。
author	Gadget の作者を指定します。
author_email	Gadget の作者の E-Mail アドレスを指定します。
height	Gadget の縦幅を指定します。デフォルトでは 200 です。
width	Gadget の横幅を指定します。デフォルトは 320 です。注意として、この値は Gadget を一般の Web ページに埋め込んだ場合にのみ有効となります。パーソナライズド・ホームページではこの値は無視されます。
scrolling	true を指定すると、コンテンツに対して Gadget のサイズが小さい場合にスクロールバーを表示します。false を指定すると、Gadget のサイズにコンテンツがクリップされます。デフォルトでは false です。

ユーザ・プリファレンス（<UserPref>）

ユーザ・プリファレンスとは、ユーザが設定できる属性のことです。ユーザによって設定された情報を利用して Gadget の動作を適切なものに変更することができます。Gadget のタイトルバーの「edit」をクリックすると値を設定する領域が表示されます：

ユーザ・プリファレンスに関する指定は <UserPref> によって行います：

<?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[
    ...
  ]]>
  </Content>
</Module>

<UserPref> の属性には以下の値を指定することができます：

name	属性の名前を指定します。アルファベット、数字、アンダースコアだけを含む（正規表現で ^[a-zA-Z0-9_]+$ にマッチする）ユニークな値でなければなりません。
display_name	属性を入力する場所の横に表示される文字列を指定します。省略した場合は name で指定した値が使用されます。
urlparam	コンテンツにパラメータ名として渡す文字列を指定します。コンテンツ・タイプが url の場合に使用します。
datatype	属性のデータ・タイプを指定します。"string"、"bool"、"enum"、"hidden"、"location" のいずれかを指定することができます。デフォルト値は "string" です。
required	true を指定した場合は値の入力が必須となります（ユーザは値を入力するまで Gadget を利用することができません）。false を指定した場合は値の入力は省略可能となります。デフォルト値は "false" です。
default_value	属性のデフォルト値を指定します。

以下に datatype について補足します：

datatype="enum": 列挙型として、あらかじめ決められた値から選択させることができます。選択させる値は <UserPref> の入れ子の <EnumValue> で指定します。
datatype="hidden": 非表示項目となり、編集領域に表示されなくなります。このデータ・タイプは、ゲームのハイスコアなどユーザに直接変更されたくない属性に使用します。
datatype="location": Google Maps と連携する場合に使用するデータ・タイプです。

コンテンツ（<Content>）

Gadget の持つコンテンツに関する情報は <Content> の属性で指定します。

type	コンテンツ・タイプを指定します。"html"、"html-inline"、"url" のいずれかを指定します。デフォルト値は "html" です。
href	type="url" の場合の送り先 URL を指定します。
cdata	iframe に描画するための生の HTML を指定します。

コンテンツ・タイプには次のような違いがあります：

type="html": コンテンツに HTML を含みます。HTML には JavaScript コードなどを埋め込むことができます。最も柔軟なコンテンツ・タイプであり、通常はこのコンテンツ・タイプを選択します。Gadget は iframe として親ページ（パーソナライズド・ホームページ）に埋め込まれます。
type="html-inline": Gadget の親ページにアクセスする必要性がある場合に選択します。Gadget は iframe ではなく、通常の HTML として描画されます。
type="url": 外部 Web ページを取り込むタイプの Gadget で使用します。Google Gadgets API の提供する JavaScript ライブラリの使用に制限があります。このタイプは既存の Web アプリケーションを Gadget に変換する場合などに使用します。

次回予告

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

紅孔雀