ガジェット XML リファレンス

このドキュメントは、ガジェット仕様 XML(OpenSocial バージョン 0.9)のリファレンスです。

JavaScript リファレンスはこちらをご覧ください。

ガジェット API の詳細についてはガジェットの仕様(英語)をご覧ください。

目次

  1. ModulePrefs 要素と属性
  2. ユーザー設定
  3. コンテンツ セクション
  4. JavaScript リファレンス
    1. 機能固有の JavaScript ライブラリのインクルード

ModulePrefs 要素と属性

XML ファイルの <ModulePrefs> セクションでは、ガジェットのタイトル、作者、最適に表示されるサイズなどの特性を指定します。次に例を示します:

<Module>
<ModulePrefs title="Developer Forum" title_url="http://groups.google.com/group/Google-Gadgets-API"
height="200" author="Jane Smith" author_email="xxx@google.com"/>
<Content ...>
... content ...
</Content>
</Module>

ガジェットのユーザーはこれらの属性を変更できません。

<ModulePrefs> は、すべてのメタデータ、機能、処理規則のコンテナ要素として機能します。ネストされる各要素については、以降の各セクションをご覧ください。このセクションでは、<ModulePrefs> 内の要素と属性について簡単に説明します。以降のセクションでは、ネスト レベルをスラッシュ(/)で示します。たとえば /ModulePrefs/Locale は、<Locale> 要素が <ModulePrefs> 要素内にネストされていることを表します。ガジェット仕様では、これを次のように記述します:

<ModulePrefs>
<Locale lang="en" country="us" /> <Locale lang="ja" country="jp" /> </ModulePrefs>

ModulePrefs

次の表に、すべてのコンテナでサポートされる <ModulePrefs> 属性を示します。各コンテナに固有の <ModulePrefs> 属性については、そのコンテナのドキュメントをご覧ください。

属性 説明
title オプション。ガジェットのタイトルを表す文字列です。このタイトルは、iGoogle のガジェット タイトル バーに表示されます。この文字列内でユーザー設定代入変数が指定され、ガジェットを iGoogle コンテンツ ディレクトリに送信する予定の場合は、ディレクトリの表示に使用する directory_title も指定する必要があります。
title_url オプション。ガジェット タイトルのリンク先 URL を表す文字列です。たとえば、ガジェットに関連するウェブページにタイトルをリンクできます。
description オプション。ガジェットを説明する文字列です。
author オプション。ガジェットの作者を表す文字列です。
author_email オプション。ガジェットの作者のメール アドレスを表す文字列です。使用するメール システムは問いませんが、スパム対策のため個人用のメール アドレスは使用しないようにしてください。ガジェット仕様では helensmith.feedback+coolgadget@gmail.com といった形式のメール アドレスを使用するのも 1 つの方法です。

Gmail では、プラス記号(+)の後はすべて切り捨てられます。したがってこのメール アドレスは helensmith.feedback@gmail.com となります。

Gmail アカウントはこちらから作成できます。
screenshot オプション。ガジェットのスクリーンショットの URL を表す文字列です。この画像は、robots.txt によってブロックされない公開ウェブサイト上に配置する必要があります。推奨の形式は PNG ですが、GIF や JPG でも構いません。ガジェットのスクリーンショットの幅は 280 ピクセルにする必要があります。高さは、使用時のガジェットが「自然な」高さになるように調整してください。
thumbnail オプション。ガジェットのサムネイルの URL を表す文字列です。この画像は、robots.txt によってブロックされない公開ウェブサイト上に配置する必要があります。推奨の形式は PNG ですが、GIF や JPG でも構いません。ガジェットのサムネイルは 120×60 ピクセルにする必要があります。

ModulePrefs/Require と ModulePrefs/Optional

<Require> 要素と <Optional> 要素は、ガジェットの機能の依存関係を宣言します。

属性:

  • "feature" -- 機能の名前です。必須です。

例:

<Require feature="dynamic-height"/>
<Optional feature="shareable-prefs"/>

ModulePrefs/Require/Param と ModulePrefs/Optional/Param

これらの要素は、機能の設定パラメータを提供します。

属性:

  • "name" -- パラメータの名前です。必須です。

ModulePrefs/Preload

<Preload> 要素は、ガジェットのレンダリング処理中にリモート ソースからデータをフェッチするようにコンテナに指示します。この要素は、リモート サーバーからデータをフェッチする makeRequest()(英語)と組み合わせて使用します。

