From 191ddf26379670b477bd63bccf8debbe16d20ed9 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Sat, 22 Sep 2012 19:42:40 -0500 Subject: update AC::Caching documentation [ci skip] --- actionpack/lib/action_controller/caching/pages.rb | 91 +++++++++++++---------- 1 file changed, 52 insertions(+), 39 deletions(-) (limited to 'actionpack/lib/action_controller/caching/pages.rb') diff --git a/actionpack/lib/action_controller/caching/pages.rb b/actionpack/lib/action_controller/caching/pages.rb index 73b8cd383c..3cf8d965ff 100644 --- a/actionpack/lib/action_controller/caching/pages.rb +++ b/actionpack/lib/action_controller/caching/pages.rb @@ -1,60 +1,72 @@ require 'fileutils' require 'active_support/core_ext/class/attribute_accessors' -module ActionController #:nodoc: +module ActionController module Caching - # 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. + # 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: + # 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. + # 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: + # 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] + # 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. + # Additionally, you can expire caches using Sweepers that act on changes in + # the model to determine when a cache is supposed to be expired. module Pages extend ActiveSupport::Concern included do - # 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.public_path (which is usually set to Rails.root + "/public"). Changing - # this setting can be useful to avoid naming conflicts with files in public/, but doing so will likely require configuring your - # web server to look in the new location for cached files. + # 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.public_path (which is usually + # set to Rails.root + "/public"). Changing this setting can be useful + # to avoid naming conflicts with files in public/, but doing so will + # likely require configuring your web server to look in the new location for + # cached files. class_attribute :page_cache_directory self.page_cache_directory ||= '' - # Most Rails requests do not have an extension, such as /weblog/new. In these cases, the page caching mechanism will add one in - # order to make it easy for the cached files to be picked up properly by the web server. By default, this cache extension is .html. - # If you want something else, like .php or .shtml, just set Base.page_cache_extension. In cases where a request already has an - # extension, such as .xml or .rss, page caching will not add an extension. This allows it to work well with RESTful apps. + # Most Rails requests do not have an extension, such as /weblog/new. + # In these cases, the page caching mechanism will add one in order to make it + # easy for the cached files to be picked up properly by the web server. By + # default, this cache extension is .html. If you want something else, + # like .php or .shtml, just set Base.page_cache_extension. + # In cases where a request already has an extension, such as .xml + # or .rss, page caching will not add an extension. This allows it + # to work well with RESTful apps. class_attribute :page_cache_extension self.page_cache_extension ||= '.html' - # The compression used for gzip. If false (default), the page is not compressed. - # If can be a symbol showing the ZLib compression method, for example, :best_compression - # or :best_speed or an integer configuring the compression level. + # The compression used for gzip. If +false+ (default), the page is not compressed. + # If can be a symbol showing the ZLib compression method, for example, :best_compression + # or :best_speed or an integer configuring the compression level. class_attribute :page_cache_compression self.page_cache_compression ||= false end @@ -62,7 +74,7 @@ module ActionController #:nodoc: module ClassMethods # Expires the page that was cached with the +path+ as a key. # - # expire_page "/lists/show" + # expire_page '/lists/show' def expire_page(path) return unless perform_caching path = page_cache_path(path) @@ -75,7 +87,7 @@ module ActionController #:nodoc: # Manually cache the +content+ in the key determined by +path+. # - # cache_page "I'm the cached content", "/lists/show" + # cache_page "I'm the cached content", '/lists/show' def cache_page(content, path, extension = nil, gzip = Zlib::BEST_COMPRESSION) return unless perform_caching path = page_cache_path(path, extension) @@ -90,19 +102,19 @@ module ActionController #:nodoc: end # Caches the +actions+ using the page-caching approach that'll store - # the cache in a path within the page_cache_directory that + # the cache in a path within the +page_cache_directory+ that # matches the triggering url. # - # You can also pass a :gzip option to override the class configuration one. + # You can also pass a :gzip option to override the class configuration one. # # # cache the index action # caches_page :index # # # cache the index action except for JSON requests - # caches_page :index, :if => Proc.new { !request.format.json? } + # caches_page :index, if: Proc.new { !request.format.json? } # # # don't gzip images - # caches_page :image, :gzip => false + # caches_page :image, gzip: false def caches_page(*actions) return unless perform_caching options = actions.extract_options! @@ -144,7 +156,7 @@ module ActionController #:nodoc: # Expires the page that was cached with the +options+ as a key. # - # expire_page :controller => "lists", :action => "show" + # expire_page controller: 'lists', action: 'show' def expire_page(options = {}) return unless self.class.perform_caching @@ -161,10 +173,11 @@ module ActionController #:nodoc: end end - # 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. + # 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. # - # cache_page "I'm the cached content", :controller => "lists", :action => "show" + # cache_page "I'm the cached content", controller: 'lists', action: 'show' def cache_page(content = nil, options = nil, gzip = Zlib::BEST_COMPRESSION) return unless self.class.perform_caching && caching_allowed? -- cgit v1.2.3