aboutsummaryrefslogtreecommitdiffstats
path: root/actionpack/lib/action_controller/mime_responds.rb
blob: 0b4c4b6793cb00c48ab5a5aa2ad140a0b18a4fba (plain) (blame)
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
module ActionController #:nodoc:
  module MimeResponds #:nodoc:
    def self.included(base)
      base.send(:include, ActionController::MimeResponds::InstanceMethods)
    end

    module InstanceMethods
      # 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 
      # (wants.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—a 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 note), 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
      # environment.rb as follows.
      # 
      #   Mime::Type.register "image/jpg", :jpg
      def respond_to(*types, &block)
        raise ArgumentError, "respond_to takes either types or a block, never both" unless types.any? ^ block
        block ||= lambda { |responder| types.each { |type| responder.send(type) } }
        responder = Responder.new(block.binding)
        block.call(responder)
        responder.respond
      end
    end
    
    class Responder #:nodoc:
      default_block_format = <<-END
        Proc.new { 
          @template.template_format = '%s'
          render :action => "\#{action_name}", :content_type => Mime::%s
        }
      END

      DEFAULT_BLOCKS = [:html, :js, :xml].inject({}) do |memo, ext| 
        default_block = default_block_format % [ext, ext.to_s.upcase]
        memo.update(ext => default_block)
      end
      
      def initialize(block_binding)
        @block_binding = block_binding
        @mime_type_priority = eval(
          "(params[:format] && Mime::EXTENSION_LOOKUP[params[:format]]) ? " +
          "[ Mime::EXTENSION_LOOKUP[params[:format]] ] : request.accepts", 
          block_binding
        )

        @order     = []
        @responses = {}
      end

      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
        
        if block_given?
          @responses[mime_type] = Proc.new do
            eval <<-END, @block_binding
              @template.template_format = '#{mime_type.to_sym}'
              response.content_type     = '#{mime_type.to_s}'
            END
            block.call
          end
        else
          if source = DEFAULT_BLOCKS[mime_type.to_sym]
            @responses[mime_type] = eval(source, @block_binding)
          else
            raise ActionController::RenderError, "Expected a block but none was given for custom mime handler #{mime_type}"
          end
        end
      end

      def any(*args, &block)
        args.each { |type| send(type, &block) }
      end
      
      def method_missing(symbol, &block)
        mime_constant = symbol.to_s.upcase
        
        if Mime::SET.include?(Mime.const_get(mime_constant))
          custom(Mime.const_get(mime_constant), &block)
        else
          super
        end
      end
      
      def respond
        for priority in @mime_type_priority
          if priority == Mime::ALL
            @responses[@order.first].call
            return
          else
            if priority === @order
              @responses[priority].call
              return # mime type match found, be happy and return
            end
          end
        end
        
        if @order.include?(Mime::ALL)
          @responses[Mime::ALL].call
        else
          eval 'render(:nothing => true, :status => "406 Not Acceptable")', @block_binding
        end
      end
    end
  end
end