Google マプレット デベロッパーガイド

マプレットは、Google マップ内で実行されるミニアプリケーションです。これまでに多くのデベロッパーによって、写真、天気、ガソリン価格などの情報を地図上に重ね合わせて表示するためのマプレットが作成されてきました。Google マップ ディレクトリでは、これら以外にもさまざまなマプレットが公開されています。

マプレットは新しい技術のため、これらを使用する際に問題を発見した場合はぜひご報告ください。ご報告を頂く場合は、Maps API ヘルプ グループに参加頂くことをお勧めします。

対象読者

このガイドは、 JavaScript のプログラミング概念とオブジェクト指向プログラミング概念を理解しているデベロッパーを対象にしています。マプレットは特殊なタイプの Google Gadgets であるため、Google Gadgets API ドキュメント も参照してください。

このドキュメントではまずコンセプトを理解できるよう、 次のようなトピックに分かれています。

• マプレット プログラミングの基本
• マプレット イベント
• マプレット オーバーレイ
• マプレット サービス

マプレットを初めて開発する場合は、マプレットのインストール方法と公開方法を説明しているこのドキュメントと、マプレットの作成方法を説明している マプレットでの「Hello World」の両方をお読みください。Google Maps API について既に理解している場合は、マプレットと標準の Maps API の違いのセクションを参照してください。このガイドでは、Google ガジェット API や Google Maps API に関する十分な知識がまだないことを前提としています。

マプレットとは

マプレットは、ミニ ウェブページを包含する XML ファイルです。このミニ ウェブページ内には、HTML、JavaScript、Flash など、通常のウェブページに配置可能なすべての要素を配置できます。Google が提供する JavaScript API を使用すると、マプレットは、Google マップサイトとの通信、 リモートウェブサイトからのコンテンツの取得、ユーザー設定の保存を行うことができます。

マプレットがユーザーによって実行されると、Google は、ウェブサーバーからマプレットのソースコードを取得して、Google マップサイト上の IFrame 内でミニウェブページを提供します。セキュリティ上の理由から、ミニウェブページは gmodules.com に配置されます。 gmodules.com.

サイト上の負荷を軽減するために、マプレットのソースコードは gmodules.com のキャッシュに数時間保存されます。このキャッシュ保存処理を回避する唯一の方法は、Developer Mapplet をインストールすることです。

重要なデベロッパー ツール

マプレットの作成を開始する前に、まず Google マップ ディレクトリのデベロッパー ツールにアクセスして、次のツールを追加する必要があります。

• Developer Mapplet: このツールをインストールすると、実行する各マプレットに [Reload] リンクが追加されます。これにより、マプレットのソースコードが自動的にキャッシュに保存されることを回避できます。多くの場合、Developer Mapplet をインストールしていないとすぐにストレスを感じるようになります。
• Mapplet Scratch Pad:このツールを使用すると、 マプレットのコードを対話的に記述して、直ちにプレビューできます。このガイドのすべての サンプルコードを Scratch Pad にカットアンドペーストできます。

マプレットを作成する

開発環境を正しく構築したら、次にマプレット自体を作成します。マプレットは、maps.google.com 上のメイン地図と通信するための特殊な Google ガジェット内に配置される JavaScript コードです。マプレットを初めて作成する場合の詳細な解説については、マプレットの基本のマプレットでの "Hello World" のセクション参照してください。

マプレットを公開する

マプレットは、一般公開されているウェブサイトに保存する必要があります。自身のウェブサイトがない場合は、Google Page Creator を試してみることをお勧めします。ただし、WYSIWYG エディタは使用しないでください。代わりに、Site Manager にアクセスして右側の [upload] リンクを使用してください。次に、[Uploaded stuff] セクションでファイル名をクリックしてマプレットの URL を取得します。

マプレットをインストールして実行する

マプレットを実行する前に、 Google マップ ディレクトリにアクセスして、ページ上部の [Google マップのコンテンツを検索] ボタンの横にある [URL を指定して追加] リンクをクリックして、そのマプレットをインストールする必要があります。次に、マプレットの URL を入力して [追加] ボタンをクリックします。その後で Google マップに戻ると、[マイマップ] タブの下にマプレットが表示されます。

マプレットを共有する

次の URL を使用すると、作成したマプレットを他のユーザーが実行できるようになります。

http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=< URL of your mapplet>

この URL をクリックしたユーザーは、マプレットをインストールするかどうかを確認するページに移動します。たとえば、マプレットのソースコードが http://www.google.com/mapfiles/mapplets/distance/distance.xml に配置されている場合は、次の URL を公開します。

http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=http://www.google.com/mapfiles/mapplets/distance/distance.xml

マプレットをディレクトリに送信する

マプレットを Google マップ ディレクトリ に追加するには、この送信フォームを使用してください。楽しくて便利、そして高品質なマプレットのディレクトリになるように、できるだけ多くのマプレットを追加したいと考えています。

マプレットと標準のMaps API の違い

地図を操作するための API 呼び出しは、標準の Google Maps API から派生しており、そのほとんどは同じです。ただし、次のようにわずかな違いがあります。

初期化がよりシンプル

