ガジェットの仕様

初版: 2008 年 1 月 28 日

改訂: 2008 年 5 月 27 日

目次

1. 概要
2. コンプライアンス: ガジェット サーバー
   1. ガジェットのレンダリング要求
   2. ガジェットのメタデータ要求
   3. JavaScript 要求
3. コア JavaScript API
4. 推奨機能

概要

ガジェットは、HTML、CSS、JavaScript に基づくウェブ ベースのソフトウェア コンポーネントです。ガジェットを使えば、デベロッパーは、ウェブ上のどのような場所でも変更なしで動作する便利なウェブ アプリケーションを簡単に作成できます。ガジェットは宣言型の XML 構文を使って定義されます。この XML 構文はガジェット サーバーで処理され、スタンドアロンのウェブ ページ、ウェブ アプリケーション、他のガジェットなど、さまざまなコンテキストに埋め込むことのできる形式に変換されます。ガジェットの埋め込み先であるコンテキストをガジェット コンテナと呼びます。コンテナはガジェットのレイアウトとコントロールを管理すると共に、ガジェットに代わってさまざまな機能をサポートします。ガジェットを使って簡単なウィジェット、再利用可能なコンポーネント、本格的なアプリケーションなどを作成できます。また、ガジェットは他のガジェットを使ったり他のガジェットとやり取りすることもできます。

ガジェットとその XML は同義です。ガジェットの XML には、ウェブ アプリケーションの識別と表示に必要なすべての情報が含まれます。

メタデータ。ガジェット デベロッパーはガジェットの XML 内にいくつかのメタデータを指定します。たとえば作成者の情報、ガジェットのタイトル、ガジェットの説明などを指定します。このデータによってガジェット コンテナにガジェットを識別するためのヒントが与えられるだけでなく、ガジェット ディレクトリにデータが提供されます。ガジェット ディレクトリはデータベースです。ユーザーはこのデータベースを使って、ニーズに応じた便利なガジェットを簡単に見つけることができます。

ガジェット機能。ガジェットのすべての機能を意味します。これには、ガジェットを動作させるために必要な機能、またはオプションで使用できる機能 (利用可能な場合) があります。ガジェット機能は、ガジェットが採用する主要な拡張性メカニズムです。通常は、ガジェット機能を使って、新しい JavaScript API をレンダリング コードで使用できるようにガジェット サーバーに指示します。ただし、拡張された構文を追加するなど、ガジェット機能を使ってガジェットのコンテンツを操作することもできます。ガジェット機能の例としては、OpenSocial (ガジェットに豊富なソーシャル API セットを提供する)、dynamic-height (ガジェットが自身を適切な高さに調整できるようにする)、タブ (表形式の操作を使用する UI ライブラリ) などがあります。

ユーザー設定。ユーザー設定はキーと値のペアです。これは、ガジェットの設定と永続性を確保するための基礎です。ほとんどの場合、ユーザー設定はガジェット ユーザーによって操作され、その後、ユーザーに代わって永続的に保持されます。これにより、ガジェットは複数のレンダリング要求にわたって、操作されたユーザー設定にアクセスできます。通常、ガジェット コンテナは、ユーザー設定データの永続性と、そのデータを編集するためのインターフェースを提供します。

メッセージ バンドル。メッセージ バンドルを使えば、デベロッパーはガジェットを簡単にグローバル化できます。方法は、サポート対象として選択した言語に応じて名前とメッセージのマッピングを追加するだけです。このメッセージには、すべてのガジェットに提供されているコア JavaScript API を通じてプログラム的にアクセスできます。また、簡単な構文を使ってこのメッセージをコードに静的に代入することもできます。

コンテンツ。ガジェットによってレンダリングされる実際の HTML、CSS、JavaScript を提供します。2 種類の配信メカニズムがサポートされます。

1. HTML 型のガジェットは最も一般的に使用されており、豊富な機能セットのほとんどが組み込まれています。レンダリングと制御フローのためのコードを、ガジェット XML のコンテンツ セクションに直接指定します。このコードは、宣言されたガジェット機能から要求された機能は単純に使用可能であると見なします。オプションで宣言される機能の場合は、簡単な機能存在 API を使って機能が有効かどうかを確認することができます (または確認する必要があります)。 コードはガジェット サーバーによって処理され、IFRAME 内でレンダリングされます。
2. URL 型のガジェットは基本の URL を指定するだけです。ガジェット サーバーは、標準セットのパラメータをこの URL に追加して、ガジェットを IFRAME 内でレンダリングします。URL が指すサプリケーションには、レンダリング時に参照される JavaScript ライブラリを <script> タグを使って追加し、Gadget API を使用できるようにする必要があります。URL 型のガジェットでは一部の機能を使用できません。特に、HTML コードや JavaScript コードを直接操作する機能は使用できません。しかし、この型のガジェットは、既存のウェブサイトやアプリケーションをガジェットに変換するのにとても役に立つことが証明されています。

