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 <code>#to_xml</code> on the given resource;

3) if the responder does not <code>respond_to :to_xml</code>, call <code>#to_format</code> 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.

Methods
A
C
D
H
J
N
R
T
Constants
ACTIONS_FOR_VERBS = { :post => :new, :put => :edit }
 
Attributes
[R] controller
[R] format
[R] options
[R] request
[R] resource
[R] resources
Class Public methods
call(*args)

Initializes a new responder an invoke the proper format. If the format is not defined, call to_format.

# File actionpack/lib/action_controller/metal/responder.rb, line 145
def self.call(*args)
  new(*args).respond
end
new(controller, resources, options={})
# File actionpack/lib/action_controller/metal/responder.rb, line 124
def initialize(controller, resources, options={})
  @controller = controller
  @request = @controller.request
  @format = @controller.formats.first
  @resource = resources.last
  @resources = resources
  @options = options
  @action = options.delete(:action)
  @default_response = options.delete(:default_response)
end
Instance Public methods
respond()

Main entry point for responder responsible to dispatch to the proper format.

# File actionpack/lib/action_controller/metal/responder.rb, line 151
def respond
  method = "to_#{format}"
  respond_to?(method) ? send(method) : to_format
end
to_format()

All other formats follow the procedure below. First we try to render a template, if the template is not available, we verify if the resource responds to :#to_format and display it.

# File actionpack/lib/action_controller/metal/responder.rb, line 174
def to_format
  if get? || !has_errors? || response_overridden?
    default_render
  else
    display_errors
  end
rescue ActionView::MissingTemplate => e
  api_behavior(e)
end
to_html()

HTML format does not render the resource, it always attempt to render a template.

# File actionpack/lib/action_controller/metal/responder.rb, line 159
def to_html
  default_render
rescue ActionView::MissingTemplate => e
  navigation_behavior(e)
end
to_js()

#to_js simply tries to render a template. If no template is found, raises the error.

# File actionpack/lib/action_controller/metal/responder.rb, line 166
def to_js
  default_render
end
Instance Protected methods
api_behavior(error)

This is the common behavior for formats associated with APIs, such as :xml and :json.

# File actionpack/lib/action_controller/metal/responder.rb, line 198
def api_behavior(error)
  raise error unless resourceful?

  if get?
    display resource
  elsif post?
    display resource, :status => :created, :location => api_location
  else
    head :no_content
  end
end
api_location()
default_action()

By default, render the :edit action for HTML requests with failure, unless the verb is POST.

# File actionpack/lib/action_controller/metal/responder.rb, line 270
def default_action
  @action ||= ACTIONS_FOR_VERBS[request.request_method_symbol]
end
default_render()

If a response block was given, use it, otherwise call render on controller.

# File actionpack/lib/action_controller/metal/responder.rb, line 228
def default_render
  if @default_response
    @default_response.call(options)
  else
    controller.default_render(options)
  end
end
display(resource, given_options={})

Display is just a shortcut to render a resource with the current format.

display @user, :status => :ok

For XML requests it’s equivalent to:

render :xml => @user, :status => :ok

Options sent by the user are also used:

respond_with(@user, :status => :created)
display(@user, :status => :ok)

Results in:

render :xml => @user, :status => :created
# File actionpack/lib/action_controller/metal/responder.rb, line 253
def display(resource, given_options={})
  controller.render given_options.merge!(options).merge!(format => resource)
end
display_errors()
# File actionpack/lib/action_controller/metal/responder.rb, line 257
def display_errors
  controller.render format => resource_errors, :status => :unprocessable_entity
end
has_errors?()

Check whether the resource has errors.

# File actionpack/lib/action_controller/metal/responder.rb, line 263
def has_errors?
  resource.respond_to?(:errors) && !resource.errors.empty?
end
json_resource_errors()
# File actionpack/lib/action_controller/metal/responder.rb, line 278
def json_resource_errors
  {:errors => resource.errors}
end
navigation_behavior(error)

This is the common behavior for formats associated with browsing, like :html, :iphone and so forth.

# File actionpack/lib/action_controller/metal/responder.rb, line 187
def navigation_behavior(error)
  if get?
    raise error
  elsif has_errors? && default_action
    render :action => default_action
  else
    redirect_to navigation_location
  end
end
navigation_location()
resource_errors()
# File actionpack/lib/action_controller/metal/responder.rb, line 274
def resource_errors
  respond_to?("#{format}_resource_errors", true) ? send("#{format}_resource_errors") : resource.errors
end
resource_location()

Returns the resource location by retrieving it from the options or returning the resources array.

Also aliased as: navigation_location, api_location
# File actionpack/lib/action_controller/metal/responder.rb, line 219
def resource_location
  options[:location] || resources
end
resourceful?()

Checks whether the resource responds to the current format or not.

# File actionpack/lib/action_controller/metal/responder.rb, line 212
def resourceful?
  resource.respond_to?("to_#{format}")
end
response_overridden?()
# File actionpack/lib/action_controller/metal/responder.rb, line 282
def response_overridden?
  @default_response.present?
end