Copyright (c) 2008 José Valim (jose.valim at gmail dot com)
Site: http://www.pagestacker.com/
Blog: http://josevalim.blogspot.com/
License: MIT
Version: 2.0

You can also read this README in pretty html at the GitHub project Wiki page

  http://github.com/josevalim/easy_http_cache/wikis/home

Warning
-------

Since version 2.0, this plugin/gem has drastically changed to fit Rails 2.2
http cache goodness. :expires_in, :expires_at and :control options were
removed, so if you want to use previous versions, see "Previous versions"
below.

Description
-----------

Allows Rails applications to do conditional cache easily and in a DRY way
(without messing up your actions):

  class ListsController < ApplicationController
    http_cache :index, :show
  end

It uses :last_modified and :etag keys, that besides Time, String or resources
accepts Proc, Method and Symbols that are evaluated within the current controller.
Read more about each option below:

  :last_modified
    Used to manipulate Last-Modified header. You can pass any object that responds
    to :to_time. If you pass a Proc or Method or Symbols, they will be evaluated
    within the current controller and :to_time will be called.

    You can also pass resources and :updated_at or :updated_on will be called on
    it. If you want to call a different method on your resource, you can pass it as
    a symbol using the :method option.

    All times will be converted to UTC. Finally, if you pass an array, it will get
    the most recent time to be used.

  :etag
    Used to manipulate Etag header. If you pass a Proc or Method or Symbols, they
    will be evaluated within the current controller.

    You can also pass an array and each element will be also evaluated with needed.

  :if
    Only perform http cache if it returns true.

  :unless
    Only perform http cache if it returns false.


Install
-------

Install Easy HTTP Cache is very easy. It is stored in GitHub, so if you
have never installed a gem via GitHub run the following:

  gem sources -a http://gems.github.com

Then install the gem:

  sudo gem install josevalim-easy_http_cache

In RAILS_ROOT/config/environment.rb:

  config.gem "josevalim-easy_http_cache",  :lib => "easy_http_cache", :source => "http://gems.github.com"

If you want it as plugin, just do:

    cd myapp
    git clone git://github.com/josevalim/easy_http_cache.git
    rm -rf vendor/plugins/easy_http_cache/.git


Previous versions
-----------------

If you are running on Rails 2.1.x, you should use v1.2.3:

    cd myapp
    git clone git://github.com/josevalim/easy_http_cache.git
    cd vendor/plugins/easy_http_cache
    git checkout v1.2.3
    rm -rf ./.git

If you are using a previous version, please updagrade your app. =)


Variables
---------

You can set ENV['RAILS_CACHE_ID'] or ENV['RAILS_APP_VERSION'] to change
the ETag that will be generated, expiring all previous caches. Those variables
are also used by other cache stores (memcached, file, ...).


Examples
--------

Just as above:

  class ListsController < ApplicationController
    http_cache :index, :show
  end

If you do not want to cache when you are showing a flash message (and you
usually want that), you can simply do:

  class ListsController < ApplicationController
    http_cache :index, :show, :if => Proc.new { |c| c.__send__(:flash).empty? }
  end

And if you do not want JSON requests:

  class ListsController < ApplicationController
    http_cache :index, :show, :unless => Proc.new { |c| c.request.format.json? }
  end

Or if you want to expire all http cache before 2008, just do:

  class ListsController < ApplicationController
    http_cache :index, :show, :last_modified => Time.utc(2008)
  end

If You want to cache a list and automatically expire the cache when
it changes, just do:

  class ListsController < ApplicationController
    http_cache :index, :show, :last_modified => :list

    protected
      def list
        @list ||= List.find(params[:id])
      end
  end

You can also set :etag header:

  class ListsController < ApplicationController
    http_cache :index, :show, :etag => :list

    protected
      def list
        @list ||= List.find(params[:id])
      end
  end

If you are using a resource that doesn't respond to updated_at or updated_on,
you can pass a method as parameter and it will be called in your resources:

  class ListsController < ApplicationController
    http_cache :index, :show, :last_modified => :list, :method => :cached_at

    protected
    def list
      @list ||= List.find(params[:id])
    end
  end

Finally, you can also pass an array at :last_modified as below:

  class ListsController < ApplicationController
    http_cache :index, :show,
               :last_modified => [ :list, Time.utc(2007,12,27) ]
  end

This will check which one is the most recent to compare with the
"Last-Modified" field sent by the client.