2010-03-17 18:09:28 -04:00
|
|
|
require 'active_support/json'
|
|
|
|
|
2009-08-06 17:48:48 -04:00
|
|
|
module ActionController #:nodoc:
|
2010-08-26 17:10:00 -04:00
|
|
|
# Responsible for exposing a resource to different mime requests,
|
2009-08-08 05:07:07 -04:00
|
|
|
# usually depending on the HTTP verb. The responder is triggered when
|
2010-01-16 16:56:20 -05:00
|
|
|
# <code>respond_with</code> is called. The simplest case to study is a GET request:
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
|
|
|
# class PeopleController < ApplicationController
|
|
|
|
# respond_to :html, :xml, :json
|
|
|
|
#
|
|
|
|
# def index
|
2011-07-07 12:12:09 -04:00
|
|
|
# @people = Person.all
|
2009-08-06 17:48:48 -04:00
|
|
|
# respond_with(@people)
|
|
|
|
# end
|
|
|
|
# end
|
|
|
|
#
|
2010-01-16 16:56:20 -05:00
|
|
|
# When a request comes in, for example for an XML response, three steps happen:
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
2010-01-16 16:56:20 -05:00
|
|
|
# 1) the responder searches for a template at people/index.xml;
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
2010-01-16 16:56:20 -05:00
|
|
|
# 2) if the template is not available, it will invoke <code>#to_xml</code> on the given resource;
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
2010-01-16 16:56:20 -05:00
|
|
|
# 3) if the responder does not <code>respond_to :to_xml</code>, call <code>#to_format</code> on it.
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
|
|
|
# === Builtin HTTP verb semantics
|
|
|
|
#
|
2010-08-26 17:10:00 -04:00
|
|
|
# The default \Rails responder holds semantics for each HTTP verb. Depending on the
|
2009-08-06 17:48:48 -04:00
|
|
|
# content type, verb and the resource status, it will behave differently.
|
|
|
|
#
|
2010-08-26 17:10:00 -04:00
|
|
|
# Using \Rails default responder, a POST request for creating an object could
|
2009-08-06 17:48:48 -04:00
|
|
|
# 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
|
|
|
|
#
|
2011-05-06 17:03:55 -04:00
|
|
|
# The same happens for PATCH/PUT and DELETE requests.
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
|
|
|
# === Nested resources
|
|
|
|
#
|
2010-01-16 16:56:20 -05:00
|
|
|
# You can supply nested resources as you do in <code>form_for</code> and <code>polymorphic_url</code>.
|
2009-08-06 17:48:48 -04:00
|
|
|
# Consider the project has many tasks example. The create action for
|
|
|
|
# TasksController would be like:
|
|
|
|
#
|
|
|
|
# def create
|
|
|
|
# @project = Project.find(params[:project_id])
|
2012-04-04 02:40:39 -04:00
|
|
|
# @task = @project.tasks.build(params[:task])
|
2009-08-06 17:48:48 -04:00
|
|
|
# flash[:notice] = 'Task was successfully created.' if @task.save
|
2009-08-13 04:27:41 -04:00
|
|
|
# respond_with(@project, @task)
|
2009-08-06 17:48:48 -04:00
|
|
|
# end
|
|
|
|
#
|
2011-05-05 06:01:15 -04:00
|
|
|
# Giving several resources ensures that the responder will redirect to
|
2010-01-16 16:56:20 -05:00
|
|
|
# <code>project_task_url</code> instead of <code>task_url</code>.
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
2010-01-16 16:56:20 -05:00
|
|
|
# Namespaced and singleton resources require a symbol to be given, as in
|
2009-08-06 17:48:48 -04:00
|
|
|
# polymorphic urls. If a project has one manager which has many tasks, it
|
|
|
|
# should be invoked as:
|
|
|
|
#
|
2009-08-13 04:27:41 -04:00
|
|
|
# respond_with(@project, :manager, @task)
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
2011-05-05 06:01:15 -04:00
|
|
|
# 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]
|
|
|
|
#
|
2011-03-31 13:00:05 -04:00
|
|
|
# === Custom options
|
|
|
|
#
|
2011-11-11 12:37:54 -05:00
|
|
|
# <code>respond_with</code> also allows you to pass options that are forwarded
|
|
|
|
# to the underlying render call. Those options are only applied for success
|
2011-03-31 13:00:05 -04:00
|
|
|
# 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
|
|
|
|
#
|
2011-11-11 12:37:54 -05:00
|
|
|
# This will return status 201 if the task was saved successfully. If not,
|
2011-03-31 13:00:05 -04:00
|
|
|
# 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 <code>respond_with</code>:
|
|
|
|
#
|
|
|
|
# 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 <code>respond_with</code> with a block follows the same syntax as <code>respond_to</code>.
|
2009-08-08 05:07:07 -04:00
|
|
|
class Responder
|
2009-08-29 11:48:11 -04:00
|
|
|
attr_reader :controller, :request, :format, :resource, :resources, :options
|
2009-05-07 11:29:22 -04:00
|
|
|
|
2011-05-06 17:03:55 -04:00
|
|
|
DEFAULT_ACTIONS_FOR_VERBS = {
|
2009-12-02 19:47:09 -05:00
|
|
|
:post => :new,
|
2011-05-06 17:03:55 -04:00
|
|
|
:patch => :edit,
|
2009-12-02 19:47:09 -05:00
|
|
|
:put => :edit
|
|
|
|
}
|
|
|
|
|
2009-08-13 04:27:41 -04:00
|
|
|
def initialize(controller, resources, options={})
|
2009-08-06 17:48:48 -04:00
|
|
|
@controller = controller
|
2010-08-19 14:15:46 -04:00
|
|
|
@request = @controller.request
|
|
|
|
@format = @controller.formats.first
|
2010-06-26 09:48:47 -04:00
|
|
|
@resource = resources.last
|
2009-08-29 11:48:11 -04:00
|
|
|
@resources = resources
|
2009-08-06 17:48:48 -04:00
|
|
|
@options = options
|
2009-11-11 11:45:21 -05:00
|
|
|
@action = options.delete(:action)
|
2012-03-05 21:06:02 -05:00
|
|
|
@default_response = options.delete(:default_response)
|
2009-08-06 17:48:48 -04:00
|
|
|
end
|
|
|
|
|
|
|
|
delegate :head, :render, :redirect_to, :to => :controller
|
2011-05-06 17:03:55 -04:00
|
|
|
delegate :get?, :post?, :patch?, :put?, :delete?, :to => :request
|
2009-05-28 10:49:02 -04:00
|
|
|
|
2009-11-11 11:45:21 -05:00
|
|
|
# Undefine :to_json and :to_yaml since it's defined on Object
|
2009-10-19 21:46:59 -04:00
|
|
|
undef_method(:to_json) if method_defined?(:to_json)
|
2009-11-11 11:45:21 -05:00
|
|
|
undef_method(:to_yaml) if method_defined?(:to_yaml)
|
2009-08-06 17:48:48 -04:00
|
|
|
|
2009-08-08 05:07:07 -04:00
|
|
|
# Initializes a new responder an invoke the proper format. If the format is
|
2009-08-06 17:48:48 -04:00
|
|
|
# not defined, call to_format.
|
|
|
|
#
|
|
|
|
def self.call(*args)
|
2009-12-01 10:11:24 -05:00
|
|
|
new(*args).respond
|
|
|
|
end
|
|
|
|
|
|
|
|
# Main entry point for responder responsible to dispatch to the proper format.
|
|
|
|
#
|
|
|
|
def respond
|
2010-12-27 03:30:36 -05:00
|
|
|
method = "to_#{format}"
|
2009-12-01 10:11:24 -05:00
|
|
|
respond_to?(method) ? send(method) : to_format
|
2009-03-19 18:45:48 -04:00
|
|
|
end
|
2009-05-19 21:05:16 -04:00
|
|
|
|
2009-08-06 17:48:48 -04:00
|
|
|
# HTML format does not render the resource, it always attempt to render a
|
|
|
|
# template.
|
|
|
|
#
|
|
|
|
def to_html
|
2009-08-29 11:48:11 -04:00
|
|
|
default_render
|
2009-11-11 11:45:21 -05:00
|
|
|
rescue ActionView::MissingTemplate => e
|
|
|
|
navigation_behavior(e)
|
2009-05-21 17:22:07 -04:00
|
|
|
end
|
|
|
|
|
2011-06-30 10:47:14 -04:00
|
|
|
# to_js simply tries to render a template. If no template is found, raises the error.
|
|
|
|
def to_js
|
|
|
|
default_render
|
|
|
|
end
|
|
|
|
|
2010-01-16 16:56:20 -05:00
|
|
|
# All other formats follow the procedure below. First we try to render a
|
2009-08-29 10:18:37 -04:00
|
|
|
# template, if the template is not available, we verify if the resource
|
|
|
|
# responds to :to_format and display it.
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
|
|
|
def to_format
|
2012-03-05 21:06:02 -05:00
|
|
|
if get? || !has_errors? || response_overridden?
|
2011-03-31 12:18:11 -04:00
|
|
|
default_render
|
|
|
|
else
|
|
|
|
display_errors
|
|
|
|
end
|
2009-11-11 11:45:21 -05:00
|
|
|
rescue ActionView::MissingTemplate => e
|
|
|
|
api_behavior(e)
|
|
|
|
end
|
2009-05-28 10:49:02 -04:00
|
|
|
|
2009-11-11 11:45:21 -05:00
|
|
|
protected
|
|
|
|
|
2010-08-26 17:10:00 -04:00
|
|
|
# This is the common behavior for formats associated with browsing, like :html, :iphone and so forth.
|
2009-11-11 11:45:21 -05:00
|
|
|
def navigation_behavior(error)
|
|
|
|
if get?
|
|
|
|
raise error
|
2009-12-02 19:47:09 -05:00
|
|
|
elsif has_errors? && default_action
|
2009-11-11 11:45:21 -05:00
|
|
|
render :action => default_action
|
|
|
|
else
|
2010-06-26 09:48:47 -04:00
|
|
|
redirect_to navigation_location
|
2009-11-11 11:45:21 -05:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2010-08-26 17:10:00 -04:00
|
|
|
# This is the common behavior for formats associated with APIs, such as :xml and :json.
|
2009-11-11 11:45:21 -05:00
|
|
|
def api_behavior(error)
|
2010-04-07 10:18:13 -04:00
|
|
|
raise error unless resourceful?
|
|
|
|
|
2009-08-06 17:48:48 -04:00
|
|
|
if get?
|
|
|
|
display resource
|
|
|
|
elsif post?
|
2010-06-26 09:48:47 -04:00
|
|
|
display resource, :status => :created, :location => api_location
|
2009-08-06 17:48:48 -04:00
|
|
|
else
|
2011-10-26 03:31:56 -04:00
|
|
|
head :no_content
|
2009-05-22 15:28:40 -04:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2009-08-06 17:48:48 -04:00
|
|
|
# Checks whether the resource responds to the current format or not.
|
|
|
|
#
|
|
|
|
def resourceful?
|
2010-12-27 03:30:36 -05:00
|
|
|
resource.respond_to?("to_#{format}")
|
2009-08-06 17:48:48 -04:00
|
|
|
end
|
2009-05-22 15:28:40 -04:00
|
|
|
|
2009-08-29 11:48:11 -04:00
|
|
|
# Returns the resource location by retrieving it from the options or
|
|
|
|
# returning the resources array.
|
|
|
|
#
|
|
|
|
def resource_location
|
|
|
|
options[:location] || resources
|
|
|
|
end
|
2010-06-26 09:48:47 -04:00
|
|
|
alias :navigation_location :resource_location
|
|
|
|
alias :api_location :resource_location
|
2009-08-29 11:48:11 -04:00
|
|
|
|
2011-11-11 12:37:54 -05:00
|
|
|
# If a response block was given, use it, otherwise call render on
|
2009-08-29 11:48:11 -04:00
|
|
|
# controller.
|
|
|
|
#
|
|
|
|
def default_render
|
2012-03-05 21:06:02 -05:00
|
|
|
if @default_response
|
|
|
|
@default_response.call(options)
|
|
|
|
else
|
|
|
|
controller.default_render(options)
|
|
|
|
end
|
2009-08-29 11:48:11 -04:00
|
|
|
end
|
|
|
|
|
2010-01-16 16:56:20 -05:00
|
|
|
# Display is just a shortcut to render a resource with the current format.
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
|
|
|
# display @user, :status => :ok
|
|
|
|
#
|
2010-01-16 16:56:20 -05:00
|
|
|
# For XML requests it's equivalent to:
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
|
|
|
# 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
|
|
|
|
#
|
|
|
|
def display(resource, given_options={})
|
2009-08-29 11:48:11 -04:00
|
|
|
controller.render given_options.merge!(options).merge!(format => resource)
|
2009-08-06 17:48:48 -04:00
|
|
|
end
|
2009-05-21 23:22:18 -04:00
|
|
|
|
2011-03-31 12:18:11 -04:00
|
|
|
def display_errors
|
2011-10-10 01:42:12 -04:00
|
|
|
controller.render format => resource_errors, :status => :unprocessable_entity
|
2011-03-31 12:18:11 -04:00
|
|
|
end
|
|
|
|
|
2010-01-16 16:56:20 -05:00
|
|
|
# Check whether the resource has errors.
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
|
|
|
def has_errors?
|
|
|
|
resource.respond_to?(:errors) && !resource.errors.empty?
|
|
|
|
end
|
2009-05-28 10:49:02 -04:00
|
|
|
|
2011-05-06 17:03:55 -04:00
|
|
|
# By default, render the <code>:edit</code> action for HTML requests with errors, unless
|
|
|
|
# the verb was POST.
|
2009-08-06 17:48:48 -04:00
|
|
|
#
|
|
|
|
def default_action
|
2011-05-06 17:03:55 -04:00
|
|
|
@action ||= DEFAULT_ACTIONS_FOR_VERBS[request.request_method_symbol]
|
2009-08-06 17:48:48 -04:00
|
|
|
end
|
2010-10-11 13:37:03 -04:00
|
|
|
|
2011-10-10 01:42:12 -04:00
|
|
|
def resource_errors
|
2012-02-20 14:02:47 -05:00
|
|
|
respond_to?("#{format}_resource_errors", true) ? send("#{format}_resource_errors") : resource.errors
|
2011-10-10 01:42:12 -04:00
|
|
|
end
|
|
|
|
|
|
|
|
def json_resource_errors
|
|
|
|
{:errors => resource.errors}
|
|
|
|
end
|
2012-03-05 21:06:02 -05:00
|
|
|
|
|
|
|
def response_overridden?
|
|
|
|
@default_response.present?
|
|
|
|
end
|
2009-03-17 21:04:22 -04:00
|
|
|
end
|
2009-04-17 19:34:49 -04:00
|
|
|
end
|