たとえば、次のようなリクエストがあるとします:

gadgets.io.makeRequest("http://www.example.com", response, params);

http://www.example.com でコンテンツをプリロードするには、次のように <Preload> タグをガジェットの <ModulePrefs> セクションに追加します:

<ModulePrefs title="Demo Preloads" description="Demo Preloads">
<Require feature="opensocial-0.9" /> <Preload href="http://www.example.com" /> </ModulePrefs>

ガジェットが makeRequest() の呼び出しを実行すると、もう一度サーバーにアクセスすることなく直ちにこのコンテンツが返されます。

<Preload> を使用すると、makeRequest() でリモート サーバーからデータをフェッチするガジェットの待ち時間を短縮できます。このトピックについて詳しくは、Introduction to makeRequest(英語)をご覧ください。

属性:

  • "href" -- プリフェッチするデータの場所を示す URL です。必須です。
  • "authz" -- このリクエストを実行するために使用する認証の種類です。有効な値は、"none"(デフォルト)、"signed""oauth" です。オプションです。

これらの属性は、makeRequest() クエリ文字列内の承認パラメータにマップしています:

属性 説明
oauth_service_name ガジェットが、その XML 仕様から OAuth <Service> 要素を参照するために使用するニックネームです。指定しない場合のデフォルトは "" です。gadgets.io.RequestParameters.OAUTH_SERVICE_NAME にマップしています。
oauth_token_name ガジェットが、特定のリソースへのアクセスを付与している OAuth トークンを参照するために使用するニックネームです。指定しない場合のデフォルトは "" です。同じサービス プロバイダから複数のリソースにアクセスする場合は、複数のトークン名を使用できます。たとえば、連絡先リストとカレンダーにアクセスできるガジェットでは、連絡先リスト トークンを使用するために "contacts" トークン名を使用し、カレンダー トークンを使用するために "calendar" トークン名を使用できます。gadgets.io.RequestParameters.OAUTH_TOKEN_NAME にマップしています。
oauth_request_token サービス プロバイダは、リソースへのアクセスが事前に承認されたリクエスト トークンを使用して、ガジェットを自動的に設定できる場合があります。このようなガジェットでは、OAUTH_REQUEST_TOKEN パラメータでそのトークンを使用できます。このパラメータはオプションです。gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN にマップしています。
oauth_request_token_secret 事前に承認されたリクエスト トークンに対応するシークレットです。このパラメータはオプションです。gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET にマップしています。
sign_owner オーナーが認証を受ける必要があるかどうかを示すブール値です。指定しない場合のデフォルトは "true" です。gadgets.io.RequestParameters.SIGN_OWNER にマップしています。
sign_viewer 閲覧者が認証を受ける必要があるかどうかを示すブール値です。指定しない場合のデフォルトは "true" です。gadgets.io.RequestParameters.SIGN_VIEWER にマップしています。
views 特定のプリロードをトリガする閲覧者名のカンマ区切りリストです。

すべての <Preload> 属性は、プロキシ経由のコンテンツにも適用されます。

ModulePrefs/Icon

<Icon> 要素には、各コンテナで特定のガジェットに関連付けることのできる 16×16 ピクセルの画像を指定します。このアイコンは、たとえば左ナビゲーション バーのガジェット名の横に表示できます。

<Icon> タグのコンテンツとしては次のいずれかを指定します:

  • ウェブ上の画像ファイルを指す HTTP URL
  • base64 エンコードのインライン画像データ

属性:

  • "mode" -- 画像を埋め込む際にアイコンに使用するエンコードです。現時点でサポートされているのは base64 のみです。オプションです。
  • "type" -- 埋め込みアイコン テキストの MIME です。オプションです。

例:

<ModulePrefs title="My gadget">
  <Icon>http://remote/favicon.ico</Icon>
</ModulePrefs>

<ModulePrefs title="My gadget">
  <Icon mode="base64" type="image/png">base64 encoded data</Icon>
</ModulePrefs>

ModulePrefs/Locale

<Locale> 要素には、ガジェットでサポートするロケールを指定します。ガジェットと国際化で説明されているように、この要素を使用してメッセージ バンドルを指定することもできます。

