- 1.0.0
- 1.1.6
- 1.2.6
- 2.0.3
- 2.1.0
- 2.2.1
- 2.3.8
- 3.0.0 (0)
- 3.0.9 (-1)
- 3.1.0 (12)
- 3.2.1 (0)
- 3.2.8 (0)
- 3.2.13 (0)
- 4.0.2 (0)
- 4.1.8 (1)
- 4.2.1
- 4.2.7
- 4.2.9
- 5.0.0.1
- 5.1.7
- 5.2.3
- 6.0.0
- 6.1.3.1
- 6.1.7.7
- 7.0.0
- 7.1.3.2
- 7.1.3.4
- What's this?
Responsible for exposing a resource to different mime requests, usually depending on the HTTP verb. The responder is triggered when respond_with is called. The simplest case to study is a GET request:
class PeopleController < ApplicationController respond_to :html, :xml, :json def index @people = Person.all respond_with(@people) end end
When a request comes in, for example for an XML response, three steps happen:
1) the responder searches for a template at people/index.xml; 2) if the template is not available, it will invoke #to_xml on the given resource; 3) if the responder does not respond_to :to_xml, call #to_format on it.
Builtin HTTP verb semantics
The default Rails responder holds semantics for each HTTP verb. Depending on the content type, verb and the resource status, it will behave differently.
Using Rails default responder, a POST request for creating an object could be written as:
def create @user = User.new(params[:user]) flash[:notice] = 'User was successfully created.' if @user.save respond_with(@user) end
Which is exactly the same as:
def create @user = User.new(params[:user]) respond_to do |format| if @user.save flash[:notice] = 'User was successfully created.' format.html { redirect_to(@user) } format.xml { render :xml => @user, :status => :created, :location => @user } else format.html { render :action => "new" } format.xml { render :xml => @user.errors, :status => :unprocessable_entity } end end end
The same happens for PUT and DELETE requests.
Nested resources
You can supply nested resources as you do in form_for and polymorphic_url. Consider the project has many tasks example. The create action for TasksController would be like:
def create @project = Project.find(params[:project_id]) @task = @project.comments.build(params[:task]) flash[:notice] = 'Task was successfully created.' if @task.save respond_with(@project, @task) end
Giving several resources ensures that the responder will redirect to project_task_url instead of task_url.
Namespaced and singleton resources require a symbol to be given, as in polymorphic urls. If a project has one manager which has many tasks, it should be invoked as:
respond_with(@project, :manager, @task)
Note that if you give an array, it will be treated as a collection, so the following is not equivalent:
respond_with [@project, :manager, @task]
Custom options
respond_with also allows you to pass options that are forwarded to the underlying render call. Those options are only applied for success scenarios. For instance, you can do the following in the create method above:
def create @project = Project.find(params[:project_id]) @task = @project.comments.build(params[:task]) flash[:notice] = 'Task was successfully created.' if @task.save respond_with(@project, @task, :status => 201) end
This will return status 201 if the task was saved successfully. If not, it will simply ignore the given options and return status 422 and the resource errors. To customize the failure scenario, you can pass a a block to respond_with:
def create @project = Project.find(params[:project_id]) @task = @project.comments.build(params[:task]) respond_with(@project, @task, :status => 201) do |format| if @task.save flash[:notice] = 'Task was successfully created.' else format.html { render "some_special_template" } end end end
Using respond_with with a block follows the same syntax as respond_to.
Constants
ACTIONS_FOR_VERBS = { :post => :new, :put => :edit }
Attributes
[R] | controller | |
[R] | request | |
[R] | format | |
[R] | resource | |
[R] | resources | |
[R] | options |