§Javascript ルーティング

Play のルータには、クライアントサイドで実行される JavaScript から サーバアプリケーションへのルーティングを行うための Javascript コードを生成する機能があります。Javascript ルータ はアプリケーションのリファクタリングを支援します。アプリケーションの URL 構成やパラメータ名を変更しても、Javascript は自動的に新しい構造を使うよう更新されます。

§Javascript ルータの生成

Play の Javascript ルータを利用するにあたってまず必要なことは、それを生成することです。Javascript ルータは、設定時に宣言されたルートだけを提供するようになっています。これにより、生成される Javascript コードのサイズが最小限になります。

Javascript ルータの生成方法は二通りあります。一つは Scala テンプレートの関数を使ってルータを HTML ページに埋め込むというものです。もう一つは、アクション内で Javascript リソースを生成して、様々なページからダウンロード、キャッシュ、そして共有できるようにするというものです。

§埋め込みルータ

埋め込みルータは Scala テンプレート内で @javascriptRouter 関数を呼び出すことで生成できます。記述箇所としてよくあるのは、親テンプレートでしょう。

@helper.javascriptRouter("jsRoutes")(
  routes.javascript.Users.list,
  routes.javascript.Users.get
)

第一引数は生成されるルータのグローバル変数名です。第二引数はこのルータに含められるルートのリストです。この関数を利用するためには、テンプレートのスコープ内に implicit な RequestHeader が必要です。例えば、 (implicit req: RequestHeader) をテンプレートの引数宣言の最後に追加するとよいでしょう。

§ルータリソース

ルータリソースの作り方は、ルータジェネレータを呼び出すアクションを作る、というものです。ルータジェネレータを呼び出す際の文法は、 Scala テンプレート内にルータを埋め込む際のそれと似ています。

def javascriptRoutes = Action { implicit request =>
  import routes.javascript._
  Ok(
    Routes.javascriptRouter("jsRoutes")(
      Users.list,
      Users.get
    )
  ).as("text/javascript")
}

それから、対応するルートを追加します:

GET /javascriptRoutes  controllers.Application.javascriptRoutes

このようなアクションを実装して routes ファイルへ追加したら、 Scala テンプレート内で以下のような記述をすることでルータを読み込むことができます。

<script type="text/javascript" src="@routes.Application.javascriptRoutes"></script>

§ルータの利用

サンプルとして jQuery を使います。呼び出し方は以下に示すとおりシンプルです:

$.ajax(jsRoutes.controllers.Users.get(someId))
  .done( /*...*/ )
  .fail( /*...*/ );

ルータは url, (HTTP メソッドの) type, absoluteURL そして webSocketURL を含むいくつかのプロパティを提供します。例えば、上記の jQuery による ajax 関数の呼び出しは次のように書くこともできます:

var r = jsRoutes.controllers.Users.get(someId);
$.ajax({url: r.url, type: r.type, success: /*...*/, error: /*...*/ });

このアプローチは、 success, error, context といった、その他のプロパティを指定したい場合に必要です。

§jQuery ajax メソッドのサポート

注意: jQuery の ajax 関数の組み込みサポートは将来のリリースで削除されるでしょう。組み込みサポートに関するこの節は、参考のみを目的として提供されています。新規のコードでルータの ajax 関数を使わず、既存のコードをできる限り速やかにアップグレードすることを検討してください。ルータの使い方に関する前の節において、jQuery がどのように使われるべきか記述しています。

jQuery をお使いでないか、または jQuery の ajax メソッドをラップしたいといった場合には、ajax リクエストを行うための任意の関数をルータに提供することができます。この関数はルータの ajax メソッドの引数と同じ形式のオブジェクトを引数にとります。また、このオブジェクトの type と url プロパティはそれぞれルータがリクエストに応じて設定してくれるものとします。

この関数を定義するためには、アクション内でメソッドに ajaxMethod という名前の引数を渡しましょう。

Routes.javascriptRouter("jsRoutes", Some("myAjaxFunction") ...