属性:

  • "lang" -- ロケールに関連付ける言語です。オプションです。
  • "country" -- ロケールに関連付ける国です。オプションです。
  • "messages" -- メッセージ バンドルを指す URL です。メッセージ バンドルとは、特定のロケール用に翻訳された文字列を格納する XML ファイルのことです。詳しくは、ガジェットと国際化をご覧ください。オプションです。
  • "language_direction" -- ガジェットの方向です。オプションです。値には、"rtl"(右から左)または"ltr"(左から右)のいずれかを指定できます。デフォルトは "ltr" です。この属性を使用すると、左から右に書く言語と右から左に書く言語の両方をサポートするガジェットを作成できます。このトピックについて詳しくは、双方向性ガジェットの作成をご覧ください。language_direction は、以下の代入変数と併用できます:
    • __BIDI_START_EDGE__: この変数の値は、ガジェットが LTR モードのときは "left"、ガジェットが RTL モードのときは "right" になります。
    • __BIDI_END_EDGE__: この変数の値は、ガジェットが LTR モードのときは "right"、ガジェットが RTL モードのときは "left" になります。
    • __BIDI_DIR__: この変数の値は、ガジェットが LTR モードのときは "ltr"、ガジェットが RTL モードのときは "rtl" になります。
    • __BIDI_REVERSE_DIR__: この変数の値は、ガジェットが LTR モードのときは "rtl"、ガジェットが RTL モードのときは "ltr" になります。

たとえば次のスニペットでは、2 つの異なるロケールを指定しています:

<ModulePrefs>
  <Locale lang="en" country="us" />
  <Locale lang="ja" country="jp" />
</ModulePrefs>

lang(言語)属性と country 属性はどちらもオプションですが、<Locale> ごとに少なくともどちらか 1 つを指定する必要があります。どちらかの属性を省略した場合は、その値に "*" や "ALL" を指定した場合と同じになります。国を指定して言語を指定しない場合、そのガジェットはその国に関連付けられているすべての言語をサポートするものと見なされます。同様に言語を指定して国を指定しない場合、そのガジェットはその言語に関連付けられているすべての国をサポートするものと見なされます。

言語の有効な値は、ISO639-1 の 2 桁の言語コードです。国には ISO 3166-1 alpha-2 コードが使用されます。

基本的には通常の言語規則が適用されますが以下は例外です:

  • 中国語(簡体): lang="zh-cn"(通常 country="cn" の場合に設定します)。
  • 中国語(繁体): lang="zh-tw"(通常 country="tw" 台湾、"hk" 香港の場合に設定します)。

ModulePrefs/Link

コンテナ固有のリンクです。たとえばこのタグを使用して、gadgetsHelpgadgetsSupport などの新しいリンク タイプをサポートできます。

属性:

  • "rel" -- ライフサイクル イベントをトリガする値です。必須です。
  • "href" -- URL です。必須です。
  • "method" -- リクエストの送信に使用するメソッド(POST または GET)です。デフォルトは GET です。オプションです。

コンテナでは、適切なクエリ パラメータを URL エンドポイントに送信する方法で、ライフサイクル イベントをアプリケーション デベロッパーのサイトに送信することもできます。このイベントは、<Link> タグを使用して受信できます。各 <Link> タグには、rel 属性と href 属性が含まれています。href 属性は、イベントの ping の送信先となるエンドポイントを示します。rel 属性を "opensocialevent" にすると、すべてのイベントがそのエンドポイントに送信されます。rel 属性が "opensocialevent.TYPE", に一致すると、TYPE のイベントがそのエンドポイントに送信されます。オプションの method 属性を使用すると、リクエストの送信メソッドを POST にするか GET にするかを指定できます。デフォルトは GET です。いくつか例を示します:

<link rel="event" href="http://www.example.com/pingme" method="POST/>
<link rel="event.addapp" href="http://www.example.com/add" />
<link rel="event.removeapp" href="http://www.example.com/remove" />

ほとんどのイベントには、1 つ以上の OpenSocial ID 値に関する情報が含まれています。これらの ID 値は、1 つ以上の ID 属性として渡されます。複数の ID 値を指定すると、単一の ping で複数のイベントをまとめることができます。

以下のイベント タイプが定義されています:

  • addapp -- アプリケーションをインストールしたユーザー(ID)です。オプションの from には、ユーザーがこのアプリケーションをどのように追加したかを指定します。指定できる値は、"invite""gallery""external" です。
  • removeapp -- アプリケーションを削除したユーザーの ID です。
  • app -- action={enabled|disabled|approved} reason={policy|quota|maintenance}
  • invite -- id は招待されたユーザー、from_id は招待状の送信元の ID です。

ModulePrefs/OAuth

