# module ActionController::MimeResponds

### Public Instance Methods

respond_to(*mimes, &block) click to toggle source

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.to_xml }
      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

Be sure to check #respond_with and #respond_to documentation for more examples.

    # File lib/action_controller/metal/mime_responds.rb, line 191
    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 : default_render({})
      end
    end

respond_with(*resources, &block) click to toggle source

#respond_with wraps a resource around a responder for default representation. First it invokes #respond_to, if a response cannot be found (ie. no block for the request was given and template was not available), it instantiates an ActionController::Responder with the controller and resource.

#### Example¶ ↑

    def index
      @users = User.all
      respond_with(@users)
    end

It also accepts a block to be given. It’s used to overwrite a default response:

    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

All options given to #respond_with are sent to the underlying responder, except for the option :responder itself. Since the responder interface is quite simple (it just needs to respond to call), you can even give a proc to it.

In order to use #respond_with, first you need to declare the formats your controller responds to in the class level with a call to `respond_to`.

    # File lib/action_controller/metal/mime_responds.rb, line 232
    def respond_with(*resources, &block)
      raise "In order to use respond_with, first you need to declare the formats your " <<
            "controller responds to in the class level" if self.class.mimes_for_respond_to.empty?

      if collector = retrieve_collector_from_mimes(&block)
        options = resources.size == 1 ? {} : resources.extract_options!
        options[:default_response] = collector.response
        (options.delete(:responder) || self.class.responder).call(self, resources, options)
      end
    end