Google Mapplets デベロッパー ガイド

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

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

対象読者

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

先ごろこのドキュメントの改訂を行い、次の主な領域についてより概念的な情報と、発展的なディスカッションを追加しました。

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

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

マプレットとは

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

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

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

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

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

• Developer Mapplet: このツールをインストールすると、実行する各マプレットに [Reload] リンクが追加されます。これにより、マプレットのソース コードが自動的にキャッシュ保存されるのを回避できます。Developer Mapplet のインストールをおすすめします。
• Mapplet Scratch Pad: マプレット コードを対話形式で作成し、すぐにプレビューできるようにするツールです。このガイドにあるサンプル コードはすべて、Scratch Pad にカット アンド ペーストできます。

マプレットを作成する

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

マプレットを公開する

マプレットは一般公開されている Web サイトに保存する必要があります。自身の Web サイトがない場合は、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 マップ ディレクトリ に追加するには、この送信フォームを使用してください。Google は、ユーザーにとって便利で楽しい、質の高いマプレットでディレクトリが充実することを目標としています。送信されたマプレットをすべてディレクトリに含めることはできませんが、可能な限り含めたいと考えています。

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

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

よりシンプルな初期化

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

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

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

標準動作以外の禁止

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

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

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

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

var zoom = map.getZoom();
alert("Current zoom level is " + zoom);
alert("This happens after you see the zoom level message");

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

map.getZoomAsync(function(zoom) {
  alert("Current zoom level is " + zoom);
});  
alert("This might happen before or after you see the zoom level message");

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

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

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

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 を使用してサーバーからデータを取得することはできません。

代わりに Gadgets API の次の呼び出しでは、コンテンツが gmodules.com で実行されているプロキシ経由で取得できるようになっています。

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

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

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

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

Google Maps API を使用したサイトを既に構築している場合は、「Maps API マッシュアップをマプレットに変換する方法」の項目をご覧ください。

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