Page caching is an approach to caching where the entire action output of is stored as a HTML file that the web server can serve without going through Action Pack. This is the fastest way to cache your content as opposed to going dynamically through the process of generating the content. Unfortunately, this incredible speed-up is only available to stateless pages where all visitors are treated the same. Content management systems – including weblogs and wikis – have many pages that are a great fit for this approach, but account-based systems where people log in and manipulate their own data are often less likely candidates.

Specifying which actions to cache is done through the caches_pageclass method:

class WeblogController < ActionController::Base
  caches_page :show, :new
end

This will generate cache files such as weblog/show/5.htmland weblog/new.html, which match the URLs used to trigger the dynamic generation. This is how the web server is able pick up a cache file when it exists and otherwise let the request pass on to Action Pack to generate it.

Expiration of the cache is handled by deleting the cached file, which results in a lazy regeneration approach where the cache is not restored before another hit is made against it. The API for doing so mimics the options from url_forand friends:

class WeblogController < ActionController::Base
  def update
    List.update(params[:list][:id], params[:list])
    expire_page :action => "show", :id => params[:list][:id]
    redirect_to :action => "show", :id => params[:list][:id]
  end
end

Additionally, you can expire caches using Sweepers that act on changes in the model to determine when a cache is supposed to be expired.

Namespace
Methods
C
E
Instance Public methods
cache_page(content = nil, options = nil)

Manually cache the contentin the key determined by options. If no content is provided, the contents of response.body is used If no options are provided, the requested url is used. Example:

cache_page "I'm the cached content", :controller => "lists", :action => "show"
# File actionpack/lib/action_controller/caching/pages.rb, line 131
def cache_page(content = nil, options = nil)
  return unless perform_caching && caching_allowed
  path = case options
    when Hash
      url_for(options.merge(:only_path => true, :skip_relative_url_root => true, :format => params[:format]))
    when String
      options
    else
      request.path
  end
  self.class.cache_page(content || response.body, path)
end
expire_page(options = {})

Expires the page that was cached with the optionsas a key. Example:

expire_page :controller => "lists", :action => "show"
# File actionpack/lib/action_controller/caching/pages.rb, line 112
def expire_page(options = {})
  return unless perform_caching
  if options.is_a?(Hash)
    if options[:action].is_a?(Array)
      options[:action].dup.each do |action|
        self.class.expire_page(url_for(options.merge(:only_path => true, :skip_relative_url_root => true, :action => action)))
      end
    else
      self.class.expire_page(url_for(options.merge(:only_path => true, :skip_relative_url_root => true)))
    end
  else
    self.class.expire_page(options)
  end
end