Documentation

You are viewing the documentation for the 2.2.0 release in the 2.2.x series of releases. The latest stable release series is 2.4.x.

§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 メソッドの引数と同じ形式のオブジェクトを引数にとります。また、このオブジェクトの typeurl プロパティはそれぞれルータがリクエストに応じて設定してくれるものとします。

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

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