# class ActionController::Responder

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`.

### Constants

ACTIONS_FOR_VERBS

### Attributes

controller[R]
format[R]
options[R]
request[R]
resource[R]
resources[R]

### Public Class Methods

call(*args) click to toggle source

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

    # File lib/action_controller/metal/responder.rb, line 145
    def self.call(*args)
      new(*args).respond
    end

new(controller, resources, options={}) click to toggle source

    # File 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

### Public Instance Methods

respond() click to toggle source

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

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

to_format() click to toggle source

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 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() click to toggle source

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

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

to_js() click to toggle source

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

    # File lib/action_controller/metal/responder.rb, line 166
    def to_js
      default_render
    end

### Protected Instance Methods

api_behavior(error) click to toggle source

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

    # File 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()
Alias for: resource_location
default_action() click to toggle source

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

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

default_render() click to toggle source

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

    # File 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={}) click to toggle source

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 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() click to toggle source

    # File lib/action_controller/metal/responder.rb, line 257
    def display_errors
      controller.render format => resource_errors, :status => :unprocessable_entity
    end

has_errors?() click to toggle source

Check whether the resource has errors.

    # File lib/action_controller/metal/responder.rb, line 263
    def has_errors?
      resource.respond_to?(:errors) && !resource.errors.empty?
    end

json_resource_errors() click to toggle source

    # File lib/action_controller/metal/responder.rb, line 278
    def json_resource_errors
      {:errors => resource.errors}
    end

resource_errors() click to toggle source

    # File 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() click to toggle source

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

    # File lib/action_controller/metal/responder.rb, line 219
    def resource_location
      options[:location] || resources
    end

Also aliased as: navigation_location, api_location
resourceful?() click to toggle source

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

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

response_overridden?() click to toggle source

    # File lib/action_controller/metal/responder.rb, line 282
    def response_overridden?
      @default_response.present?
    end