= response_for

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

== Current Version 0.2-stable

As of version 0.2.0, response_for's functionality can be summed up in one sentence:

<b>"response_for allows you to specify default responses for any action (or before filter) that doesn't render or redirect"</b>

Actions typically do two things - interact with models, and render a response.  The above simple idea allows you to decouple these
two functions (where appropriate), which means abstraction of common patterns becomes possible.

NOTE: 0.2-stable has BC-breaking API changes, and is supported only for Rails >= 2.1.x.  Version 0.2.0 was released on Sept 14th 2008.
You should use 0.1-stable in your existing projects until you have runs your specs and whatnot.

If you want to know more about why I changed the API in 0.2 look at the bottom of this README

== Tested for Rails 2.1 and edge

response_for works with 2.1.x and edge.  For previous rails versions checkout the 0.1-stable-rails2.0 branch

=== Example

  class FooController < ApplicationController
    def index
      @foos = Foo.find(:all)
      # default response - render html
    end
  end
  
  # this controller needs to respond_to fbml on index. 
  # Using response_for, we don't need to repeat '@foos = Foo.find(1)'
  class SpecialFooController < FooController
    response_for :index do |format|
      format.fbml { render :inline => turn_into_facebook(@foos) }
    end
  end

=== Specs and Coverage

* The SPECDOC lists the specifications
* Coverage is 100% (C0), and the spec suite is quite comprehensive

RSpec is used for testing, so the tests are in <tt>spec/</tt> rather than
<tt>test/</tt> Do rake --tasks for more details.

=== Continuous Integration

garlic (at http://github.com/ianwhite/garlic) is used for CI.  To run the CI suite have a look at
garlic_example.rb

=== Why change the API in 0.2?

repsonse_for <= v0.1 intercepted respond_to calls to allow overriding of these by class level declarations.  This turns out to have some 
headaches, such as:

* If you have some bail-out code in before_filters which uses respond_to, then response_for tries to overwrite this.  This meant that I had
  to write response_for to only kick in once before_filters had run.  This made for some funky smelling code.
* Sometimes your bail out code runs after the before_filters, in a superclass action for example, or just as part of your action (perhaps in
  another method).  The above hack doesn't work for this case (the before_filters have run).  The solution in this case was to use
  respond_to_without_response_for in any bail out code.
* Conceptually, overriding code declared in methods, with code declared at the class level, is weird.  Here's an example

    class FooController < SuperclassController
      response_for :index # override Superclass's index respond_to
    
      def index
        respond_to  # one might expect this to override the above, as its declared later - but it wont!
      end
    end

So, in 0.2 a much simpler idea is behind response_for - you can declare a default response for an action which will be performed
if <b>that that action has not already performed a render or redirect</b>.  This means that all of your bail out code written with
respond_to will do what it's supposed to.

==== Rewriting for 0.2

If you're upgrading, you just need to convert any actions you want to override from this:

  def index
    @things = Thing.all
    respond_to do |format|
      format.html
      format.xml { render :xml => @things }
    end
  end
  
to this:

  def index
    @things = Thing.all
  end
  
  response_for :index fo |format|
    format.html
    format.xml { render :xml => @things }
  end

== Previous Versions: 0.1

There is a branch for rails 2.0 users on this release.  If you are using rails 2.0, then you want the 0.1-stable-rails2.0 branch.  If you are
using rails >= 2.1 then use the 0.1-stable branch