Module: ActionController::MimeResponds
- Extended by:
- ActiveSupport::Concern
- Defined in:
- lib/action_controller/metal/mime_responds.rb
Defined Under Namespace
Modules: ClassMethods Classes: Collector
Instance Method Summary collapse
-
#respond_to(*mimes, &block) ⇒ Object
Without web-service support, an action which collects the data for displaying a list of people might look something like this:.
-
#respond_with(*resources, &block) ⇒ Object
For a given controller action, respond_with generates an appropriate response based on the mime-type requested by the client.
Instance Method Details
#respond_to(*mimes, &block) ⇒ Object
Without web-service support, an action which collects the data for displaying a list of people might look something like this:
def index
@people = Person.all
end
Here’s the same action, with web-service support baked in:
def index
@people = Person.all
respond_to do |format|
format.html
format.xml { render xml: @people }
end
end
What that says is, “if the client wants HTML in response to this action, just respond as we would have before, but if the client wants XML, return them the list of people in XML format.” (Rails determines the desired response format from the HTTP Accept header submitted by the client.)
Supposing you have an action that adds a new person, optionally creating their company (by name) if it does not already exist, without web-services, it might look like this:
def create
@company = Company.find_or_create_by(name: params[:company][:name])
@person = @company.people.create(params[:person])
redirect_to(person_list_url)
end
Here’s the same action, with web-service support baked in:
def create
company = params[:person].delete(:company)
@company = Company.find_or_create_by(name: company[:name])
@person = @company.people.create(params[:person])
respond_to do |format|
format.html { redirect_to(person_list_url) }
format.js
format.xml { render xml: @person.to_xml(include: @company) }
end
end
If the client wants HTML, we just redirect them back to the person list. If they want JavaScript, then it is an Ajax request and we render the JavaScript template associated with this action. Lastly, if the client wants XML, we render the created person as XML, but with a twist: we also include the person’s company in the rendered XML, so you get something like this:
<person>
<id>...</id>
...
<company>
<id>...</id>
<name>...</name>
...
</company>
</person>
Note, however, the extra bit at the top of that action:
company = params[:person].delete(:company)
@company = Company.find_or_create_by(name: company[:name])
This is because the incoming XML document (if a web-service request is in process) can only contain a single root-node. So, we have to rearrange things so that the request looks like this (url-encoded):
person[name]=...&person[company][name]=...&...
And, like this (xml-encoded):
<person>
<name>...</name>
<company>
<name>...</name>
</company>
</person>
In other words, we make the request so that it operates on a single entity’s person. Then, in the action, we extract the company data from the request, find or create the company, and then create the new person with the remaining data.
Note that you can define your own XML parameter parser which would allow you to describe multiple entities in a single request (i.e., by wrapping them all in a single root node), but if you just go with the flow and accept Rails’ defaults, life will be much easier.
If you need to use a MIME type which isn’t supported by default, you can register your own handlers in config/initializers/mime_types.rb as follows.
Mime::Type.register "image/jpg", :jpg
Respond to also allows you to specify a common block for different formats by using any:
def index
@people = Person.all
respond_to do |format|
format.html
format.any(:xml, :json) { render request.format.to_sym => @people }
end
end
In the example above, if the format is xml, it will render:
render xml: @people
Or if the format is json:
render json: @people
Since this is a common pattern, you can use the class method respond_to with the respond_with method to have the same results:
class PeopleController < ApplicationController
respond_to :html, :xml, :json
def index
@people = Person.all
respond_with(@people)
end
end
Formats can have different variants.
The request variant is a specialization of the request format, like :tablet
, :phone
, or :desktop
.
We often want to render different html/json/xml templates for phones, tablets, and desktop browsers. Variants make it easy.
You can set the variant in a before_action
:
request.variant = :tablet if request.user_agent =~ /iPad/
Respond to variants in the action just like you respond to formats:
respond_to do |format|
format.html do |variant|
variant.tablet # renders app/views/projects/show.html+tablet.erb
variant.phone { extra_setup; render ... }
variant.none { special_setup } # executed only if there is no variant set
end
end
Provide separate templates for each format and variant:
app/views/projects/show.html.erb
app/views/projects/show.html+tablet.erb
app/views/projects/show.html+phone.erb
When you’re not sharing any code within the format, you can simplify defining variants using the inline syntax:
respond_to do |format|
format.js { render "trash" }
format.html.phone { redirect_to progress_path }
format.html.none { render "trash" }
end
Variants also support common ‘any`/`all` block that formats have.
It works for both inline:
respond_to do |format|
format.html.any { render text: "any" }
format.html.phone { render text: "phone" }
end
and block syntax:
respond_to do |format|
format.html do |variant|
variant.any(:tablet, :phablet){ render text: "any" }
variant.phone { render text: "phone" }
end
end
You can also set an array of variants:
request.variant = [:tablet, :phone]
which will work similarly to formats and MIME types negotiation. If there will be no :tablet variant declared, :phone variant will be picked:
respond_to do |format|
format.html.none
format.html.phone # this gets rendered
end
Be sure to check the documentation of respond_with
and ActionController::MimeResponds.respond_to
for more examples.
253 254 255 256 257 258 259 260 |
# File 'lib/action_controller/metal/mime_responds.rb', line 253 def respond_to(*mimes, &block) raise ArgumentError, "respond_to takes either types or a block, never both" if mimes.any? && block_given? if collector = retrieve_collector_from_mimes(mimes, &block) response = collector.response response ? response.call : render({}) end end |
#respond_with(*resources, &block) ⇒ Object
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
end
end
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 aspost
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 acreate
action) --
If there are no errors, i.e. the resource was saved successfully, the response
redirect
‘s to the resource i.e. itsshow
action. -
If there are validation errors, the response renders a default action, which is
:new
for apost
request or:edit
forpatch
orput
.
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 respond_with(@user) end
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 } else format.html { render action: "new" } format.xml { render xml: @user } end end end
-
-
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 toto_<format>
, the method attempts to render the resource in the requested format directly, e.g. for an xml request, the response is equivalent to callingrender 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)
end
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 }
end
end
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
-
-
:location
- overwrites the default redirect location used after a successful htmlpost
request. -
:action
- overwrites the default render action used after an unsuccessful htmlpost
request.
390 391 392 393 394 395 396 397 398 399 400 401 402 |
# File 'lib/action_controller/metal/mime_responds.rb', line 390 def respond_with(*resources, &block) if self.class.mimes_for_respond_to.empty? raise "In order to use respond_with, first you need to declare the " \ "formats your controller responds to in the class level." end if collector = retrieve_collector_from_mimes(&block) = resources.size == 1 ? {} : resources. = .clone [:default_response] = collector.response (.delete(:responder) || self.class.responder).call(self, resources, ) end end |