ruby script/plugin install svn://rubyforge.org/var/svn/cache-filter

Usage
===========

The plugin adds the cache_filter method to your controllers. The cache_filter method takes one or more action names and an optional block as parameters. The cache_filter method requires that there be a method called 'judge_cache' in either your ApplicationController or the current controller.

An example follows:

	class WelcomeController < ApplicationController
	  
	  cache_filter :index, :faq
	  
    def index
	  end
	  
	  def faq
	    @faqs = Faq.find_for_main_faq
	  end
  
  private
    def judge_cache(cache)
      if session[:member_id]
        cache.as :logged_in
      else
        cache.as :not_logged_in
      end
    end

	end

Internally, the cache_filter method is an around_filter which gets prepended to the list of filters.

Inside the judge_cache method you have full access to your custom ApplicationController methods!
(Thanks Chris [http://errtheblog.com])

In the example, we check for a value in the current controller's session, which can be read and changed along with the flash and other controller methods as mentioned above.

I mentioned that cache_filter takes an optional block as parameter. If this is the case, you don't need a judge_cache method in that controller (it will be ignored by the cache_filter method). The block exposes a object through which the controller's methods can be accessed.

For example:

#######in application.rb
include CacheFilter

  def method_residing_in_application_dot_rb
    false
  end
#######

#######in for example welcome_controller.rb
cache_filter :action_one, :action_two do |cache|
  if cache.method_residing_in_application_dot_rb
    cache.as :foo
  elsif cache.method_in_current_controller
    cache.as :bar
  end
  #note that if both are false, it won't cache the request at all!
end

private
  def method_in_current_controller
    false
  end
#######

To expire a CacheFilter fragment, use the expire_cache_filter() action, passing in the normal url_for options, in addition to the :version of the cached action you want to expire.

eg.

class MyController < ApplicationController
  cache_filter :my_action {|cache|
    cache.as :one
  }

  def expiring_action
    expire_cache_filter(:controller => "my_controller", :action => "my_action", :version => "one")
  end
end

Here's some further examples:

  class ApplicationController < ActionController::Base
    include CacheFilter

    def is_admin?
      admin_role = Role.find_by_title("Admin")
      Member.find(cache.session[:member_id]).roles.include?(admin_role)
    end
  end

	class WelcomeController < ApplicationController
		  
	  cache_filter :index, :faq do | cache |
	  
	    if cache.is_admin?
	      cache.as :its_me_admin
	    elsif cache.session[:member_id]
	      cache.as :logged_in
	    else
	    	cache.as :not_logged_in
	    end
    end

    
    def index; end

    def faq; end

	end

The usage of the judge_cache method is preferred as you don't need to call controller methods using the 'cache' object as a proxy (which can lead to violations between internal methods belonging to the cache object and your own methods), and can simply use them as is to be expected. If however your judging method is very simple, judging in the cache_filter block is fine!

  class ApplicationController < ActionController::Base
    include CacheFilter

    def is_admin?
      admin_role = Role.find_by_title("Admin")
      Member.find(cache.session[:member_id]).roles.include?(admin_role)
    end

    def logged_in?
      session[:member_id]
    end
  end

  class WelcomeController < ApplicationController
      
    cache_filter :index, :faq
    
    def index; end
    
    def faq; end


  private
    def judge_cache(cache)
      if is_admin?
        cache.as admin_cache_name
      elsif logged_in?
        cache.as :logged_in
      else
        cache.as :not_logged_in
      end
    end
    
    def admin_cache_name
      "its_me_admin"
    end
  end

Obviously, CacheFilter mimicks the behaviour of action_cache (I made copious use of the caching module in edge). However, if you want an action to be action_cached even if no cache.as method call is reached in the cache_filter block or judge_cache method, you'll need to action_cache it seperately!

There is currently no advanced documentation for this plugin.