Object
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.
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.
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]
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.
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 145: def self.call(*args) 146: new(*args).respond 147: end
# File lib/action_controller/metal/responder.rb, line 124 124: def initialize(controller, resources, options={}) 125: @controller = controller 126: @request = @controller.request 127: @format = @controller.formats.first 128: @resource = resources.last 129: @resources = resources 130: @options = options 131: @action = options.delete(:action) 132: @default_response = options.delete(:default_response) 133: end
Main entry point for responder responsible to dispatch to the proper format.
# File lib/action_controller/metal/responder.rb, line 151 151: def respond 152: method = "to_#{format}" 153: respond_to?(method) ? send(method) : to_format 154: 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/metal/responder.rb, line 174 174: def to_format 175: if get? || !has_errors? || response_overridden? 176: default_render 177: else 178: display_errors 179: end 180: rescue ActionView::MissingTemplate => e 181: api_behavior(e) 182: end
HTML format does not render the resource, it always attempt to render a template.
# File lib/action_controller/metal/responder.rb, line 159 159: def to_html 160: default_render 161: rescue ActionView::MissingTemplate => e 162: navigation_behavior(e) 163: end
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 166: def to_js 167: default_render 168: end
This is the common behavior for formats associated with APIs, such as :xml and :json.
# File lib/action_controller/metal/responder.rb, line 198 198: def api_behavior(error) 199: raise error unless resourceful? 200: 201: if get? 202: display resource 203: elsif post? 204: display resource, :status => :created, :location => api_location 205: else 206: head :no_content 207: end 208: end
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 270: def default_action 271: @action ||= ACTIONS_FOR_VERBS[request.request_method_symbol] 272: end
If a response block was given, use it, otherwise call render on controller.
# File lib/action_controller/metal/responder.rb, line 228 228: def default_render 229: if @default_response 230: @default_response.call(options) 231: else 232: controller.default_render(options) 233: end 234: 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/metal/responder.rb, line 253 253: def display(resource, given_options={}) 254: controller.render given_options.merge!(options).merge!(format => resource) 255: end
# File lib/action_controller/metal/responder.rb, line 257 257: def display_errors 258: controller.render format => resource_errors, :status => :unprocessable_entity 259: end
Check whether the resource has errors.
# File lib/action_controller/metal/responder.rb, line 263 263: def has_errors? 264: resource.respond_to?(:errors) && !resource.errors.empty? 265: end
# File lib/action_controller/metal/responder.rb, line 278 278: def json_resource_errors 279: {:errors => resource.errors} 280: end
# File lib/action_controller/metal/responder.rb, line 274 274: def resource_errors 275: respond_to?("#{format}_resource_errors", true) ? send("#{format}_resource_errors") : resource.errors 276: end
Returns the resource location by retrieving it from the options or returning the resources array.
# File lib/action_controller/metal/responder.rb, line 219 219: def resource_location 220: options[:location] || resources 221: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.