<OAuth> 要素は、ガジェットでの OAuth プロキシの使用を定義します。ガジェットに OAuth を実装する方法については、OAuth ガジェットの作成をご覧ください。

ModulePrefs/OAuth/Service

この要素には、個々の OAuth サービスの設定を指定します。

属性:

  • "name" -- 実行時に OAuth サービスを参照するために使用するサービス名(たとえば "google")です。このパラメータはオプションで、指定しない場合のデフォルトは "" です。ガジェット デベロッパーは、使用する OAuth サービスの名前を、パラメータとして makeRequest() に渡します。

ModulePrefs/OAuth/Service/Request と ModulePrefs/OAuth/Service/Access

これらの要素は、OAuth リクエスト トークンとアクセス トークンの URL を表します。詳しくは、OAuth の仕様(英語)と OAuth ガジェットの作成をご覧ください。

属性:

  • "url" -- エンドポイントの URL です。
  • "method" -- このリクエストを実行するために使用する HTTP 動詞です。このパラメータはオプションです。指定しない場合のデフォルトは POST です。
  • "param_location" -- サービスに対するリクエスト内で OAuth パラメータを渡す場所として、以下の 3 つのうち 1 つを指定します。この値を使用して、OAuth 関連のパラメータの場所を指定できます。指定できる値は次のとおりです:
    • "uri-query" -- OAuth パラメータはクエリ文字列内で渡されます。
    • "auth-header" -- OAuth パラメータは承認ヘッダー内で渡されます。
    • "post-body" -- OAuth パラメータは POST リクエストの本文内で渡されます。

これらの値は、OAuth の仕様(英語)に説明されているオプションと対応しています。デフォルト値は "auth-header" です。

ModulePrefs/OAuth/Service/Authorization

OAuth 承認 URL です。

ユーザー設定

ガジェットによっては、ユーザーが固有の情報を指定するための手段を提供する必要があります。たとえば天気予報のガジェットでは、ユーザーが郵便番号を指定する必要があるかもしれません。XML ファイルのユーザー設定(<UserPref>)セクションには、ガジェットの実行時にユーザー インターフェース コントロールとして機能するユーザー入力フィールドを記述します。

次の表に <UserPref> 属性の一覧を示します:

属性 説明
name 必須。ユーザー設定の名前であり、内容を表す「象徴的」な名前を付けます。display_name が定義されていない場合は、編集時にこの名前がユーザーに表示されます。使用できるのは、文字、数字、アンダースコアのみです。正規表現で表すと ^[a-zA-Z0-9_]+$ となります。一意にする必要があります。
display_name オプション。編集ウィンドウでユーザー設定の横に表示される文字列です。一意にする必要があります。
urlparam オプション。コンテンツ type="url" のパラメータ名として渡される文字列です。
datatype オプション。この属性のデータ型を示す文字列です。指定できるのは、stringboolenumhidden(表示されず、ユーザーが編集できない文字列)、list(ユーザーの入力から生成される動的配列)です。デフォルトは string です。
required オプション。このユーザー設定が必須かどうかを示すブール値の引数(true または false)です。デフォルトは false です。
default_value オプション。ユーザー設定のデフォルト値を示す文字列です。

ガジェットからユーザー設定にアクセスするには、ユーザー設定用の JavaScript API を使用します。次に例を示します:

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

Enum データ型

<UserPref> datatype 属性に指定できる値の 1 つに enum があります。enum データ型は、ユーザー インターフェースでは選択肢のメニューとして表示されます。メニューの内容は <EnumValue> を使用して指定します。

たとえば次の <UserPref> では、ユーザーがゲームの難易度を設定できます。メニューに表示される各値(Easy、Medium、Hard)は <EnumValue> タグで定義されています。

<UserPref name="difficulty" 
     display_name="Difficulty"
     datatype="enum"
     default_value="4">
  <EnumValue value="3" display_value="Easy"/>
  <EnumValue value="4" display_value="Medium"/>
  <EnumValue value="5" display_value="Hard"/>
</UserPref>

次の表に <EnumValue> 属性の一覧を示します:

属性 説明
value 必須。一意の値を表す文字列です。display_value が指定されていない場合は、ユーザー設定の編集ボックスのメニューにこの値が表示されます。
display_value オプション。ユーザー設定の編集ボックスのメニューに表示される文字列です。display_value を指定しない場合、ユーザー インターフェースには value が表示されます。

コンテンツ セクション

