PlaceEngine API のメッセージをハンドリングするヒント

PlaceEngine API を使って現在地の The geo microformat を生成できるようにしました

先週公開した The geo microformat 生成ツール に PlaceEngine API を使って、現在地を取得できる機能を追加しました。これにより、PlaceEngine をインストールした環境があれば、現在地を取得ボタンをクリックすることで、無線 LAN (Wi-Fi) の電波から現在位置を取得して、今いるその位置の HTML を生成できます。

PlaceEngine API の使い方とリファレンスは、PlaceEngine API JavaScript ライブラリ にまとまっているのですが、その中の実例がオーソドックスな使い方を紹介したものだけです。そのため、応用して PlaceEngine が通知するメッセージをハンドリングしたくなったとき、どうすればよいのか、読み取りにくい印象がありました。

そこで、PlaceEngine API を組み込んだ The geo microformat 生成ツール を題材にして、PlaceEngine が通知するメッセージをハンドリングするヒントをお伝えします。

次の HTML は、題材のツールから PlaceEngine に関する HTML を抜粋したものです。

id="status" の要素に PlaceEngine が通知するメッセージを表示することを意図しています。

<input type="image" id="post" alt="位置を教える" src="wide_bt2.png" />
<input type="image" id="get" alt="現在地を取得" src="wide_bt1.png" />
<a href="http://www.placeengine.com">
<img alt="PlaceEngine" src="logo_wh.gif" />
</a><br />
<span id="status">
<a href="http://www.placeengine.com/show/install">PlaceEngine をインストールする</a>
と、無線 LAN (Wi-Fi) の電波から、現在位置を取得できるようになります。
</span>

次の JavaScript は、題材のツールから PlaceEngine に関する JavaScript を抜粋したものです。

PlaceEngine インスタンスを生成しています。idstatus オプションにメッセージの出力先とする要素の id を指定すると、その要素にメッセージが自動的に表示されます。ですが、ここでは、メッセージを表示せずに独自にハンドリングしたいため、idstatus オプションを指定していません。

  // PEngine
  engine = new PEngine({
    //idstatus: 'placeengine-status',
    appkey: 'apikey',

onFindClient オプションにコールバック関数を指定すると、PlaceEngine が見つかったとき、この関数が実行されます。ここでは、PlaceEngine が見つかったとき、既存のメッセージを消去しています。

    // onFindClient
    onFindClient: function() {
      $('#status').empty();
    },

onGetLocation オプションにコールバック関数を指定すると、現在地が見つかったとき、この関数が実行されます。ここでは、現在地が見つかったとき、その住所を入力ボックスに設定し、その現在位置まで Google マップをスクロールさせています。また、現在地が見つからないとき(エラーを含む)、そのメッセージを表示しています。

    // onGetLocation
    onGetLocation: function(x, y, r, info) {
      if (r > 0) {
        c.val(info.addr);
        map.panTo(new GLatLng(y, x));
      } else {
        $('#status').text(info.msg);
      }
    },

onMessage オプションにコールバック関数を指定すると、PlaceEngine がメッセージを通知するたび、この関数が実行されます。ここでは、無用なメッセージを表示しなようにするため、空の関数を指定しています。なお、onMessage オプションを省略しても同様の効果があります。

    // onMessage
    onMessage: function(message) {
    }
  });

PlaceEngine の存在を確認しています。PlaceEngine が存在するとき、前述の onFindClient が非同期で実行されます。

  engine.pingClient();

位置を教えるボタンをクリックしたときのコードです。現在の位置を表す Google マップのインスタンスを指定しています。

  $('#post').click(function() {
    engine.registerLocation(map);
    return false;
  });

現在地を取得ボタンをクリックしたときのコードです。現在地が取得できたとき、できないとき(またはエラーが発生したとき)、前述の onGetLocation が非同期で実行されます。

  $('#get').click(function() {
    engine.getLocation();
    return false;
  });

ダラダラと長い説明になりましたが、以上でおしまいです。PlaceEngine API のメッセージを独自にハンドリングしようとするときのヒントになればと期待します。