0
@@ -2,11 +2,15 @@
0
 
0
 response_for (see Ardes::ResponseFor::ClassMethods) allows you to decorate the respond_to block of actions on sublcassed controllers.  This works nicely with http://plugins.ardes.com/doc/resources_controller
0
 
0
-== Version 0.2
0
+== Current Version 0.2-stable
0
 
0
-Version 0.2 of response_for has BC-breaking API changes, has vastly simplified internals, and is supported only for Rails >= 2.1.x.
0
+Version 0.2-stable of response_for has BC-breaking API changes, has vastly simplified internals, and is supported only for Rails >= 2.1.x.
0
 
0
-Version 0.2 was released on Sept 14th 2008.
0
+Version 0.2.0 was released on Sept 14th 2008.
0
+
0
+As of version 0.2.0, response_for's functionality can be summed up in one sentence:
0
+
0
+"response_for allows you to specify default responses for any action (or before filter) that doesn't render or redirect"
0
 
0
 == Version 0.1
0
 
0
@@ -36,7 +40,6 @@ using rails >= 2.1 then use the 0.1-stable branch
0
     
0
     response_for :index, :show, :types => [:html, :xml, :js]
0
   end
0
-  
0
 
0
 === Specs and Coverage
0
 

0
@@ -17,7 +17,6 @@ module Ardes #:nodoc:
0
       # == Usage
0
       #
0
       #   response_for :action1 [, :action2], [,:types => [:mime, :type, :list]] [ do |format| ... end] # or
0
-      #   response_for :action1 [, :action2], [,:type => :mime_type] [ do |format| ... end]
0
       #
0
       # === Example
0
       #
0
@@ -41,29 +40,13 @@ module Ardes #:nodoc:
0
       #     response_for :index, :show, :types => [:html, :xml, :js]
0
       #   end
0
       #
0
-      # === respond_to takes precedence
0
+      # === when response_for kicks in
0
       # 
0
-      # If you write your action with a respond_to block, response_for will never be invoked for that action.
0
-      # If you want to write a controller so that its subclasses can use response_for then do this:
0
-      #
0
-      #   # before
0
-      #   def show
0
-      #     @thing = Thing.find(params[:id])
0
-      #     respond_to do |format|
0
-      #       format.html { }
0
-      #       format.xml  { render :xml => @thing }
0
-      #     end
0
-      #   end
0
+      # response_for only kicks in if the action (or any filters) have not already redirected or rendered.
0
       # 
0
-      #   # after
0
-      #   def show
0
-      #     @thing = Thing.find(params[:id])
0
-      #   end
0
-      #
0
-      #   response_for :show do |format|
0
-      #     format.html { }
0
-      #     format.xml  { render :xml => @thing }
0
-      #   end
0
+      # This means that if you foresee wanting to override your action's responses, you should write them without
0
+      # a respond_to block, but with a response_for block (the latter can be overridden by subsequent response_fors, the 
0
+      # former cannot)
0
       # 
0
       # === Other examples 
0
       #
0
@@ -101,14 +84,14 @@ module Ardes #:nodoc:
0
           action_responses[action].unshift types_block if types_block
0
           action_responses[action].unshift block if block
0
           
0
-          # if there's no action yet defined, create a stub - this is so that you
0
-          # can provide responses for actions which are simply templates, or simply define responses
0
+          # if there's no action yet defined, create an empty one - this is so that you
0
+          # we may provide responses for templates
0
           class_eval "def #{action}; end" unless instance_methods.include?(action)
0
         end
0
       end
0
     
0
-      # remove any response for the specified actions.  If no arguments are given, the
0
-      # entire all repsonses for all actions are removed
0
+      # remove any response for the specified actions.  If no arguments are given,
0
+      # then all repsonses for all actions are removed
0
       def remove_response_for(*actions)
0
         if actions.empty?
0
           instance_variable_set('@action_responses', nil)
0
@@ -129,6 +112,7 @@ module Ardes #:nodoc:
0
     end
0
     
0
   protected
0
+    # if there are responses for the current action, then respond_to them
0
     def respond_to_action_responses
0
       if (responses = self.class.action_responses[action_name]) && responses.any?
0
         respond_to do |responder|
0
@@ -139,6 +123,8 @@ module Ardes #:nodoc:
0
       end
0
     end
0
     
0
+    # this method is invoked if we've got to the end of an action without
0
+    # performing, which is when we respond_to any repsonses defined 
0
     def default_render_with_response_for
0
       respond_to_action_responses
0
       default_render_without_response_for unless performed?