= itrigga-cache

Adds methods to models and controllers to help caching output.

== Models
With models use like below to cache the output of the block

with_cache(:key => "unique_key") do
  Model.find(:all)
end

To use a different timeout use the below. (Only supported for memcached backend. Filecache uses the value from setup!)

with_cache(:key => "unique_key", :timeout => 42) do
  Model.find(:all)
end

== Controllers
With controllers use like:

with_controller_cache do
  @items = Item.new_on_site(:site_id=>@current_site.id, :page=>params[:page], :per_page=>params[:per_page])
end

This will
- call the block
- render the content
- cache the *rendered* output
- set the :content_type according to the pasted in value (defaults to 'text/html')

== Content-type, respond_to and response status codes
With controller caching, there are a couple of gotchas. 
- If you need to return a non-200 HTTP status code, set it in @status
- The cached value will be the *return value* of the block
- respond_to doesn't return anything - so it can break the nice and simple pattern

So, if you're not using an explicit render statement, you'll need to render_to_string as the last action of your cache block:

def tracker_stats
  with_controller_cache( :key=>default_cache_key ) {
    do_some_stuff_that_takes_a_long_time
    @title = "#{@client.name} Tracker Stats"
    @header = "#{@client.name} Tracker Stats"

    render_to_string # <- this will be the cached value
  }
end 

If you're using respond_to, you need to do it like this:

with_controller_cache(opts) do
	respond_to do |format|
		format.html{
			@content = render_to_string
		}
		format.js {
			@content_type = 'text/javascript'
			@content = render_to_string
		}
	end
	@content
end

To bypass the cache just have the "freshen" => true key in the params (ie as a query string param). This will force fresh the cache


== Installation
In environment.rb: 
config.gem 'itrigga-cache', :lib=>'itrigga/cache'

In application_controller
require 'itrigga/cache'
include Itrigga::Cache
Itrigga::Cache.setup!

Itrigga::Cache.setup! initializes a cache instance. Memcache and filecache are currently supported

Itrigga::Cache.setup! :backend => :memcached
Options are:
:servers - ip:port of the memcache instances to use
:timeout - the default life of the cache item
Any other options get passed to the memcached initializer - see https://github.com/fauna/memcached for more info


Itrigga::Cache.setup! :backend => :filecache
Options are:
:cache_dir - the file path to where the cache files will live
:timeout - how long the cache key is valid for

Itrigga::Cache.setup! can be called as many times as you like, for as many backends as you like.
The cache gem will use the last defined (setup) backend as the default backend.

Use the :backend option to force a backend
with_cache(:key => "unique_key", :backend => :memcached) do
  Model.find(:all)
end


== Contributing to itrigga-cache
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2011 Anson. See LICENSE.txt for
further details.