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.
Built-in 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", status: :unprocessable_entity } format.xml { render xml: @user.errors, status: :unprocessable_entity } end end end
The same happens for PATCH/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.tasks.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.tasks.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. You can also override the location to redirect to:
respond_with(@project, location: root_path)
To customize the failure scenario, you can pass a block to respond_with
:
def create @project = Project.find(params[:project_id]) @task = @project.tasks.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", status: :unprocessable_entity } end end end
Using respond_with
with a block follows the same syntax as respond_to
.
Constants
- DEFAULT_ACTIONS_FOR_VERBS
Attributes
Public Class Methods
Initializes a new responder and invokes the proper format. If the format is not defined, call to_format.
# File lib/action_controller/responder.rb, line 160 def self.call(*args) new(*args).respond end
# File lib/action_controller/responder.rb, line 134 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) if options[:location].respond_to?(:call) location = options.delete(:location) options[:location] = location.call unless has_errors? end end
Public Instance Methods
Main entry point for responder responsible to dispatch to the proper format.
# File lib/action_controller/responder.rb, line 166 def respond method = "to_#{format}" respond_to?(method) ? send(method) : to_format end
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/responder.rb, line 189 def to_format if !get? && has_errors? && !response_overridden? display_errors elsif has_view_rendering? || response_overridden? default_render else api_behavior end rescue ActionView::MissingTemplate api_behavior end
HTML format does not render the resource, it always attempt to render a template.
# File lib/action_controller/responder.rb, line 174 def to_html default_render rescue ActionView::MissingTemplate => e navigation_behavior(e) end
to_js
simply tries to render a template. If no template is found, raises the error.
# File lib/action_controller/responder.rb, line 181 def to_js default_render end
Protected Instance Methods
This is the common behavior for formats associated with APIs, such as :xml and :json.
# File lib/action_controller/responder.rb, line 215 def api_behavior raise MissingRenderer.new(format) unless has_renderer? if get? display resource elsif post? display resource, status: :created, location: api_location else head :no_content end end
By default, render the :edit
action for HTML requests with errors, unless the verb was POST.
# File lib/action_controller/responder.rb, line 294 def default_action @action ||= DEFAULT_ACTIONS_FOR_VERBS[request.request_method_symbol] end
If a response block was given, use it, otherwise call render on controller.
# File lib/action_controller/responder.rb, line 239 def default_render if @default_response @default_response.call(options) elsif !get? && has_errors? controller.render({ status: error_status }.merge!(options)) else controller.render(options) end end
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/responder.rb, line 266 def display(resource, given_options = {}) controller.render given_options.merge!(options).merge!(format => resource) end
# File lib/action_controller/responder.rb, line 270 def display_errors # TODO: use `error_status` once we switch the default to be `unprocessable_entity`, # otherwise we'd be changing this behavior here now. controller.render format => resource_errors, :status => :unprocessable_entity end
# File lib/action_controller/responder.rb, line 310 def error_rendering_options if options[:render] options[:render] else { action: default_action, status: error_status } end end
Check whether the resource has errors.
# File lib/action_controller/responder.rb, line 278 def has_errors? resource.respond_to?(:errors) && !resource.errors.empty? end
Check whether the necessary Renderer is available
# File lib/action_controller/responder.rb, line 283 def has_renderer? Renderers::RENDERERS.include?(format) end
# File lib/action_controller/responder.rb, line 287 def has_view_rendering? controller.class.include? ActionView::Rendering end
# File lib/action_controller/responder.rb, line 302 def json_resource_errors { errors: resource.errors } end
# File lib/action_controller/responder.rb, line 298 def resource_errors respond_to?("#{format}_resource_errors", true) ? send("#{format}_resource_errors") : resource.errors end
Returns the resource location by retrieving it from the options or returning the resources array.
# File lib/action_controller/responder.rb, line 230 def resource_location options[:location] || resources end
# File lib/action_controller/responder.rb, line 306 def response_overridden? @default_response.present? end