ホットペッパー - HotPepper.UI.Places.Drilldown - by Recruit Web Service UI Library
関東 > 東京 > 渋谷・原宿 > センター街・公園通り ...といった地域を選択する為のユーザーインターフェースを自動生成するモジュール。相互連動更新する、一般的な4つのプルダウンUIを提供。
必要な選択肢情報を、必要なタイミングで動的に取得/生成する為、大量の都市マスタデータ等を事前に読み込む必要無く、快適なUIを提供する事ができます。
大サービスエリアを選ぶとその下のサービスエリアの選択肢が、サービスエリアを選ぶと中エリアの選択肢が、中エリアを選ぶと小エリアの選択肢が、それぞれ該当地域のものに自動的に切り替わります。
コピペする事で手軽に再利用が可能なコード例はこちら
下記のように必要なファイルを読み込んだうえで...
<script type="text/javascript" src="jquery.js"></script> <script type="text/javascript" src="recruit.ui.js"></script> <script type="text/javascript" src="hotpepper.ui.js"></script>
プルダウンを表示させたい場所にこのようなHTMLを書き...
<select id="hpp-large-service-area-sel"></select>
<select id="hpp-service-area-sel"></select>
<select id="hpp-middle-area-sel"></select>
<select id="hpp-small-area-sel"></select>
最後にこのようなjavascriptコードを書くことで任意のタイミングでプルダウンが自動生成されます。
Recruit.UI.key = 'ご自身のAPIキー'; new HotPepper.UI.Places.Pulldown();
jQueryを使って、ページ表示と同時にプルダウン生成したい場合はこちら:
$(function (){ Recruit.UI.key = 'ご自身のAPIキー'; new HotPepper.UI.Places.Pulldown(); });
ご自身のAPIキーをお持ちでない方はこちらの画面からリクルートWEBサービスに登録する事で取得する事ができます。
他のプルダウン系UIと同じく、コンストラクタの引数にパラメーターを与える事でオプション機能が利用できます。その際には以下の例に示すように、大サービスエリア・サービスエリア・中エリア・小エリア - 4つのプルダウンそれぞれが個別のパラメーター空間を持つ形になります。
デフォルトでは "hpp-large-service-area-sel" 等のid値でHTML中のプルダウン(SELECTタグ)を探しにいきますが、これを任意のid値で指定したい場合は以下のように書きます:
new HotPepper.UI.Places.Pulldown({ large_service_area: { id: 'my-lsa-sel' }, service_area: { id: 'my-sa-sel' }, middle_area: { id: 'my-ma-sel' }, small_area: { id: 'my-sma-sel' } });
いずれかひとつだけの指定ももちろん可能です。
以下のように指定する事で文言を変えられます:
new HotPeper.Places.Pulldown({ large_service_area: { first_opt_text: '▼大サービスエリア' }, service_area: { first_opt_text: '▼サービスエリア' }, middle_area: { first_opt_text: '▼中エリア' }, small_area: { first_opt_text: '▼小エリア' } });
このようにそれぞれ個別に指定します。
実際の動作例:
各プルダウンに予め何らかの地域を最初から設定しておきたい場合は以下のように書きます:
// アクアシティをデフォルトに new HotPepper.UI.Places.Pulldown({ small_area: { val: 'X076' } });
実際の動作例:
同様に large_service_area または service_area または middle_area を指定する事も可能です:
// 東京をデフォルトに new HotPepper.UI.Places.Pulldown({ service_area: { val: 'SA11' } });
// お台場をデフォルトに new HotPepper.UI.Places.Pulldown({ middle_area: { val: 'Y007' } });
大サービスエリアとサービスエリアだけを使いたい:
<select id="hpp-large-service-area-sel"></select>
<select id="hpp-service-area-sel"></select>
new HotPepper.UI.Places.Pulldown();
実際の動作例:
上記のように、最上位レベルである大サービスエリアから任意の下位エリアまでを使いたい際には、何も気にすることなく必要なプルダウンだけ用意しておけばOKです。しかし、下位エリアの一部だけを使いたい場合は下記のような記述が必要になります。
中エリアと小エリアだけを使いたい:
<select id="hpp-middle-area-sel"></select>
<select id="hpp-small-area-sel"></select>
new HotPepper.UI.Places.Pulldown({ middle_area: { service_area: 'SA11' } });
実際の動作例:
中エリア(middle_area)の選択肢を表示させるには、必ずどの上位エリア(service_area)に属しているのかを伝える必要がある為、上記例のように middle_area のオプション指定にて、service_area は 'SA11' (東京) だよ、と伝えている形になります。
小エリアコード 'X076' のエリア名は?このエリアが属する中エリアやサービスエリアや大サービスエリアのコード値および名称は?などを調べるには以下のインスタンスメソッドを使います:
var places = HotPepper.UI.Places.Pulldown(); places.find_item_by_code({ small_area: 'X076', callback: function ( itm ){ itm.name; // アクアシティ itm.code; // X076 itm.middle_area.name; // お台場 itm.middle_area.code; // Y007 itm.service_area.name; // 東京 itm.service_area.code; // SA11 itm.large_service_area.name; // 関東 itm.large_service_area.code; // SS10 } });
JSONP形式の通信にてWebサービスから情報を取得する為、上記の例のように引数 callback にて結果を処理するための関数を定義する形になります。
同様に large_service_area_area または service_area または middle_area で調べる事も可能です:
var places = HotPepper.UI.Places.Pulldown(); places.find_item_by_code({ service_area: 'SA12', callback: function ( itm ){ itm.name; // 神奈川 itm.code; // SA12 itm.large_service_area.name; // 関東 itm.large_service_area.code; // SS10 } });
同メソッドで返されるオブジェクトの中身は HotPepper Webサービスの各エリア系マスタAPIが返す単体レコードの中身と同一です。詳しくはこれらAPIのドキュメントを参照してください。
インスタンス生成時のオプション指定 - on_update_hook - を各要素ごとに指定することで、プルダウンの選択肢が刷新される度に任意の処理を実施できます:
HotPepper.UI.Places.Pulldown({ large_service_area: { on_update_hook: function (){ alert( 'large_service_area updated' ); } }, service_area: { on_update_hook: function (){ alert( 'service_area updated' ); } }, middle_area: { on_update_hook: 同上... }, small_area: { on_update_hook: 同上... } });
各 on_update_hook 処理内で出来ること・便利に利用できるメソッド等については、こちらのドキュメントを参照ください。
簡単なサンプルコードはこちら:
on_update_hook サンプルコード
これを有効活用する事により、「ユーザがプルダウン値を選択したら、下層プルダウンの情報を元に xxx を画面に別途表示」といったカスタマイズUIを作成することができるようになります。
各プルダウンごとの get_current_stat() メソッドにより、現在選択中の値や全選択肢のリスト等の便利情報を取得する事ができます:
var p = HotPepper.UI.Places.Pulldown(); var lsa_stat = p.large_service_area.get_current_stat(); var sa_stat = p.service_area.get_current_stat(); var ma_stat = p.middle_area.get_current_stat(); var sma_stat = p.small_area.get_current_stat();
各戻り値 *_stat の中身については、こちらのドキュメントを参照ください。