<Content> セクションでは、コンテンツのタイプを定義し、コンテンツそのものを指定するか、外部コンテンツへの参照を指定します。<Content> セクションは、ガジェットの属性とユーザー設定をプログラミング ロジックやフォーマット情報と組み合わせて、実行可能なガジェットを作成する場所です。コンテンツ タイプについて詳しくは、コンテンツ タイプの選択をご覧ください。

次の表に <Content> 属性の一覧を示します:

属性 説明
type オプション。コンテンツのタイプを指定する文字列です。指定できる値は、htmlurl です。デフォルトは html です。
href 参照先の URL を表す文字列です。type="url" ガジェットまたはプロキシ経由のコンテンツのいずれかに適用できます。
view オプション。OpenSocial ガジェット専用です。特定のコンテンツを、OpenSocial コンテナのどのビューに表示するかを示す文字列です。OpenSocial ガジェットでは、複数のコンテンツ セクションを定義し、それぞれを別々のビューに表示できます。
preferred_height ガジェットの初期の高さ(ピクセル単位)です。
preferred_width ガジェットの初期の幅(ピクセル単位)です。

ModulePrefs/Content@href(プロキシ経由のコンテンツ)

プロキシ経由のコンテンツは、OpenSocial ガジェットに適用される機能の 1 つです。この機能を使用すると、特定のビューの URL ごとに HTML コンテンツを指定できます。ビューについて詳しくは、Multiple Content Sections(英語)をご覧ください。

この機能に指定するターゲット URL は、有効な HTML 4.01、XHTML 1.1 などでなければなりません。画像や Flash の URL は指定しないようにしてください。これらについては、HTML 内にラップしてその HTML にリンクします。ターゲットとなる HTML コンテンツには、<html> タグ、<head> タグ、<body> タグを含める必要があります。

たとえば、次のガジェットでは、canvas ビューにプロキシ経由のコンテンツを使用し、home ビューにインライン コンテンツを使用しています:

<?xml version="1.0" encoding="UTF-8"?>
<Module>
  <ModulePrefs title="Proxied Content Example">
</ModulePrefs>
  <Content view="canvas" 
    href="http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-09/mycontent.html">
  </Content>
  <Content view="home">
    <![CDATA[
      Hello, home view!
    ]]>
  </Content>
</Module>

プロキシ経由のコンテンツは、<Preload> 要素に適用されるのと同じ属性を使用します。詳しくは、ModulePrefs/Preload をご覧ください。

JavaScript リファレンス

JavaScript リファレンスはこちらをご覧ください。

機能固有の JavaScript ライブラリのインクルード

タブや Flash ムービーなど、特定の機能を使用するガジェットを作成する場合は、<Require> タグを <ModulePrefs> 要素内で使用して、ガジェット仕様に機能ライブラリをインクルードする必要があります。次に例を示します:

<ModulePrefs 
  title="My Tabbed Gadget">
  <Require feature="tabs"/>
</ModulePrefs> 

gadgets.* API には、以下の機能ライブラリが用意されています:

機能ライブラリ 説明 構文
setprefs ユーザー設定の値をプログラムで設定します。詳しくは、状態の保存をご覧ください。 <Require feature="setprefs"/>
dynamic-height ガジェットのサイズが自動的に変更されるようにします。詳しくは、ガジェットの高さの管理をご覧ください。 <Require feature="dynamic-height"/>
settitle ガジェットのタイトルをプログラムで設定します。詳しくは、ガジェットのタイトルの設定をご覧ください。 <Require feature="settitle"/>
tabs ガジェットにタブ付きインターフェースを追加します。詳しくは、タブをご覧ください。 <Require feature="tabs"/>
minimessage 無視できる一時的なメッセージをガジェット内に表示します。詳しくは、MiniMessage をご覧ください。 <Require feature="minimessage"/>
flash ガジェット内に Flash ムービー(具体的には .swf ファイル)を埋め込みます。詳しくは、Flash をご覧ください。 <Require feature="flash"/>
locked-domain locked-domain ライブラリは、自分のガジェットを、同じページ上の他のガジェットから隔離するために使用します。この機能は、type="html" ガジェットでのみ使用できます。個人の機密情報をユーザー データとして格納するガジェットには、この機能要件を追加することをおすすめします。この機能は iGoogle と Google カレンダーでのみ使用できます。その他のガジェット コンテナでは対応していないため、この機能が追加されているガジェットは拒否されます。 <Require feature="locked-domain"/>

特定の機能が対応しているすべてのメソッドを確認するには、JavaScript リファレンスをご覧ください。

 

トップへ戻る