ガジェットの XML 内には複数のコンテンツ セクションを指定できます。それぞれのコンテンツ セクションは、1 つ以上のオプションのビュー ID を使ってラベル付けできます。これにより、レンダリングされるコンテンツに従ってガジェットの動作や表示を変えることができます。このコンテキストはガジェット コンテナにより提供されます。

このドキュメントでは、ガジェットの XML 構文と、互換性のあるガジェット サーバーでその XML 構文がどのように処理されるについて説明します。さらに、レンダリング時にすべてのガジェットで使用可能であるべき、コア JavaScript API について説明します。このコア API のみをサポートすることでコンプライアンスは達成できますが、これをサポートすることでガジェット サーバーの有用性が制限されます。ガジェット サーバーはできるだけ多くの機能をサポートする必要があります。このドキュメントの最後に、広く使用されている推奨機能を紹介します。

コンプライアンス: ガジェット サーバー

サーバーをガジェット準拠にするには、以下に説明するように、サーバーがガジェットのレンダリング要求と JavaScript 要求を満たすことができる必要があります。またサーバーは、以下に説明するように、ガジェットのメタデータ要求を満たすことができる必要があります。

ガジェットのレンダリング要求

コア Gadget API は、ガジェット XML を、ブラウザ (通常は IFRAME) 内でレンダリングできるコンテンツに変換します。

入力:

• ガジェット XML。通常は、ウェブ上のファイルを指す URL で指定されます。
• ユーザー設定。
• エンド ユーザーのロケール。
• (オプション) IgnoreCache 処理オプション。
• (オプション) モジュール ID。特定のコンテナ コンテキスト内でのガジェットに対する整数の識別子です。指定されていない場合、最上位の 0 がデフォルトになります。

出力:

• HTML、CSS、JavaScript。

処理:

1. ガジェット XML をフェッチします。
   1. これを行うには、キャッシュを使って、ガジェット XML をホストするサーバーの負荷を最小にする必要があります。キャッシュの特定のプロパティは実装に委ねられます。
   2. サーバーは、更新されたコンテンツを確実に展開できるように、頻繁にキャッシュを更新することで負荷を受けますが、HTTP キャッシュ ヘッダーを使うことで、その負荷を分散する方法をデベロッパーに提供できます。
   3. サーバーは IgnoreCache 処理オプションを受け入れる必要があります。これにより、組み込みの仕様キャッシュはすべて無視され、仕様は標準のリソースから直接フェッチされます。この機能はガジェット開発時に役立ちます。
      1. HTTP ベースの要求サーバーでは、nocache という URL パラメータを使ってこの機能がサポートされる必要があります。
      2. サーバーでは、デベロッパーのために、仕様のフェッチ回数を特定の期間制限してサービス拒否に対する保護を実装することができます。
2. ガジェット XML を解析します。
   1. XML は拡張ガジェット仕様 XSD に準拠する必要があります。この XSD は、レガシーの iGoogle ガジェット サーバー (gmodules.com) で受け入れられた有効な要素と属性をすべて表します。ただし、このフィールドの一部は段階的に廃止されます。標準ガジェット仕様 XSD には、サーバーにより解析され変換される必要のある属性のサブセットが含まれます。つまり、パーサーは拡張仕様に準拠するガジェット仕様を拒否できませんが、標準仕様以外を解析する必要はありません。
3. リクエストに対応するロケール オブジェクトを識別して、それに指定されたメッセージをフェッチします。
   1. 宣言された言語と国が照合されて、<Locale> 要素がガジェット XML から選択されます。要素が言語と国の両方に一致する場合は、その要素を使います。それ以外の場合、言語のみの一致を国のみの一致に優先して選択します。このような一致もない場合は、言語属性も国属性も定義されていない要素を使用します。
   2. 一致した <Locale> 要素があれば、その要素に指定されたメッセージ バンドルを読み込みます。
      1. メッセージ属性が指定されている場合は、その属性を使用します。 指定された URL を使ってネットワークからバンドルを読み込みます。
      2. それ以外の場合は、<Locale> の子である <messagebundle> 要素があればその要素を使用します。
