Skip to content
This repository
tag: v3.0.5
Fetching contributors…

Cannot retrieve contributors at this time

file 304 lines (283 sloc) 10.41 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304
require 'abstract_controller/collector'
require 'active_support/core_ext/class/attribute'

module ActionController #:nodoc:
  module MimeResponds #:nodoc:
    extend ActiveSupport::Concern

    included do
      class_attribute :responder, :mimes_for_respond_to
      self.responder = ActionController::Responder
      clear_respond_to
    end

    module ClassMethods
      # Defines mime types that are rendered by default when invoking
      # <tt>respond_with</tt>.
      #
      # Examples:
      #
      # respond_to :html, :xml, :json
      #
      # Specifies that all actions in the controller respond to requests
      # for <tt>:html</tt>, <tt>:xml</tt> and <tt>:json</tt>.
      #
      # To specify on per-action basis, use <tt>:only</tt> and
      # <tt>:except</tt> with an array of actions or a single action:
      #
      # respond_to :html
      # respond_to :xml, :json, :except => [ :edit ]
      #
      # This specifies that all actions respond to <tt>:html</tt>
      # and all actions except <tt>:edit</tt> respond to <tt>:xml</tt> and
      # <tt>:json</tt>.
      #
      # respond_to :rjs, :only => :create
      #
      # This specifies that the <tt>:create</tt> action and no other responds
      # to <tt>:rjs</tt>.
      def respond_to(*mimes)
        options = mimes.extract_options!

        only_actions = Array(options.delete(:only))
        except_actions = Array(options.delete(:except))

        new = mimes_for_respond_to.dup
        mimes.each do |mime|
          mime = mime.to_sym
          new[mime] = {}
          new[mime][:only] = only_actions unless only_actions.empty?
          new[mime][:except] = except_actions unless except_actions.empty?
        end
        self.mimes_for_respond_to = new.freeze
      end

      # Clear all mime types in <tt>respond_to</tt>.
      #
      def clear_respond_to
        self.mimes_for_respond_to = ActiveSupport::OrderedHash.new.freeze
      end
    end

    # 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.find(:all)
    # end
    #
    # Here's the same action, with web-service support baked in:
    #
    # def index
    # @people = Person.find(: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
    # (format.js), then it is an RJS request and we render the RJS 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.find(: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.find(:all)
    # respond_with(@person)
    # end
    # end
    #
    # Be sure to check respond_with and respond_to documentation for more examples.
    #
    def respond_to(*mimes, &block)
      raise ArgumentError, "respond_to takes either types or a block, never both" if mimes.any? && block_given?

      if response = retrieve_response_from_mimes(mimes, &block)
        response.call
      end
    end

    # 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 destroy
    # @user = User.find(params[:id])
    # 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.
    #
    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 response = retrieve_response_from_mimes(&block)
        options = resources.size == 1 ? {} : resources.extract_options!
        options.merge!(:default_response => response)
        (options.delete(:responder) || self.class.responder).call(self, resources, options)
      end
    end

  protected

    # Collect mimes declared in the class method respond_to valid for the
    # current action.
    #
    def collect_mimes_from_class_level #:nodoc:
      action = action_name.to_sym

      self.class.mimes_for_respond_to.keys.select do |mime|
        config = self.class.mimes_for_respond_to[mime]

        if config[:except]
          !config[:except].include?(action)
        elsif config[:only]
          config[:only].include?(action)
        else
          true
        end
      end
    end

    # Collects mimes and return the response for the negotiated format. Returns
    # nil if :not_acceptable was sent to the client.
    #
    def retrieve_response_from_mimes(mimes=nil, &block)
      collector = Collector.new { default_render }
      mimes ||= collect_mimes_from_class_level
      mimes.each { |mime| collector.send(mime) }
      block.call(collector) if block_given?

      if format = request.negotiate_mime(collector.order)
        self.content_type ||= format.to_s
        lookup_context.freeze_formats([format.to_sym])
        collector.response_for(format)
      else
        head :not_acceptable
        nil
      end
    end

    class Collector #:nodoc:
      include AbstractController::Collector
      attr_accessor :order

      def initialize(&block)
        @order, @responses, @default_response = [], {}, block
      end

      def any(*args, &block)
        if args.any?
          args.each { |type| send(type, &block) }
        else
          custom(Mime::ALL, &block)
        end
      end
      alias :all :any

      def custom(mime_type, &block)
        mime_type = mime_type.is_a?(Mime::Type) ? mime_type : Mime::Type.lookup(mime_type.to_s)
        @order << mime_type
        @responses[mime_type] ||= block
      end

      def response_for(mime)
        @responses[mime] || @responses[Mime::ALL] || @default_response
      end
    end
  end
end
Something went wrong with that request. Please try again.