--- !ruby/object:RI::MethodDescription 
aliases: []

block_params: 
comment: 
- !ruby/struct:SM::Flow::P 
  body: "Without web-service support, an action which collects the data for displaying a list of people might look something like this:"
- !ruby/struct:SM::Flow::VERB 
  body: "  def list\n    @people = Person.find(:all)\n  end\n"
- !ruby/struct:SM::Flow::P 
  body: "Here's the same action, with web-service support baked in:"
- !ruby/struct:SM::Flow::VERB 
  body: "  def list\n    @people = Person.find(:all)\n\n    respond_to do |wants|\n      wants.html\n      wants.xml { render :xml =&gt; @people.to_xml }\n    end\n  end\n"
- !ruby/struct:SM::Flow::P 
  body: What that says is, &quot;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.&quot; (Rails determines the desired response format from the HTTP Accept header submitted by the client.)
- !ruby/struct:SM::Flow::P 
  body: "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:"
- !ruby/struct:SM::Flow::VERB 
  body: "  def add\n    @company = Company.find_or_create_by_name(params[:company][:name])\n    @person  = @company.people.create(params[:person])\n\n    redirect_to(person_list_url)\n  end\n"
- !ruby/struct:SM::Flow::P 
  body: "Here's the same action, with web-service support baked in:"
- !ruby/struct:SM::Flow::VERB 
  body: "  def add\n    company  = params[:person].delete(:company)\n    @company = Company.find_or_create_by_name(company[:name])\n    @person  = @company.people.create(params[:person])\n\n    respond_to do |wants|\n      wants.html { redirect_to(person_list_url) }\n      wants.js\n      wants.xml  { render :xml =&gt; @person.to_xml(:include =&gt; @company) }\n    end\n  end\n"
- !ruby/struct:SM::Flow::P 
  body: "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\xE2\x80\x99s company in the rendered XML, so you get something like this:"
- !ruby/struct:SM::Flow::VERB 
  body: "  &lt;person&gt;\n    &lt;id&gt;...&lt;/id&gt;\n    ...\n    &lt;company&gt;\n      &lt;id&gt;...&lt;/id&gt;\n      &lt;name&gt;...&lt;/name&gt;\n      ...\n    &lt;/company&gt;\n  &lt;/person&gt;\n"
- !ruby/struct:SM::Flow::P 
  body: "Note, however, the extra bit at the top of that action:"
- !ruby/struct:SM::Flow::VERB 
  body: "  company  = params[:person].delete(:company)\n  @company = Company.find_or_create_by_name(company[:name])\n"
- !ruby/struct:SM::Flow::P 
  body: "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):"
- !ruby/struct:SM::Flow::VERB 
  body: "  person[name]=...&amp;person[company][name]=...&amp;...\n"
- !ruby/struct:SM::Flow::P 
  body: "And, like this (xml-encoded):"
- !ruby/struct:SM::Flow::VERB 
  body: "  &lt;person&gt;\n    &lt;name&gt;...&lt;/name&gt;\n    &lt;company&gt;\n      &lt;name&gt;...&lt;/name&gt;\n    &lt;/company&gt;\n  &lt;/person&gt;\n"
- !ruby/struct:SM::Flow::P 
  body: "In other words, we make the request so that it operates on a single entity\xE2\x80\x94a 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."
- !ruby/struct:SM::Flow::P 
  body: 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.
- !ruby/struct:SM::Flow::P 
  body: 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.
- !ruby/struct:SM::Flow::VERB 
  body: "  Mime::Type.register &quot;image/jpg&quot;, :jpg\n"
full_name: ActionController::MimeResponds::InstanceMethods#respond_to
is_singleton: false
name: respond_to
params: (*types, &block)
visibility: public