4. 「Hangman 変数」を、サポートされるガジェット仕様のフィールドに代入します。Hangman 変数の形式は、__<TYPE>_<ID>__ です。この変数は文字列値で置き換えられます。Hangman 変数には次のように 4 つの種類があります。
   1. メッセージ バンドルを処理して __MSG_foo__ Hangman 変数に変換します。
      1. バンドルは メッセージ バンドル XSD に準拠する必要があります。
      2. 名前が foo で値が bar の各メッセージでは、Hangman 拡張 __MSG_foo__ = bar。
   2. キーが foo で値が bar の、指定された各ユーザー設定では、Hangman 拡張 __UP_foo__ = bar。
   3. Hangman 拡張 __MODULE_ID__ = <provided module ID>。
      1. HTTP ベースの要求サーバーでは、これに mid という URL パラメータを使う必要があります。
   4. language_direction = "rtl" を使ってメッセージ バンドルが見つかった場合、Hangman 拡張は __BIDI_START_EDGE__ = "right"、__BIDI_END_EDGE__ = "left"、__BIDI_DIR__ = "rtl"、__BIDI_REVERSE_DIR__ = "ltr"。それ以外の場合は、__BIDI_START_EDGE__ = "left"、__BIDI_END_EDGE__ = "right"、__BIDI_DIR__ = "ltr"、__BIDI_REVERSE_DIR__ = "rtl"。
   5. ユーザーに表示するすべてのフィールドで各 Hangman 拡張の代入を実行します。現在これには次のフィールドが含まれます (ただしこれらに限定されません)。
      1. Module.ModulePrefs attributes、Module.Content@href、Module.Content、UserPref@display_name、UserPref@default_value、UserPref.EnumValue@display_value
5. ガジェット XML に <Require> または <Optional> として指定されているガジェット機能を処理します。
   1. <Require> ブロックにサポートされない機能が 1 つ以上指定されている場合、サーバーは標準のエラーメッセージを出力し、レンダリング要求を満たすことができないことを示す必要があります。
      1. 要求された機能のうち、コンテナでサポートされていないために使用不可となった機能はメッセージにすべて表示する必要があります。
      2. メッセージには、ガジェット サーバー管理者の連絡先情報とともに、機能のサポート追加を要求するためのメカニズムを提供することもできます。
   2. サーバーは次のコア JavaScript API をサポートする必要があります。これらは <Optional> 機能に適用されます。

      gadgets.util.hasFeature(featureName)

      JsDoc で説明されているとおり、このメソッドは、サーバーが featureName を満たすことができる場合に true を返し、そうでない場合に false を返します。ガジェット デベロッパーはこの機能性を使ってガジェットを拡張できます。機能が利用可能な場合は、その機能が欠落していてもガジェットを無効にする必要はありません。
   3. サーバーは、要求された各機能に指定されている要件に準拠して、その機能をサポートすることを宣言する必要があります。その詳細は機能ごとに異なりますが、レンダリングされた出力または URL 包含型のライブラリに JavaScript API を加えること、および HTML 型のコンテンツを操作して拡張構文をサポートすることを含めます。
6. ガジェットのコンテンツを出力します。
   1. HTML ガジェットの場合は次の順序で指定します。
      1. <html> タグと <body> タグで開始される標準 HTML ヘッダー。<head> 情報はオプションです。ガジェットはブラウザ固有のモードで動作します。
      2. ここに指定されているガジェットのコア JavaScript ライブラリ。
      3. 機能ライブラリの初期化コード (必要な場合)。
      4. 処理されたガジェットのコンテンツ。ステップ 4 (および、場合によってはステップ 5) の結果です。
      5. gadgets.util.runOnLoadHandlers(); の単独呼び出し。
      6. 標準の HTML 終了タグ。
   2. URL 型のガジェットの場合は、指定する URL に次のパラメータを追加する必要があります。
      1. 指定する各ユーザー設定の up_<name>=<value>。
      2. 指定するリクエスト ロケールの lang=<language> と country=<country>。
      3. libs=<jsLib>。<jsLib> は、サーバーの JavaScript リクエスト ハンドラのパスに対する相対的な URL パス フラグメントのカンマ区切りリストです。このフラグメントは、URL 型のターゲットによって JS パスに追加されます。これにより、Gadget API JavaScript が実行コンテキストに読み込まれます。
         1. サーバーはすべてのライブラリを 1 つのリクエストに統合して、クライアントのブラウザからの HTTP リクエストの数を最小にする必要があります。

ガジェットのメタデータ要求

この API は、ガジェット コンテナに、ページでガジェットをレンダリングする方法を指示し、ガジェットの機能をサポートするために必要なコンテナ側の JavaScript を提供します。

コンテキスト (コンテナ側の JavaScript):

