My favorites | 日本語 | Sign in

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

このドキュメントはガジェット仕様で使用される XML のリファレンスです。

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

現在、gadgets.* JavaScript API は、OpenSocial API もサポートするコンテナでのみ動作します。元の「レガシー」 Gadgets API は、ガジェットをサポートするすべてのアプリケーション (OpenSocial をサポートしないアプリケーションを含む) で、まだ使用することができます。

gadgets.* API に対する理解を深めたい場合は、ガジェットの仕様をご覧ください。

目次

  1. ModulePrefs 要素と属性
  2. ユーザー設定
  3. コンテンツ セクション
  4. 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 も使用できます。ガジェットのサムネイルは 120x60 ピクセルにする必要があります。

/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> 要素は、ガジェットのレンダリング処理中にリモート ソースからデータをフェッチするようにコンテナに指示します。このデータは、レンダリングされた出力内でインライン化され、ガジェット コードが実行されるとすぐに利用できるようになります。このメソッドを使用するとガジェットの待ち時間が短縮されるはずです。待ち時間は、レンダリングするリモート サーバーのコンテンツによって異なります。

属性:

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

ModulePrefs/Icon

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

<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

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

属性:

  • "rel" -- ライフサイクル イベントを起動する値です。必須です。
  • "href" -- URL です。必須です。
  • "method" -- リクエストの送信元のメソッド (POST または GET) です。デフォルトは GET です。省略可能です。

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

ユーザー設定

ガジェットによっては、ユーザーが独自の情報を指定できる方法を提供する必要があります。たとえば天気予報のガジェットでは、ユーザーが郵便番号を指定することが必要な場合があります。XML ファイルのユーザー設定 (<UserPref>) セクションで、ガジェットの実行時にユーザー インターフェース コントロールになる、ユーザー用入力フィールドを指定します。

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

属性 説明
name 必須。ユーザー設定の名前で、内容を表す「象徴的」な名前を付けます。display_name が定義されていない場合、編集時にこの名前がユーザーに表示されます。文字、数字、アンダースコアのみ使用できます。正規表現で表すと ^[a-zA-Z0-9_]+$ となります。一意である必要があります。
display_name オプション。編集ウィンドウでユーザー設定の横に表示される文字列です。一意である必要があります。
urlparam オプション。コンテンツ type="url" のパラメータ名として渡される文字列です。
datatype オプション。この属性のデータ型を指定する文字列です。指定できるのは、string、bool、enum、hidden (表示されず、ユーザーが編集できない文字列)、list (ユーザーの入力から生成される動的配列)、location (Google マップに基づくガジェット用) のいずれかです。デフォルトは 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 オプション。コンテンツのタイプを指定する文字列です。指定できる値は、html と url です。デフォルトは html です。
href 参照先の URL を指定する文字列です。type="url" の場合に必須で、他のコンテンツ タイプの場合は指定できません。
cdata オプション。コンテンツ タイプが HTML の場合、iframe で表示する HTML そのものを含む文字列です。

JavaScript リファレンス

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

トップへ戻る