link_to_remote

rails

RDoc 見たら ActionView::Helpers::PrototypeHelper の link_to_remote 読めって書いてあったので訳してみたよ。★はわかんないとこ。情報求ム。


link_to_remote(name, options = {}, html_options = {})


options[:url] (url_for フォーマットで記述する) で定義されたリモートアクションへのリンクを返します。リンクをクリックするとバックグラウンドで XMLHttpRequest が呼ばれます。そのリクエストの結果が、options[:update] で指定された DOM オブジェクトに挿入されます。

例：

  link_to_remote "Delete this post", :update => "posts",
    :url => { :action => "destroy", :id => post.id }
  link_to_remote(image_tag("refresh"), :update => "emails",
    :url => { :action => "list_emails" })

また、options[:update] にハッシュを指定し、サーバサイドでエラーが発生した時、簡単に出力を別の DOM 要素にリダイレクトすることができます。

例：

  link_to_remote "Delete this post",
    :url => { :action => "destroy", :id => post.id },
    :update => { :success => "posts", :failure => "error" }

また、引数の options[:position] では対象の DOM エレメントをどのように更新するかを指定することもできます。:before, :top, :bottom, :after のどれかを指定しましょう。(☆)


メソッドは通常 POST が使われます。GET を指定することもできますし、POST で PUT や DELETE をシミュレートすることもできます。これらは options[:method] で指定できます。

例：

  link_to_remote "Destroy", person_url(:id => person), :method => :delete


通常、これらのリモートリクエストは、様々な JavaScript コールバックが呼ばれる間中(プログレスバーやそれに類するもののために)、非同期に実行されます。全てのコールバックは、XMLHttpRequest を内包するリクエストオブジェクトを介して行われます。


request.respondText を使用してサーバのレスポンスにアクセスし、request.status を使用して HTTP ステータスを知ります。

例：

  link_to_remote word,
    :url => { :action => "undo", :n => word_counter },
    :complete => "undoRequestCompleted(request)"


コールバックは以下のものが順に指定できます：

  • :loading
    • リモートドキュメントがブラウザによってデータをロードされている時に呼ばれます。
  • :loaded
    • ブラウザがリモートドキュメントのロードを終えた時に呼ばれます。
  • :interractive
    • ロードを終えてないときに、ユーザーがリモートドキュメントをインタラクティブに扱うことが出来ます。
  • :success
  • :failure
  • :complete
    • XMLHttpdRequest が完了した時に呼ばれます(success/failure が確定した後)。

:success や :failure に、ステータスコードを指定したコールバックを付加して、さらに細かく制御できます。

例：

  link_to_remote word,
    :url => { :action => "action" },
    404 => "alert('Not found...? Wrong URL...?')",
    :failure => "alert('HTTP Error ' + request.status + '!')"

ステータスコード指定のコールバックは、既にある success/failure ハンドラを上書きします。


もし、同期処理する(リクエストがある間ブラウザをブロックする)何らかの理由か必要があれば、options[:type] = :synchronous を指定できます。


ブラウザ側の呼び出しロジックを、いくらかのパラメータを付加して JavaScript コード片を処理することにより、カスタマイズできます。

  • :confirm
    • 確認ダイアログを付け加えます。
  • :condition
    • この表現を使うことで、リモートリクエストをより安定して (conditionally) 使うことができます。リモートリクエストが発行されない場合には、ブラウザサイドの状態を返すようになります。(☆)
  • :before
    • リクエストを開始する前に呼ばれます。
  • :after
    • リクエストが開始された後、:loading の直前に、呼ばれます。
  • :submit
    • (submit する)フォームエレメントの親となる DOM エレメントの ID を指定できます。デフォルトではカレントフォームですが、テーブルの行にすることも、別の DOM エレメントにすることもできます。(☆)


追記:
「満足せる豚。眠たげなポチ。」の tanabe sunao さんが☆のところを訳してくれました。感謝！　そっくり入れ替えました。