Merge branch 'master' of github.com:lifo/docrails

9 files changed, 122 insertions, 23 deletions

diff --git a/README.rdoc b/README.rdoc
index 78640b39aa..c9fb595efb 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -47,7 +47,7 @@ can read more about Action Pack in its {README}[link:/rails/rails/blob/master/ac
 
     cd myapp; rails server
 
-   Run with <tt>--help</tt> for options.
+   Run with <tt>--help</tt> or <tt>-h</tt> for options.
 
 4. Go to http://localhost:3000 and you'll see:
 
diff --git a/actionpack/lib/action_controller/metal/mime_responds.rb b/actionpack/lib/action_controller/metal/mime_responds.rb
index 73e044a092..fbb5d01e86 100644
--- a/actionpack/lib/action_controller/metal/mime_responds.rb
+++ b/actionpack/lib/action_controller/metal/mime_responds.rb
@@ -195,20 +195,106 @@ module ActionController #:nodoc:
       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.
+    # For a given controller action, respond_with generates an appropriate
+    # response based on the mime-type requested by the client.
     #
-    # ==== Example
+    # If the method is called with just a resource, as in this example -
     #
-    #   def index
-    #     @users = User.all
-    #     respond_with(@users)
+    #   class PeopleController < ApplicationController
+    #     respond_to :html, :xml, :json
+    #
+    #     def index
+    #       @people = Person.all
+    #       respond_with @people
+    #     end
     #   end
     #
-    # It also accepts a block to be given. It's used to overwrite a default
-    # response:
+    # then the mime-type of the response is typically selected based on the
+    # request's Accept header and the set of available formats declared
+    # by previous calls to the controller's class method +respond_to+. Alternatively
+    # the mime-type can be selected by explicitly setting <tt>request.format</tt> in
+    # the controller.
+    #
+    # If an acceptable format is not identified, the application returns a
+    # '406 - not acceptable' status. Otherwise, the default response is to render
+    # a template named after the current action and the selected format,
+    # e.g. <tt>index.html.erb</tt>. If no template is available, the behavior
+    # depends on the selected format:
+    #
+    # * for an html response - if the request method is +get+, an exception
+    #   is raised but for other requests such as +post+ the response
+    #   depends on whether the resource has any validation errors (i.e.
+    #   assuming that an attempt has been made to save the resource,
+    #   e.g. by a +create+ action) -
+    #   1. If there are no errors, i.e. the resource
+    #      was saved successfully, the response +redirect+'s to the resource
+    #      i.e. its +show+ action.
+    #   2. If there are validation errors, the response
+    #      renders a default action, which is <tt>:new</tt> for a
+    #      +post+ request or <tt>:edit</tt> for +put+.
+    #   Thus an example like this -
+    #
+    #     respond_to :html, :xml
+    #
+    #     def create
+    #       @user = User.new(params[:user])
+    #       flash[:notice] = 'User was successfully created.' if @user.save
+    #       respond_with(@user)
+    #     end
+    #
+    #   is equivalent, in the absence of <tt>create.html.erb</tt>, to -
+    #
+    #     def create
+    #       @user = User.new(params[:user])
+    #       respond_to do |format|
+    #         if @user.save
+    #           flash[:notice] = 'User was successfully created.'
+    #           format.html { redirect_to(@user) }
+    #           format.xml { render :xml => @user }
+    #         else
+    #           format.html { render :action => "new" }
+    #           format.xml { render :xml => @user }
+    #         end
+    #       end
+    #     end
+    #
+    # * for a javascript request - if the template isn't found, an exception is
+    #   raised.
+    # * for other requests - i.e. data formats such as xml, json, csv etc, if
+    #   the resource passed to +respond_with+ responds to <code>to_<format></code>,
+    #   the method attempts to render the resource in the requested format
+    #   directly, e.g. for an xml request, the response is equivalent to calling 
+    #   <code>render :xml => resource</code>.
+    #
+    # === Nested resources
+    #
+    # As outlined above, the +resources+ argument passed to +respond_with+
+    # can play two roles. It can be used to generate the redirect url
+    # for successful html requests (e.g. for +create+ actions when
+    # no template exists), while for formats other than html and javascript
+    # it is the object that gets rendered, by being converted directly to the
+    # required format (again assuming no template exists).
+    #
+    # For redirecting successful html requests, +respond_with+ also supports
+    # the use of nested resources, which are supplied in the same way as
+    # in <code>form_for</code> and <code>polymorphic_url</code>. For example -
+    #
+    #   def create
+    #     @project = Project.find(params[:project_id])
+    #     @task = @project.comments.build(params[:task])
+    #     flash[:notice] = 'Task was successfully created.' if @task.save
+    #     respond_with(@project, @task)
+    #   end
+    #
+    # This would cause +respond_with+ to redirect to <code>project_task_url</code>
+    # instead of <code>task_url</code>. For request formats other than html or
+    # javascript, if multiple resources are passed in this way, it is the last
+    # one specified that is rendered.
+    #
+    # === Customizing response behavior
+    #
+    # Like +respond_to+, +respond_with+ may also be called with a block that
+    # can be used to overwrite any of the default responses, e.g. -
     #
     #   def create
     #     @user = User.new(params[:user])
@@ -219,13 +305,24 @@ module ActionController #:nodoc:
     #     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 <tt>respond_to</tt>.
+    # The argument passed to the block is an ActionController::MimeResponds::Collector
+    # object which stores the responses for the formats defined within the
+    # block. Note that formats with responses defined explicitly in this way
+    # do not have to first be declared using the class method +respond_to+.
+    #
+    # Also, a hash passed to +respond_with+ immediately after the specified
+    # resource(s) is interpreted as a set of options relevant to all
+    # formats. Any option accepted by +render+ can be used, e.g.
+    #   respond_with @people, :status => 200
+    # However, note that these options are ignored after an unsuccessful attempt
+    # to save a resource, e.g. when automatically rendering <tt>:new</tt>
+    # after a post request.
+    #
+    # Two additional options are relevant specifically to +respond_with+ -
+    # 1. <tt>:location</tt> - overwrites the default redirect location used after
+    #    a successful html +post+ request.
+    # 2. <tt>:action</tt> - overwrites the default render action used after an
+    #    unsuccessful html +post+ request.
     #
     def respond_with(*resources, &block)
       raise "In order to use respond_with, first you need to declare the formats your " <<
@@ -283,8 +380,8 @@ module ActionController #:nodoc:
       end
     end
 
-    # A container of responses available for requests with different mime-types
-    # sent to the current controller action.
+    # A container for responses available from the current controller for
+    # requests for different mime-types sent to a particular action.
     #
     # The public controller methods +respond_with+ and +respond_to+ may be called
     # with a block that is used to define responses to different mime-types, e.g.
diff --git a/guides/assets/images/getting_started/new_post.png b/guides/assets/images/getting_started/new_post.png
new file mode 100644
index 0000000000..dc9459032a
--- /dev/null
+++ b/guides/assets/images/getting_started/new_post.png
diff --git a/guides/assets/images/getting_started/routing_error_no_controller.png b/guides/assets/images/getting_started/routing_error_no_controller.png
new file mode 100644
index 0000000000..92a39efd78
--- /dev/null
+++ b/guides/assets/images/getting_started/routing_error_no_controller.png
diff --git a/guides/assets/images/getting_started/routing_error_no_route_matches.png b/guides/assets/images/getting_started/routing_error_no_route_matches.png
new file mode 100644
index 0000000000..bc768a94a2
--- /dev/null
+++ b/guides/assets/images/getting_started/routing_error_no_route_matches.png
diff --git a/guides/assets/images/getting_started/template_is_missing_posts_new.png b/guides/assets/images/getting_started/template_is_missing_posts_new.png
new file mode 100644
index 0000000000..9f070d59db
--- /dev/null
+++ b/guides/assets/images/getting_started/template_is_missing_posts_new.png
diff --git a/guides/assets/images/getting_started/unknown_action_create_for_posts.png b/guides/assets/images/getting_started/unknown_action_create_for_posts.png
new file mode 100644
index 0000000000..03d92dfb7d
--- /dev/null
+++ b/guides/assets/images/getting_started/unknown_action_create_for_posts.png
diff --git a/guides/assets/images/getting_started/unknown_action_new_for_posts.png b/guides/assets/images/getting_started/unknown_action_new_for_posts.png
new file mode 100644
index 0000000000..b63883d922
--- /dev/null
+++ b/guides/assets/images/getting_started/unknown_action_new_for_posts.png
diff --git a/guides/source/getting_started.textile b/guides/source/getting_started.textile
index 8196a67d35..fdae21caf2 100644
--- a/guides/source/getting_started.textile
+++ b/guides/source/getting_started.textile
@@ -371,17 +371,19 @@ When a form is submitted, the fields of the form are sent to Rails as _parameter
 
 <ruby>
 def create
-  render :text => params.inspect
+  render :text => params[:post].inspect
 end
 </ruby>
 
-The +render+ method here is taking a very simple hash with the key of +text+ and the value of +params.inspect+. The +params+ method here is the object which represents the parameters (or fields) coming in from the form. If you re-submit the form one more time you'll now no longer get the missing template error. Instead, you'll see something that looks like the following:
+The +render+ method here is taking a very simple hash with the key of +text+ and the value of +params[:post].inspect+. The +params+ method here is the object which represents the parameters (or fields) coming in from the form. The +params+ method returns a +HashWithIndifferentAccess+ object, which allows you to access the keys of the hash using either strings or symbols. In this situation, the only parameters that matter are the ones from the form.
+
+If you re-submit the form one more time you'll now no longer get the missing template error. Instead, you'll see something that looks like the following:
 
 <ruby>
 {"title"=>"First post!", "text"=>"This is my first post."}
 </ruby>
 
-
+This action is now displaying the parameters for the post that are coming in from the form. However, this isn't really all that helpful. Yes, you can see the parameters but nothing in particular is being done with them.
 
 h4. Running a Migration