【spine.js】Spineのドキュメント翻訳　Routing

元のドキュメントはこちら
↓↓↓
Routing – Documentation – Spine

この記事ではcoffee scriptを使わはないピュアjavascript環境を前提としています。

はじめに

SpineはURLハッシュフラグメントに基づいたアプリケーションルーティングを提供しています。例えば、 「http://example.com/#/users」は「/users」というハッシュフラグメントを持っています。ハッシュフラグメントは完全に恣意的で、ページリロードを発生させず、ページの状態を維持します。また、Googleの Ajax Crawling specificationを使えばハッシュフラグメントによって検索エンジンにインデックスされることもできます。

内部的にSpineはhashchangeイベントを使ってURLのハッシュの変化を検知しています。このイベントは最近開発され、最新のブラウザでのみ有効になっています。過去のブラウザをサポートするために、 jQuery hashchange pluginを使います。このプラグインはiframeと様々なトリックを使ってhashchangeイベントをエミュレートしています。

ルーティングの追加

ではどのようにしてAPIを使うのでしょう。これは非常に簡単です。まずrout.coffeeをインクルードします。これはSpine.Routeモジュールを含んでいます。そしてルートをコントローラに追加していきます。Spine.Routeはコントローラ内でroutes()関数を提供しています。これはハッシュルートとコールバックを記述します。

var App = Spine.Controller.sub({
  init: function(){
    this.routes({
      "/users/:id": function(params){
        console.log("/users/", params.id)
      },

      "/users": function(){
        console.log("users")
      }
    })
  }
});

ルートパラメータは「:name」形式と関連付けられたコールバックに渡します。また、アスタリスクを使って全てにマッチすることもできます。

this.routes({
  "/pages/*glob": function(params) {
    return console.log("/pages/", params.glob);
  }
});

routesは逆順に特定されていくので、最も特定されるルートは初めに追加され、一般的で包括的なルートはあとに追加されます。これは注目に値し、特にコントローラのconstructor()関数でルートを追加する場合に、ルートは1度だけ追加されるべきです。上記はよい例で、Appコントローラは1度しかインスタス化されません。

もうひとつの方法は、コントローラを飛ばして、Spine.Route.add()に直接追加します。このときハッシュかシングルルートを渡します。

Spine.Route.add(/\/groups(\/)?/, function() {
  return console.log("groups");
});

上記の例でみたように、ルートは正規表現にマッチさせて制御することができます。

初期設定

最初にページがロードされるとき、URLがハッシュフラグメントを持っていたとしても、hashchangeイベントはコールされません。それ以降の変化でのみコールされます。これはアプリケーションがセットアップされた後に、手動でSpineに、ルーティングとURLのハッシュをチェックすることを知らせる必要があります。これはSpine.Route.setup()を呼び出して行います。

Spine.Route.setup();

ナビゲート

最後に、Spineはコントローラにnavigate()関数を提供しており、URLハッシュを変更するフラグメントを渡すことができます。また、navigate()には複数の引数を渡すことができます。これは頭にスラッシュ（/）を付けて結合されています。

var Users = Spine.Controller.sub({
  init: function(){
    this.navigate("/users", this.item.id);
  }
});

new Users({item: User.first()});

navigate()を使うことでURLのフラグメントは関連するコントローラと同期することができます。デフォルトではnavigate()の呼び出しはrouteコールバックに引き起こされます。もしroutesを発生させたくない場合は、navigate()の最後の引数にfalseを与えます。

Spine.Route.navigate("/users", false);

HTML5ヒストリ

Spineはまた、HTML5のヒストリAPIの使用についてのオプションを持っています。このAPIはページの更新やハッシュフラグメントを使わずにURLを切り替えられる点で優れています。これはユーザーが親しんだよりきれいなURLの形式を持っています。

ハッシュフラグメントに代わって、このヒストリAPIを使うために、setup()関数に{history: true}を渡します。

Spine.Route.setup({
  history: true
});

HTML5ヒストリのサポートはこのオプションが設定された場合にのみ有効です。言い換えると、Spineのルーティングはハッシュフラグメントを使って履歴を遡ります。

しかし、ヒストリAPIが使用されるときはいくつか気にかけておかなくてはならないことがあります。まず、navigate()に送られた全てのURLは本物のHTML表示を持たなくてはなりません。ブラウザはある時点で新しいURLにリクエストをなげないとはいえ、もしページがリロードされればリクエストが投げられます。言い換えると、ハッシュフラグメントのように勝手なURLを作ることができず、APIに渡される全てのURLが存在する必要があります。この実装の一つの方法はサーバーサイドでのサポートです。

ブラウザが（HTMLを期待して）URLを要求するとき、サーバーサイドでエンドポイントが存在し有効であることを確認します。それから、メインアプリケーションをロードして、URLを読み込み、適切なルーティングを呼び出します。例えば、ユーザーがhttp://example.com/users/1にアクセスしたとします。サーバー側ではURLのusers/1が有効かどうか、IDが１のユーザーレコードが存在しているかどうかを確認します。それからJavaScriptアプリケーションを提供します。

この方法の注意すべき点は、検索エンジンのクローラーに何もコンテンツを与えないということです。もしアプリケーションをクルーリングしてもらいたいなら、クローラボットのリクエストを検知し、コンテンツのパラレルワールドを与えなければなりません。これはｋのドキュメントの範囲を超えています。

シミング

しばしば、routesをの使用は便利で、ページURLやハッシュフラグメントを変更しません。これは特にフルスクリーンモバイルやPhoneGapアプリケーションなどページアドレスが表示されない環境で共通しています。これに対応するために、Route.setup()にshimオプションを渡します。

Spine.Route.setup({
  shim: true
});