ブラウザのセキュリティ モデルが原因で、Gadget API リクエストを満たすためにガジェット コンテナのサポートが必要になることはよくあります。たとえば dynamic-height 機能を使えば、ガジェットはコンテンツに応じて自身のサイズを変更するよう要求できます。これは特にガジェットが IFRAME で使用される場合に役立ちます。ほとんどの場合、ガジェットはそのコンテナとは異なるドメインでレンダリングされます。したがって、ガジェットは自身の高さを変更できません。その代わりに、ガジェットは、サイズ変更を要求するコンテナに対してドメイン間のプロシージャ呼び出しを実行します。このコミュニケーションは、コア gadgets.rpc.* API を使って実行されます。この API は、ブラウザ固有の技術を使って、同じブラウザ コンテキスト内に配置された異なるドメイン上のフレーム間でメッセージの受け渡しを行います。コンテナはこのリクエストを受け取り、そのリクエストに応答できるようにする必要があります。これが、コンテナ側の JavaScript の機能です。

サニタイズされたガジェット コンテンツに関する注意事項:

ガジェットのレンダリング要求の URL ではなく、ガジェットのメタデータ要求の API では、セキュリティ上の理由でサニタイズされたガジェット出力のバージョンを返すことができます。Caja プロジェクト ではこのサニタイズが提供されます。そのサニタイズでは、静的な分析手法を使用して HTML、CSS、JavaScript が書き換えられて、危険な DOM やガジェット コンテンツへの危険な Cookie アクセスが排除される一方で、IFRAME 内で単純に実行されるコンテンツに近い表現力が維持されます。ただし、この機能は依然として試行段階であるため、現時点でコア仕様に含まれていません。

入力:

• ガジェットのレンダリング要求と同じです。

出力:

• 要求されたガジェットに対する、ガジェットのレンダリング要求への URL。
• 必要な API リクエストを満たすために必要なコンテナの JavaScript への参照。

処理:

1. ガジェットのレンダリング要求のステップ 1 と 2 で説明されているとおりに、ガジェット XML を読み込んで解析します。
2. ガジェット XML に <Require> または <Optional> として指定されているガジェット機能を処理します。
   1. 必要な機能がサポートされていない場合はエラー メッセージを出力します。
   2. それ以外の場合は、要求されたサポート済みの機能とコンテナ側の JavaScript ごとに、その JavaScript をキューに追加してクライアントに返します。
3. 対応するガジェットのレンダリング要求への URL を構成します。生成方法は次のとおりです。
   1. 静的なプレフィックスを使って URL を初期化します。
   2. パラメータ url=<url> を追加します。<url> は要求されたガジェット仕様の URL です。
   3. ガジェットのレンダリング要求の 6.ii.a で説明されているユーザー設定パラメータを追加します。
   4. ガジェットのレンダリング要求の 6.ii.b で説明されているロケール パラメータを追加します。
4. キューに追加したコンテナ側の JavaScript とガジェットのレンダリング要求の URL を返します。

JavaScript 要求

URL 型ガジェットの JavaScript ライブラリ読み込み要求を満たすために、サーバーは、機能にリンクされたコア JavaScript を取得する HTTP サービスを提供する必要があります。

入力:

• 固定パス。静的なベース URL とパス フラグメントを組み合わせて算出します。パス フラグメントについてはガジェットのレンダリング要求の 6.ii.c をご覧ください。

出力:

• URL 型のガジェットが必要とする API に対応する JavaScript コード。

コア JavaScript API

サーバーは、すべてのコア API を、Gadgets API リファレンスに準拠する方法で提供する必要があります。コンテナがすべてを自動で提供するので、ガジェット デベロッパーはこのいずれの機能も要求する必要はありません。

ファイル	JsDoc
prefs.js	ドキュメント
io.js	ドキュメント
json.js	ドキュメント
util.js	ドキュメント

推奨機能

ほとんどのガジェットに 1 つ以上の機能が含まれます。ガジェット サーバーがサポートする機能が増加するほど、ガジェット サーバーがサポートするガジェットも増加します。したがって、各ガジェット サーバーはできるだけ多くの機能をサポートする必要があります。特に、使用率の高い次の機能をサポートすることを強くお勧めします。各機能はガジェットで使用できるようにするための JavaScript API を提供します。機能名と関連する API を表に示します。

機能	ファイル	JsDoc
tabs	tabs.js	ドキュメント
minimessage	minimessage.js	ドキュメント
flash	flash.js	ドキュメント
rpc	rpc.js	ドキュメント
views	views.js	ドキュメント
skins	skins.js	ドキュメント
dynamic-height	dynamic-height.js	ドキュメント
settitle	settitle.js	ドキュメント