Ruby on Rails latest stable (v4.0.2) - 3 notes - Class: ActionController::MimeResponds
respond_with(*resources, &block) public

For a given controller action, respond_with generates an appropriate response based on the mime-type requested by the client.

If the method is called with just a resource, as in this example -

class PeopleController < ApplicationController
  respond_to :html, :xml, :json

  def index
    @people = Person.all
    respond_with @people

then the mime-type of the response is typically selected based on the request’s Accept header and the set of available formats declared by previous calls to the controller’s class method respond_to. Alternatively the mime-type can be selected by explicitly setting request.format in the controller.

If an acceptable format is not identified, the application returns a ‘406 - not acceptable’ status. Otherwise, the default response is to render a template named after the current action and the selected format, e.g. index.html.erb. If no template is available, the behavior depends on the selected format:

  • for an html response - if the request method is get, an exception is raised but for other requests such as post the response depends on whether the resource has any validation errors (i.e. assuming that an attempt has been made to save the resource, e.g. by a create action) -

    1. If there are no errors, i.e. the resource was saved successfully, the response redirect's to the resource i.e. its show action.

    2. If there are validation errors, the response renders a default action, which is :new for a post request or :edit for patch or put.

    Thus an example like this -

    respond_to :html, :xml
    def create
      @user = User.new(params[:user])
      flash[:notice] = 'User was successfully created.' if @user.save

    is equivalent, in the absence of create.html.erb, to -

    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 }
          format.html { render action: "new" }
          format.xml { render xml: @user }
  • for a javascript request - if the template isn’t found, an exception is raised.

  • for other requests - i.e. data formats such as xml, json, csv etc, if the resource passed to respond_with responds to to_<format>, the method attempts to render the resource in the requested format directly, e.g. for an xml request, the response is equivalent to calling render xml: resource.

Nested resources

As outlined above, the resources argument passed to respond_with can play two roles. It can be used to generate the redirect url for successful html requests (e.g. for create actions when no template exists), while for formats other than html and javascript it is the object that gets rendered, by being converted directly to the required format (again assuming no template exists).

For redirecting successful html requests, respond_with also supports the use of nested resources, which are supplied in the same way as in form_for and polymorphic_url. For example -

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)

This would cause respond_with to redirect to project_task_url instead of task_url. For request formats other than html or javascript, if multiple resources are passed in this way, it is the last one specified that is rendered.

Customizing response behavior

Like respond_to, respond_with may also be called with a block that can be used to overwrite any of the default responses, e.g. -

def create
  @user = User.new(params[:user])
  flash[:notice] = "User was successfully created." if @user.save

  respond_with(@user) do |format|
    format.html { render }

The argument passed to the block is an ActionController::MimeResponds::Collector object which stores the responses for the formats defined within the block. Note that formats with responses defined explicitly in this way do not have to first be declared using the class method respond_to.

Also, a hash passed to respond_with immediately after the specified resource(s) is interpreted as a set of options relevant to all formats. Any option accepted by render can be used, e.g.

respond_with @people, status: 200

However, note that these options are ignored after an unsuccessful attempt to save a resource, e.g. when automatically rendering :new after a post request.

Two additional options are relevant specifically to respond_with -

  1. :location - overwrites the default redirect location used after a successful html post request.

  2. :action - overwrites the default render action used after an unsuccessful html post request.

Show source
Register or log in to add new notes.
October 16, 2010 - (>= v3.0.0)
10 thanks

needs to be paired with respond_to

Needs to be paired with respond_to at the top of your class.

class MyController < ApplicationController
  respond_to :js, :html
October 8, 2011
5 thanks

Undocumented :location option

You can use undocumented :location option to override where respond_to sends if resource is valid, e.g. to redirect to products index page instead of a specific product’s page, use:

respond_with(@product, :location => products_url)  
June 24, 2011 - (v3.0.0 - v3.0.9)
1 thank

RailsCast about Responders

See Ryan Bate’s excellent RailsCast #224 about Responders in Rails 3.x: http://asciicasts.com/episodes/224-controllers-in-rails-3