From bb444e61ee065ee849e0198459308bd9e7d040f7 Mon Sep 17 00:00:00 2001
From: Aditya <aditya@sublucid.com>
Date: Sun, 9 Nov 2008 21:58:49 -0500
Subject: Updated as per Xavier's notes, still to do: Etags and globally keyed
fragments
---
railties/doc/guides/source/caching_with_rails.txt | 74 ++++++++++++-----------
1 file changed, 40 insertions(+), 34 deletions(-)
(limited to 'railties/doc')
diff --git a/railties/doc/guides/source/caching_with_rails.txt b/railties/doc/guides/source/caching_with_rails.txt
index d5b8b03669..e680b79d55 100644
--- a/railties/doc/guides/source/caching_with_rails.txt
+++ b/railties/doc/guides/source/caching_with_rails.txt
@@ -10,59 +10,65 @@ need to return to those hungry web clients in the shortest time possible.
This is an introduction to the three types of caching techniques that Rails
provides by default without the use of any third party plugins.
-To get started make sure Base.perform_caching is set to true for your
-environment.
+To get started make sure config.action_controller.perform_caching is set
+to true for your environment. This flag is normally set in the
+corresponding config/environments/*.rb and caching is disabled by default
+there for development and test, and enabled for production.
[source, ruby]
-----------------------------------------------------
-Base.perform_caching = true
+config.action_controller.perform_caching = true
-----------------------------------------------------
=== Page Caching
Page caching is a Rails mechanism which allows the request for a generated
page to be fulfilled by the webserver, without ever having to go through the
-Rails stack at all. Obviously, this is super fast. Unfortunately, it can't be
+Rails stack at all. Obviously, this is super-fast. Unfortunately, it can't be
applied to every situation (such as pages that need authentication) and since
the webserver is literally just serving a file from the filesystem, cache
expiration is an issue that needs to be dealt with.
So, how do you enable this super-fast cache behavior? Simple, let's say you
-have a controller called ProductController and a 'list' action that lists all
+have a controller called ProductsController and a 'list' action that lists all
the products
[source, ruby]
-----------------------------------------------------
-class ProductController < ActionController
+class ProductsController < ActionController
- cache_page :list
+ caches_page :index
- def list; end
+ def index; end
end
-----------------------------------------------------
-The first time anyone requestsion products/list, Rails will generate a file
-called list.html and the webserver will then look for that file before it
-passes the next request for products/list to your Rails application.
+The first time anyone requests products/index, Rails will generate a file
+called index.html and the webserver will then look for that file before it
+passes the next request for products/index to your Rails application.
By default, the page cache directory is set to Rails.public_path (which is
-usually set to RAILS_ROOT + "/public") and this can be configured by changing
-the configuration setting Base.cache_public_directory
-
-The page caching mechanism will automatically add a .html exxtension to
+usually set to RAILS_ROOT + "/public") and this can be configured by
+changing the configuration setting ActionController::Base.page_cache_directory. Changing the
+default from /public helps avoid naming conflicts, since you may want to
+put other static html in /public, but changing this will require web
+server reconfiguration to let the web server know where to serve the
+cached files from.
+
+The Page Caching mechanism will automatically add a .html exxtension to
requests for pages that do not have an extension to make it easy for the
webserver to find those pages and this can be configured by changing the
-configuration setting Base.page_cache_extension
+configuration setting ActionController::Base.page_cache_extension.
In order to expire this page when a new product is added we could extend our
example controler like this:
[source, ruby]
-----------------------------------------------------
-class ProductController < ActionController
+class ProductsController < ActionController
- cache_page :list
+ caches_page :list
def list; end
@@ -80,11 +86,11 @@ to expire cached objects when things change. This is covered in the section on S
=== Action Caching
-One of the issues with page caching is that you cannot use it for pages that
+One of the issues with Page Caching is that you cannot use it for pages that
require to restrict access somehow. This is where Action Caching comes in.
Action Caching works like Page Caching except for the fact that the incoming
web request does go from the webserver to the Rails stack and Action Pack so
-that before_filters can be run on it before the cache is served, so that
+that before filters can be run on it before the cache is served, so that
authentication and other restrictions can be used while still serving the
result of the output from a cached copy.
@@ -95,10 +101,10 @@ object, but still cache those pages:
[source, ruby]
-----------------------------------------------------
-class ProductController < ActionController
+class ProductsController < ActionController
before_filter :authenticate, :only => [ :edit, :create ]
- cache_page :list
+ caches_page :list
caches_action :edit
def list; end
@@ -120,7 +126,7 @@ or the number of items in the cart can be left uncached. This feature is
available as of Rails 2.2.
-[More: more examples? Walk-through of action caching from request to response?
+[More: more examples? Walk-through of Action Caching from request to response?
Description of Rake tasks to clear cached files? Show example of
subdomain caching? Talk about :cache_path, :if and assing blocks/Procs
to expire_action?]
@@ -132,15 +138,15 @@ a page or action and serving it out to the world. Unfortunately, dynamic web
applications usually build pages with a variety of components not all of which
have the same caching characteristics. In order to address such a dynamically
created page where different parts of the page need to be cached and expired
-differently Rails provides a mechanism called Fragment caching.
+differently Rails provides a mechanism called Fragment Caching.
-Fragment caching allows a fragment of view logic to be wrapped in a cache
+Fragment Caching allows a fragment of view logic to be wrapped in a cache
block and served out of the cache store when the next request comes in.
-As an example, if you wanted to show all the orders placed on your website in
-real time and didn't want to cache that part of the page, but did want to
-cache the part of the page which lists all products available, you could use
-this piece of code:
+As an example, if you wanted to show all the orders placed on your website
+in real time and didn't want to cache that part of the page, but did want
+to cache the part of the page which lists all products available, you
+could use this piece of code:
[source, ruby]
-----------------------------------------------------
@@ -158,7 +164,7 @@ this piece of code:
The cache block in our example will bind to the action that called it and is
written out to the same place as the Action Cache, which means that if you
-want to cache multiple fragments per action, you should provide an action_path to the cache call:
+want to cache multiple fragments per action, you should provide an action_suffix to the cache call:
[source, ruby]
-----------------------------------------------------
@@ -225,10 +231,10 @@ following:
[source, ruby]
-----------------------------------------------------
-class ProductController < ActionController
+class ProductsController < ActionController
before_filter :authenticate, :only => [ :edit, :create ]
- cache_page :list
+ caches_page :list
caches_action :edit
cache_sweeper :store_sweeper, :only => [ :create ]
@@ -257,10 +263,10 @@ For example:
[source, ruby]
-----------------------------------------------------
-class ProductController < ActionController
+class ProductsController < ActionController
before_filter :authenticate, :only => [ :edit, :create ]
- cache_page :list
+ caches_page :list
caches_action :edit
cache_sweeper :store_sweeper, :only => [ :create ]
--
cgit v1.2.3