<Require feature="sharedmap"/> は自動的に API を初期化するため、手動で JavaScript ライブラリを読み込んだり API キーを渡す必要はありません。<div> は常にメイン地図への参照を返すため、<div> を手動で GMap2 コンストラクタには渡しません。

ユーザーがマプレットを読み込んだ場合は、そのユーザーが Google マップと互換性のあるブラウザを使用していることはほぼ確実であるため、GBrowserIsCompatible チェックは不要でありマプレットではサポートされていません。

Google Maps API では、setCenter() メソッドを通じて地図の位置決めをすることで地図を「初期化」する必要があります。マプレットでは、適切に初期化された地図が既にあるためこの位置決めは不要です。

禁止される動作

マプレットによって Google マップの標準動作を変更することは許可されていないため、ドラッグやダブルクリックズームなどを無効にするメソッドは排除しています。

マップとの通信は非同期式

マプレットと Google マップサイトとの間の通信は非同期式です。その結果、一部のメソッドは Google Maps API 側の対応する標準メソッドとは動作が異なります。ほとんどの場合、マップを変更する操作 (setCenter() や addOverlay() など) はMaps API 内の操作と同じです。ただし、マップから戻り値を取得する操作ではコールバック関数が必要です。マプレットでは、Async の影響を受けるすべてのMaps API メソッドの名前の末尾には Async が付加されており、これらの戻り値は代わりに引数としてコールバック関数に渡されます。

たとえば、Maps API では次のように記述します。

var zoom = map.getZoom();
alert("現在のズームレベル: " + zoom);
alert("これはズームレベルメッセージの表示後に発生します");

これに対してマプレットでは、これは次のように記述する必要があります。

map.getZoomAsync(function(zoom) {
  alert("現在のズームレベル: " + zoom);
});  
alert("これはズームレベルメッセージの表示前か表示後に発生する可能性があります");

多くの場合、複数の非同期要求を同時に実行する必要があります。これらの要求を連続的に実行したり相互に入れ子にする代わりに、マプレットが提供する GAsync() ユーティリティ関数を使用して複数の要求を1回の呼び出しで実行できます。GAsync() を使用するには、この関数にオブジェクトを渡して、その後ろに呼び出すメソッドを引用符で囲んで列挙し、最後の引数としてコールバック関数を指定します。

GAsync(map, 'getZoom', 'getCenter', function(zoom,center) {
  // ここにコードを記述します
}

複数のオブジェクトで要求を実行するには、最初のオブジェクトの直後に追加のオブジェクトと引用符付きメソッドを記述します。

GAsync(map, 'getZoom', 'getCenter', marker, 'getPoint',
  function(zoom,center,point) {
  // code here
}

セキュリティの問題と情報ウィンドウのクリーンアップ

マプレットは、gmodules.com に配置されている iframe 内で実行されるため、 Google ユーザーのクッキーにアクセスしたり Google マップサイトの JavaScript を中断することはできません。ただし、マップ (とそこに表示されるすべての要素) は maps.google.com ドメインに配置されているため、マプレットから情報ウィンドウの表示が要求されたときは、情報ウィンドウのコンテンツから許可されていない要素を削除してから、情報ウィンドウをマップに渡します。情報ウィンドウ内では JavaScript は許可されておらず、 安全な HTML タグと CSS のみが許可されています。

さらに、新しいマップコントロールやマップタイプの追加などの操作を行うには、現在はマップ内でサードパーティの JavaScript コードを実行する必要があるため、今のところはこれらを禁止しています。

リモートデータの要求は Google のプロキシを経由

マプレットは、Google によってサーバーが実行される gmodules.com から提供されます。ブラウザのセキュリティモデルでは、gmodules.com 上の JavaScript が他のドメインにデータを要求することは許可されていないため、マプレット内の GDownloadUrl や GXml を使用してサーバーからデータを取得することはできません。

代わりに、Google ガジェット API が提供する次の呼び出しを使用して、 gmodules.com 上で実行されているプロキシを介してコンテンツを取得できます。

• _IG_FetchContent(url, callback) -- url にあるコンテンツをテキストとして返します。HTML またはプレーンテキストのコンテンツを取得するには、この関数を使用します。
• _IG_FetchXmlContent(url, callback) -- url にある XML コンテンツを DOM オブジェクトとして返して処理します。解析が必要な XML コンテンツを取得するには、この関数を使用します。

これらのメソッドは、次の点で GDownloadUrl や GXml と 動作が異なります。

• _IG_FetchContent と _IG_FetchXmlContent の呼び出しはインターネット上の任意のウェブサイトからデータを取得できます。
• _IG_FetchXmlContent は GXml よりも厳格であり、XML ファイルが <?xml version="1.0" encoding="UTF-8"?> で始まっていることを要求します。
• _IG_FetchContent と _IG_FetchXmlContent の呼び出しは、コンテンツを自動的にキャッシュに保存してサーバー上の負荷を軽減します。キャッシュ保存期間を変更する方法やキャッシュ保存を無効化する方法については、ガジェット API ドキュメントの Refreshing the Cache のセクションを参照してください。

既存のMaps API マッシュアップをマプレットに変換する方法

Google Maps API を使用して構築した既存のサイトがある場合は、 Converting a Maps API Mashup into a Mapplet の記事を参照してください。

マプレット プログラミングの基本に続きます。