4 module ActionController
#:nodoc:
6 # Page caching is an approach to caching where the entire action output of is stored as a HTML file that the web server
7 # can serve without going through Action Pack. This is the fastest way to cache your content as opposed to going dynamically
8 # through the process of generating the content. Unfortunately, this incredible speed-up is only available to stateless pages
9 # where all visitors are treated the same. Content management systems -- including weblogs and wikis -- have many pages that are
10 # a great fit for this approach, but account-based systems where people log in and manipulate their own data are often less
13 # Specifying which actions to cache is done through the <tt>caches_page</tt> class method:
15 # class WeblogController < ActionController::Base
16 # caches_page :show, :new
19 # This will generate cache files such as <tt>weblog/show/5.html</tt> and <tt>weblog/new.html</tt>,
20 # which match the URLs used to trigger the dynamic generation. This is how the web server is able
21 # pick up a cache file when it exists and otherwise let the request pass on to Action Pack to generate it.
23 # Expiration of the cache is handled by deleting the cached file, which results in a lazy regeneration approach where the cache
24 # is not restored before another hit is made against it. The API for doing so mimics the options from +url_for+ and friends:
26 # class WeblogController < ActionController::Base
28 # List.update(params[:list][:id], params[:list])
29 # expire_page :action => "show", :id => params[:list][:id]
30 # redirect_to :action => "show", :id => params[:list][:id]
34 # Additionally, you can expire caches using Sweepers that act on changes in the model to determine when a cache is supposed to be
37 # == Setting the cache directory
39 # The cache directory should be the document root for the web server and is set using <tt>Base.page_cache_directory = "/document/root"</tt>.
40 # For Rails, this directory has already been set to Rails.public_path (which is usually set to <tt>RAILS_ROOT + "/public"</tt>). Changing
41 # this setting can be useful to avoid naming conflicts with files in <tt>public/</tt>, but doing so will likely require configuring your
42 # web server to look in the new location for cached files.
44 # == Setting the cache extension
46 # Most Rails requests do not have an extension, such as <tt>/weblog/new</tt>. In these cases, the page caching mechanism will add one in
47 # order to make it easy for the cached files to be picked up properly by the web server. By default, this cache extension is <tt>.html</tt>.
48 # If you want something else, like <tt>.php</tt> or <tt>.shtml</tt>, just set Base.page_cache_extension. In cases where a request already has an
49 # extension, such as <tt>.xml</tt> or <tt>.rss</tt>, page caching will not add an extension. This allows it to work well with RESTful apps.
51 def self.included(base
) #:nodoc:
52 base
.extend(ClassMethods
)
54 @
@page_cache_directory = defined?(Rails
.public_path
) ? Rails
.public_path
: ""
55 cattr_accessor
:page_cache_directory
57 @
@page_cache_extension = '.html'
58 cattr_accessor
:page_cache_extension
63 # Expires the page that was cached with the +path+ as a key. Example:
64 # expire_page "/lists/show"
66 return unless perform_caching
68 benchmark
"Expired page: #{page_cache_file(path)}" do
69 File
.delete(page_cache_path(path
)) if File
.exist
?(page_cache_path(path
))
73 # Manually cache the +content+ in the key determined by +path+. Example:
74 # cache_page "I'm the cached content", "/lists/show"
75 def cache_page(content
, path
)
76 return unless perform_caching
78 benchmark
"Cached page: #{page_cache_file(path)}" do
79 FileUtils
.makedirs(File
.dirname(page_cache_path(path
)))
80 File
.open(page_cache_path(path
), "wb+") { |f
| f
.write(content
) }
84 # Caches the +actions+ using the page-caching approach that'll store the cache in a path within the page_cache_directory that
85 # matches the triggering url.
89 # # cache the index action
92 # # cache the index action except for JSON requests
93 # caches_page :index, :if => Proc.new { |c| !c.request.format.json? }
94 def caches_page(*actions
)
95 return unless perform_caching
96 options
= actions
.extract_options
!
97 after_filter({:only => actions
}.merge(options
)) { |c
| c
.cache_page
}
101 def page_cache_file(path
)
102 name
= (path
.empty
? || path
== "/") ? "/index" : URI
.unescape(path
.chomp('/'))
103 name
<< page_cache_extension
unless (name
.split('/').last
|| name
).include? '.'
107 def page_cache_path(path
)
108 page_cache_directory
+ page_cache_file(path
)
112 # Expires the page that was cached with the +options+ as a key. Example:
113 # expire_page :controller => "lists", :action => "show"
114 def expire_page(options
= {})
115 return unless perform_caching
117 if options
.is_a
?(Hash
)
118 if options
[:action].is_a
?(Array
)
119 options
[:action].dup
.each
do |action
|
120 self.class.expire_page(url_for(options
.merge(:only_path => true, :skip_relative_url_root => true, :action => action
)))
123 self.class.expire_page(url_for(options
.merge(:only_path => true, :skip_relative_url_root => true)))
126 self.class.expire_page(options
)
130 # Manually cache the +content+ in the key determined by +options+. If no content is provided, the contents of response.body is used
131 # If no options are provided, the requested url is used. Example:
132 # cache_page "I'm the cached content", :controller => "lists", :action => "show"
133 def cache_page(content
= nil, options
= nil)
134 return unless perform_caching
&& caching_allowed
138 url_for(options
.merge(:only_path => true, :skip_relative_url_root => true, :format => params
[:format]))
145 self.class.cache_page(content
|| response
.body
, path
)
150 request
.get
? && response
.headers
['Status'].to_i
== 200