このガイドを、iGoogle 環境でのガジェットの構築と管理に役立ててください。このガイドは、iGoogle、Gadgets API、JavaScript についての一般的な知識を持つデベロッパーを対象とするものです。また、iGoogle でのガジェット開発に関連するその他のリソースにもリンクしています。
注意: このドキュメントは頻繁に改訂されています。英語版と日本語版で内容が異なることがあります。最新の版を見るには、ページ上のメニューで [English] を選択してください。
開発作業は、ガジェットのコンテナによって異なります。このセクションでは、iGoogle で使用するガジェットの開発プロセスについて説明します。
このガイドでは、iGoogle 開発作業に関連する要素とトピックを説明するために、次の用語を使用します。
| Updates ガジェット | 1 人のユーザーからのアクティビティを含むデータ フィードを表示するガジェットです。 |
|---|---|
| ガジェット | 第三者が作成したコード。ガジェットと OpenSocial API を使用して iGoogle の機能を拡張します。 |
| ガジェット定義 | ガジェットを定義する XML ファイル。構文はガジェット XML に基づき、「ガジェット仕様」とも呼ばれます。 |
| ガジェット ディレクトリ | 利用できるガジェットのリスト。人気とユーザー フィードバックに基づいてランクが付けられています。 |
| 左ナビゲーション | iGoogle ページの左側にあるリンクのリスト。左ナビゲーションには、ユーザーのページでの各ガジェットのキャンバス ビューへのリンクが表示されます。 |
| 左ナビゲーション リンク | 左ナビゲーションにあるリンク。ガジェットのキャンバス ページを開きます。 |
| ビュー | ガジェットが表示される場所。iGoogle では、ガジェット はキャンバス ビューまたはホーム ビューで表示されます。どちらのビューも非公開です。iGoogle では、ユーザーが別のユーザーのガジェットを見ることはできません。 |
| ホーム ビュー | 他のガジェットとともに表示される、小さいガジェット ビュー。自分のすべてのガジェットを、小さい表示形式で表示します。ホーム ビューは非公開で 、ログインしているユーザーのみに表示されます。 |
| キャンバス ビュー | ガジェットを単独で表示する、大きいガジェット ビュー。キャンバス ビューは非公開で 、ログインしているユーザーのみに表示されます。 |
| 友だち | OpenSocial API は、ユーザーの友だちネットワークへのアクセスを提供します。iGoogle サンドボックスに、Sandbox Friends ガジェットを使って友だちを追加できます。 |
iGoogle のガジェットを作成する前に、まずガジェットのさまざまな機能と、それぞれの関係について知っておくと便利です。iGoogle ガジェットの構造 のドキュメントをご覧ください。
はじめてガジェットを作成する場合は、OpenSocial Tutorial で OpenSocial API の詳細を確認してください。このチュートリアルでは、OpenSocial API を使用してシンプルなギフト贈呈ガジェットを開発するために必要な手順について説明しています。
すでに作成したガジェットがある場合は、それを拡張することによって、iGoogle サンドボックスを通じて提供される次の新機能のメリットを活用できます。
サーバにアクセスして自分のガジェットを保存することができない場合は、 Google Gadgets Editor (GGE) でガジェットを編集してホスティングすることができます。簡単な「Hello World」ガジェットを作成するには、Google アカウントでログインしていることを確認し (ログインしていないと、ガジェットを保存できません)、Google Gadgets Editor で次のガジェットを変更します。たとえば、メッセージ「Hello, world!」を「Hello, iGoogle!」に変更します。
[File] > [Save As] で、ファイルを「igoogle-sample.xml」という名前で保存します。一度保存した後は、エディタの右上隅のファイル名をクリックすると、ガジェットの XML ファイルを開くことができるようになります。
これでガジェット XML がブラウザで開きます。ガジェットをインストールするには、次のセクションにファイルの URL を入力する必要があります。
ソーシャル ネットワーク データにアクセスするためには、ガジェットをコンテナ内で実行する必要があります。iGoogle は、OpenSocial API およびその他の新機能にアクセスできるデベロッパー サンドボックスを提供します。サンドボックスには、こちらから登録できます。
新しいガジェットを追加するには
デベロッパー ツール タブを追加して、Developer ガジェットからガジェットを追加することもできます。
iGoogle サンドボックスには、ガジェットを表示するビューが 2 種類あります。1 つはホーム ビューです。ホームビューで、ガジェットは追加した他のガジェットとともに 3 段組で表示されます。
ガジェットを最大のサイズで表示するには、[ホーム] の下のリンクをクリックして、キャンバス ビューで表示してください。デフォルトでは、ガジェットは小さい形式でのみ表示されます。自分のガジェットにキャンバス ビューを追加する方法については、ビューを参照してください。
たとえば、これはホーム ビューで Books ガジェットが表示されている画面です。ここには、ユーザーの読書リスト、ユーザーの友だちの読んだ本、おすすめの本が並べられているだけですが、
Books ガジェットの大きなキャンバス ビューには、タブ、ユーザーの読んだ本の詳細、ユーザーのレビューなど、より豊富な内容が表示されます。
iGoogle のホーム ビューとキャンバス ビューは非公開で 、ユーザーとしてログインしていないと、表示されません。iGoogle と Orkut などのその他のソーシャル ガジェットとコンテナとの大きな違いは、この点です。
サンドボックス開発環境を設定するには、サンドボックスにログインしてデベロッパー ツール タブを追加します。
デベロッパー ツール タブには、次のガジェットが配置されています。
Developer ガジェットは、各自の iGoogle ページにあるすべてのガジェットの「コマンド センター」として動作します。実行中のすべてのガジェットを表示することができるほか、ガジェットの追加、表示、管理ができます。Developer ガジェットは、ガジェット開発者が必要とする機能を提供します。たとえば、これを使用すれば「分割した」ガジェットを追加できます。これは、ガジェットを積極的に変更する場合に便利です。
Developer ガジェットで個別のガジェット リンクをクリックすると、そのガジェットの XML 仕様を表示できます。これは、他のガジェットがどのように実装されているかを調べるために便利な方法です。
[Cached] チェックボックスは、ガジェットの開発に便利な機能の 1 つです。デフォルトでは、ガジェット仕様がキャッシュされます。ガジェットの開発中は、[Cached] をオフにする必要があります。これにより、ガジェットのキャッシュされたバージョンではなく、最新バージョンを確認することができます。
Sandbox Friends ガジェットは、iGoogle サンドボックスの友だちを管理することができます。
だれかをサンドボックスの友だちとして設定する手順は、2 段階で構成されています。1 人が招待状を発行し、もう 1 人がこれを受け入れなければなりません。
招待状を表示し、他の人を招待するには、[Invitations & Suggestions] をクリックします。このパネルには 2 つのリストが含まれます。
だれかを招待して友だちになるには、リストに表示されている連絡先の横の [Add as friend] をクリックするか、テキスト フィールドに新しいメール アドレスを入力します。メール アドレスは Google アカウントに関連付けられている必要があります。それ以外のアドレスは、入力しても無視されます。[Save changes] をクリックすると、このパネルで行った変更が保存されます。これを実行しないと、発行した招待状や受け付けた招待状が処理されないので、これは重要なステップです。
招待状を受け付けるか、送った招待状が受け付けられると、その人は友だちリストに追加されます。この時点で、その人には OpenSocial API を通じてアクセスできるようになります。友だちデータの操作の例については、チュートリアルをご覧ください。
Sandbox Profile Editor ガジェットを使うと、iGoogle サンドボックス プロフィールを編集できます。API を通じてアクセスできるプロフィール情報はユーザー ID、名前、場所、サムネイルの URL のみです。詳細については、プロフィール データをご覧ください。
Updates ガジェットには、ユーザーが送信したすべてのアクティビティの現在のリストが、最新のものから順に表示されます。
Updates ガジェットの詳細については、アップデートをご覧ください。
以上で、ガジェットのインストールと更新の基礎について学習できました。ここではガジェットの作成と iGoogle サンドボックスの機能の活用に役立つノウハウを説明します。
OpenSocial ガジェットはガジェット テクノロジに基づく新しいタイプのガジェットです。機能は拡張されており、OpenSocial API をサポートするウェブサイト (コンテナともいいます) から取得したソーシャル データと対話します。iGoogle は OpenSocial コンテナの一例です。このセクションでは、iGoogle 環境でのガジェット開発作業の側面に焦点を当てます。
ビューは、ガジェットが表示されるコンテナ内の場所です。さまざまなビューに、さまざまな特性があります。たとえば、コンテナには小さい形式のガジェットが表示される場合と、全画面形式のガジェットが表示される場合があります。
iGoogle サンドボックスのデフォルトでは、ガジェットはホーム ビュー モード (小さい表示モード) で表示されます。これは、他のガジェットとともに段組のレイアウトで表示されます。ガジェットのキャンバス ビュー (大きい表示モード。ガジェットは領域の横幅全体に拡大されます) を作成するには、次のように<Content> セクションを「canvas」ビュー タイプとして定義する必要があります。
<Content type="html" view="canvas">
<Content> セクションでキャンバス ビューを定義したら、<Content> セクションを作成して、ガジェットがホーム ビューでも正しく表示されるようにする必要があります。これは、「default」または「home」のいずれかにします。複数の <Content> セクションをサポートするガジェットの作成については、OpenSocial JavaScript デベロッパー ガイドをご覧ください。
これは、Hello World ガジェットで <Content> セクションに「home」と「canvas」のビューを定義したバージョンの例です。ホーム ビューで表示するかキャンバス ビューで表示するかによって、幅が変化します。
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Hello World!">
<Require feature="opensocial-0.7" />
</ModulePrefs>
<Content type="html" view="home">
<![CDATA[
Hello, small world!
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
Hello, big world!
]]>
</Content>
</Module>
iGoogle でのガジェットの表示には、キャンバス ビューとホーム ビューがあります。どちらのビューも、ログインしているユーザーでなければ表示できません。
現在のビューを取得するための最も簡単な方法は、ガジェットのモジュール プリファレンスに views 機能をインクルードすることです。
<ModulePrefs title="Views example"> <Require feature="views" /> </ModulePrefs>
views 機能をインクルードすると、gadget.util.getCurrentView() 関数を呼び出すことによって現在のビューを取得できます。これは、gadgets.views.View オブジェクトを current_view 変数にアサインします。この呼び出しによって返されるビューの一覧については、iGoogle で使用可能なビューをご覧ください。
次に、現在のビューを取得して、返された値に対して条件に応じたコードを実行する例を示します。
function getViewName() {
return gadgets.views.getCurrentView().getName();
}
if (getViewName() == "canvas") {
/* Do canvas specific stuff here */
}
if (getViewName() == "home") {
/* Do home specific stuff here */
}
ModulePrefs セクションに必ず <Require feature="views"> を入れてください。gadgets.views.getSupportedViews() 関数を呼び出して、使用可能な View オブジェクトを取得します。
var supported_views = gadgets.views.getSupportedViews();
getSupportedViews 呼び出しによって返されるオブジェクトには、iGoogle で使用可能なすべてのビューを表す、ビュー名によってインデクシングされた gadgets.views.View オブジェクトが含まれます。
ガジェットのホーム ビューには、ユーザーにとって最も関心が深いコンテンツとお知らせが含まれます。ここはコンテンツや友だちのアップデートのサマリーを表示するための場所であり、ユーザーが簡単な作業をすばやく実行することができる場所です。
ガジェットのキャンバス ビューはより大きなスペースに表示されるので、コンテンツと機能を豊富に詰め込めます。ユーザーをつなぎ止め、友だちの動向を表示させたり、複雑な作業を実行できるようにしたりするためには、このビューを活用します。
ModulePrefs セクションに必ず <Require feature="views"> を入れてください。他のビューへのリンクを提供する場合は、gadgets.views.requestNavigateTo() メソッドに gadgets.views.View オブジェクトを渡す必要があります。iGoogle で使用可能なビューに記載されている getSupportedViews() 呼び出しによって返されるオブジェクトの 1 つを選択することができます。次は、このメソッドを示したコードの例です。
function navigateTo(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
navigateTo("canvas");
};
/**
* When called, this method asks the container to switch to the home
*/
function gotoHome() {
navigateTo("home");
};
別の方法として、新しい View オブジェクトを手動で作成し、これを使ってナビゲーションする方法があります。次のコードは、新しい gadgets.views.View オブジェクトを作成して gadgets.views.requestNavigateTo() メソッドに渡す例を示しています。
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view);
};
/**
* When called, this method asks the container to switch to the home
*/
function gotoHome() {
var home_view = new gadgets.views.View("home");
gadgets.views.requestNavigateTo(home_view);
};
これは「Hello World」ガジェットを基にした、完全な例です。
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs height="100" title="Navigation">
<Require feature="views" />
</ModulePrefs>
<Content type="html" view="home">
<![CDATA[
<div>Hello world Home view</div>
<script type="text/javascript">
function goToView(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
</script>
<a href="javascript:goToView('canvas')" >Go to canvas view</a><br><br>
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
<div>Hello world Canvas view</div>
<script type="text/javascript">
function goToView(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
</script>
<a href="javascript:goToView('home')" >Go to home view</a><br><br>
]]>
</Content>
</Module>
注: OpenSocial 0.7 には、ガジェットの ID 番号を返す呼び出しはありません。この値をガジェットで使用する場合は、手動で値を保存してください。
ModulePrefs セクションに必ず <Require feature="views"> を入れてください。gadgets.views.requestNavigateTo() 呼び出しを使用している場合は、新しいページに渡すデータを含むオプション パラメータを指定することができます。
次のコードは、foo と bar の 2 つの変数を現在のガジェットのキャンバス サーフェスに渡しています。
function gotoCanvas(params) {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view, params);
};
var my_params = {
foo : 12345,
bar : "Bar value"
};
gotoCanvas(my_params);
キャンバス ビューでは、これらの値を次のコードによって確認します。
var prefs = gadgets.views.getParams(); var foo = prefs["foo"]; /* foo contains 12345 */ var bar = prefs["bar"]; /* bar contains "Bar value" */
アップデートとは、ユーザーが iGoogle ガジェットを操作しながら実行したアクションについて、そのユーザーの友だちに送信するアクティビティのことです。Updates ガジェットは、送信されたすべてのアップデート (アクティビティ) の現在のリストを、最新のものから順に表示します。
このサンプル ガジェットは、テキストボックスにアップデートを入力して [Post Update] をクリックすると、そのアップデートを送信できるガジェットです。送信したアップデートは、Updates ガジェットの [Refresh Now] をクリックすると表示されます。
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Post Updates" >
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
// Post an activity and set its title to be the text the user entered in the
// text box.
function postUpdate(form) {
var text = form.inputbox.value;
var div = document.getElementById('content_div');
var params = {};
params[opensocial.Activity.Field.TITLE] = text;
var activity = opensocial.newActivity(params);
opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH);
div.innerHTML = "Update title is: " + activity.getField(opensocial.Activity.Field.TITLE);
}
</script>
<FORM NAME="myform" ACTION="" METHOD="GET">Add Update: <BR>
<INPUT TYPE="text" NAME="inputbox" VALUE=""><P>
<INPUT TYPE="button" NAME="button" Value="Post Update" onClick="postUpdate(this.form)">
</FORM>
<div id="content_div"></div>
]]>
</Content>
</Module>
上の例は、Activity オブジェクトの TITLE フィールドのみにアクセスしています。iGoogle では、オプション フィールド BODY、MEDIA_ITEMS、STREAM_FAVICON_URL、STREAM_URL もサポートしています。
開発用に、iGoogle サンドボックスは getActivities() を呼び出して、ユーザーに対するすべてのアクティビティを取得する機能をサポートしています。今後、getActivities() は特定のガジェットのアクティビティのみ返すようになります。
このデバッグ機能を使用するには、オプション パラメータを次のように設定してください。
var optParams = {};
optParams[opensocial.DataRequest.ActivityRequestFields.APP_ID] = '*';
アスタリスク (*) は、すべてのアクティビティを要求していることを示すワイルドカードです。
次の表は、イベントが表示される場所を表しています。
| イベント タイプ | Updates gadget |
|---|---|
| ネイティブ イベント | |
| ガジェットのインストールとアンインストール | はい |
| ガジェットのイベント | はい |
ガジェットから Updates ガジェットに対して大量のアップデートが送信されるのを回避するため、ユーザーが 1 日に送信できるアップデートの数を制限できるようにする予定ですが、開発を容易にするため、サンドボックスでは現在この制限を提供していません。詳しくは、よくある質問 をご覧ください。
OpenSocial API は、iGoogle ユーザーに関する情報へのアクセスをプロフィール データという形で提供します。このセクションでは、iGoogle で利用できるプロフィール フィールドについて説明します。iGoogle サンドボックスは、ユーザーに自分のプロフィール データを編集するための Profile ガジェットを提供します。
iGoogle サンドボックスでは、Person オブジェクトを通じて現在のユーザーの次のフィールドにアクセスできます。
getId()getDisplayName()getField(opensocial.Person.Field.THUMBNAIL_URL)
getField(opensocial.Person.Field.CURRENT_LOCATION)
これは、ユーザーをフェッチして、そのサムネイル、名前、ID、場所を表示する例です。
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Profile Example" scrolling="true">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
/**
* Request for viewer information.
*/
function getData() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.VIEWER), 'viewer');
req.send(onLoadViewer);
};
/**
* Display the viewer's thumbnail, name, ID, and location.
*/
function onLoadViewer(dataResponse) {
var viewer = dataResponse.get('viewer').getData();
var thumb = viewer.getField(opensocial.Person.Field.THUMBNAIL_URL);
var loc = viewer.getField(opensocial.Person.Field.CURRENT_LOCATION);
var address = loc.getField(opensocial.Address.Field.UNSTRUCTURED_ADDRESS);
var html = "<img src=\"" + thumb + "\"/><br />";
html += "The ID for " + viewer.getDisplayName() + " is " + viewer.getId()+"<br />";
html += "The location for " + viewer.getDisplayName() + " is " + address;
document.getElementById('message').innerHTML = html;
};
gadgets.util.registerOnLoadHandler(getData);
</script>
<div id="message"> </div>
]]>
</Content>
</Module>
iGoogle サンドボックスでは、個々のユーザー インスタンスが格納できる永続データ (Appdata) の量が制限されています (Appdata の詳細については OpenSocial JavaScript デベロッパー ガイドを参照してください)。上限は 10 KB です。Appdata の書き込みオペレーションがこの制限を超過しそうになると、オペレーションが失敗して「quota exceeded」というエラーが発生します。
iGoogle サンドボックスは、まもなく OpenSocial メソッド requestSendMessage() をサポートする予定です。このメソッドにより、コンテナから指定のユーザーにメッセージを送信できるようになります。
OpenSocial API についてさらに情報を得るには、OpenSocial API ホームページのさまざまなドキュメントや資料をご覧ください。