Module ActionController::Caching::Pages
In: vendor/rails/actionpack/lib/action_controller/caching.rb

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 the Action Pack. This can be as much as 100 times faster than going through the process of dynamically 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 class method:

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

This will generate cache files such as weblog/show/5 and weblog/new, 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 the 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_for and 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.

Setting the cache directory

The cache directory should be the document root for the web server and is set using Base.page_cache_directory = "/document/root". For Rails, this directory has already been set to RAILS_ROOT + "/public".

Setting the cache extension

By default, the cache extension is .html, which makes it easy for the cached files to be picked up by the web server. If you want something else, like .php or .shtml, just set Base.page_cache_extension.

Methods

Classes and Modules

Module ActionController::Caching::Pages::ClassMethods

Public Instance methods

Manually cache the content in 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"

[Source]

     # File vendor/rails/actionpack/lib/action_controller/caching.rb, line 140
140:       def cache_page(content = nil, options = nil)
141:         return unless perform_caching && caching_allowed
142: 
143:         path = case options
144:           when Hash
145:             url_for(options.merge(:only_path => true, :skip_relative_url_root => true, :format => params[:format]))
146:           when String
147:             options
148:           else
149:             request.path
150:         end
151: 
152:         self.class.cache_page(content || response.body, path)
153:       end

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

  expire_page :controller => "lists", :action => "show"

[Source]

     # File vendor/rails/actionpack/lib/action_controller/caching.rb, line 121
121:       def expire_page(options = {})
122:         return unless perform_caching
123: 
124:         if options.is_a?(Hash)
125:           if options[:action].is_a?(Array)
126:             options[:action].dup.each do |action|
127:               self.class.expire_page(url_for(options.merge(:only_path => true, :skip_relative_url_root => true, :action => action)))
128:             end
129:           else
130:             self.class.expire_page(url_for(options.merge(:only_path => true, :skip_relative_url_root => true)))
131:           end
132:         else
133:           self.class.expire_page(options)
134:         end
135:       end

[Validate]