0
@@ -1,5 +1,7 @@
0
 *SVN*
0
 
0
+* Add documentation for respond_to. [Jamis Buck]
0
+
0
 * Fixed require of bluecloth and redcloth when gems haven't been loaded #4446 [murphy@cYcnus.de]
0
 
0
 * Update to Prototype 1.5.0_pre1 [Sam Stephenson]

0
@@ -5,6 +5,93 @@
0
     end
0
 
0
     module InstanceMethods
0
+      # Without web-service support, an action which collects the data for displaying a list of people
0
+      # might look something like this:
0
+      #
0
+      #   def list
0
+      #     @people = Person.find(:all)
0
+      #   end
0
+      # 
0
+      # Here's the same action, with web-service support baked in:
0
+      # 
0
+      #   def list
0
+      #     @people = Person.find(:all)
0
+      # 
0
+      #     respond_to do |wants|
0
+      #       wants.html
0
+      #       wants.xml { render :xml => @people.to_xml }
0
+      #     end
0
+      #   end
0
+      # 
0
+      # What that says is, "if the client wants HTML in response to this action, just respond as we 
0
+      # would have before, but if the client wants XML, return them the list of people in XML format." 
0
+      # (Rails determines the desired response format from the HTTP Accept header submitted by the client.)
0
+      # 
0
+      # Supposing you have an action that adds a new person, optionally creating their company 
0
+      # (by name) if it does not already exist, without web-services, it might look like this:
0
+      # 
0
+      #   def add
0
+      #     @company = Company.find_or_create_by_name(params[:company][:name])
0
+      #     @person  = @company.people.create(params[:person])
0
+      # 
0
+      #     redirect_to(person_list_url)
0
+      #   end
0
+      # 
0
+      # Here's the same action, with web-service support baked in:
0
+      # 
0
+      #   def add
0
+      #     company  = params[:person].delete(:company)
0
+      #     @company = Company.find_or_create_by_name(company[:name])
0
+      #     @person  = @company.people.create(params[:person])
0
+      # 
0
+      #     respond_to do |wants|
0
+      #       wants.html { redirect_to(person_list_url) }
0
+      #       wants.js
0
+      #       wants.xml  { render :xml => @person.to_xml(:include => @company) }
0
+      #     end
0
+      #   end
0
+      # 
0
+      # If the client wants HTML, we just redirect them back to the person list. If they want Javascript 
0
+      # (wants.js), then it is an RJS request and we render the RJS template associated with this action. 
0
+      # Lastly, if the client wants XML, we render the created person as XML, but with a twist: we also 
0
+      # include the person’s company in the rendered XML, so you get something like this:
0
+      # 
0
+      #   <person>
0
+      #     <id>...</id>
0
+      #     ...
0
+      #     <company>
0
+      #       <id>...</id>
0
+      #       <name>...</name>
0
+      #       ...
0
+      #     </company>
0
+      #   </person>
0
+      # 
0
+      # Note, however, the extra bit at the top of that action:
0
+      # 
0
+      #   company  = params[:person].delete(:company)
0
+      #   @company = Company.find_or_create_by_name(company[:name])
0
+      # 
0
+      # This is because the incoming XML document (if a web-service request is in process) can only contain a 
0
+      # single root-node. So, we have to rearrange things so that the request looks like this (url-encoded):
0
+      # 
0
+      #   person[name]=...&person[company][name]=...&...
0
+      # 
0
+      # And, like this (xml-encoded):
0
+      # 
0
+      #   <person>
0
+      #     <name>...</name>
0
+      #     <company>
0
+      #       <name>...</name>
0
+      #     </company>
0
+      #   </person>
0
+      # 
0
+      # In other words, we make the request so that it operates on a single entity—a person. Then, in the action, 
0
+      # we extract the company data from the request, find or create the company, and then create the new person 
0
+      # with the remaining data.
0
+      # 
0
+      # Note that you can define your own XML parameter parser which would allow you to describe multiple entities 
0
+      # in a single request (i.e., by wrapping them all in a single root note), but if you just go with the flow 
0
+      # and accept Rails' defaults, life will be much easier.
0
       def respond_to(*types, &block)
0
         raise ArgumentError, "respond_to takes either types or a block, never bot" unless types.any? ^ block
0
         block ||= lambda { |responder| types.each { |type| responder.send(type) } }