# module ActionController::Caching::Pages

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_page` class method:

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

This will generate cache files such as `weblog/show/5.html` and `weblog/new.html`, which match the URLs used that would normally trigger dynamic page generation. Page caching works by configuring a web server to first check for the existence of files on disk, and to serve them directly when found, without passing the request through to Action Pack. This is much faster than handling the full dynamic request in the usual way.

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.

### Public Instance Methods

cache_page(content = nil, options = nil, gzip = Zlib::BEST_COMPRESSION) click to toggle source

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 url of the current request being handled is used. Example:

    cache_page "I'm the cached content", :controller => "lists", :action => "show"

    # File lib/action_controller/caching/pages.rb, line 166
    def cache_page(content = nil, options = nil, gzip = Zlib::BEST_COMPRESSION)
      return unless self.class.perform_caching && caching_allowed?

      path = case options
        when Hash
          url_for(options.merge(:only_path => true, :format => params[:format]))
        when String
          options
        else
          request.path
      end

      if (type = Mime::LOOKUP[self.content_type]) && (type_symbol = type.symbol).present?
        extension = ".#{type_symbol}"
      end

      self.class.cache_page(content || response.body, path, extension, gzip)
    end

expire_page(options = {}) click to toggle source

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

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

    # File lib/action_controller/caching/pages.rb, line 147
    def expire_page(options = {})
      return unless self.class.perform_caching

      if options.is_a?(Hash)
        if options[:action].is_a?(Array)
          options[:action].each do |action|
            self.class.expire_page(url_for(options.merge(:only_path => true, :action => action)))
          end
        else
          self.class.expire_page(url_for(options.merge(:only_path => true)))
        end
      else
        self.class.expire_page(options)
      end
    end