doc/api/classes/ActionController/Caching/Pages.html
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Module: ActionController::Caching::Pages</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href="../../.././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Module</strong></td>
<td class="class-name-in-header">ActionController::Caching::Pages</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../../../files/vendor/rails/actionpack/lib/action_controller/caching_rb.html">
vendor/rails/actionpack/lib/action_controller/caching.rb
</a>
<br />
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<p>
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.
</p>
<p>
Specifying which actions to cache is done through the <tt>caches</tt> class
method:
</p>
<pre>
class WeblogController < ActionController::Base
caches_page :show, :new
end
</pre>
<p>
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.
</p>
<p>
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:
</p>
<pre>
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
</pre>
<p>
Additionally, you can expire caches using Sweepers that act on changes in
the model to determine when a cache is supposed to be expired.
</p>
<h2>Setting the cache directory</h2>
<p>
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".
</p>
<h2>Setting the cache extension</h2>
<p>
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.
</p>
</div>
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000112">cache_page</a>
<a href="#M000111">expire_page</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<div id="class-list">
<h3 class="section-bar">Classes and Modules</h3>
Module <a href="Pages/ClassMethods.html" class="link">ActionController::Caching::Pages::ClassMethods</a><br />
</div>
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Instance methods</h3>
<div id="method-M000112" class="method-detail">
<a name="M000112"></a>
<div class="method-heading">
<a href="#M000112" class="method-signature">
<span class="method-name">cache_page</span><span class="method-args">(content = nil, options = {})</span>
</a>
</div>
<div class="method-description">
<p>
Manually cache the <tt>content</tt> in the key determined by
<tt>options</tt>. If no content is provided, the contents of response.body
is used If no options are provided, the current <tt>options</tt> for this
action is used. Example:
</p>
<pre>
cache_page "I'm the cached content", :controller => "lists", :action => "show"
</pre>
<p><a class="source-toggle" href="#"
onclick="toggleCode('M000112-source');return false;">[Source]</a></p>
<div class="method-source-code" id="M000112-source">
<pre>
<span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/caching.rb, line 132</span>
132: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">cache_page</span>(<span class="ruby-identifier">content</span> = <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span> = {})
133: <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">perform_caching</span> <span class="ruby-operator">&&</span> <span class="ruby-identifier">caching_allowed</span>
134: <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">cache_page</span>(<span class="ruby-identifier">content</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">response</span>.<span class="ruby-identifier">body</span>, <span class="ruby-identifier">url_for</span>(<span class="ruby-identifier">options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">:only_path</span> =<span class="ruby-operator">></span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:skip_relative_url_root</span> =<span class="ruby-operator">></span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:format</span> =<span class="ruby-operator">></span> <span class="ruby-identifier">params</span>[<span class="ruby-identifier">:format</span>])))
135: <span class="ruby-keyword kw">end</span>
</pre>
</div>
</div>
</div>
<div id="method-M000111" class="method-detail">
<a name="M000111"></a>
<div class="method-heading">
<a href="#M000111" class="method-signature">
<span class="method-name">expire_page</span><span class="method-args">(options = {})</span>
</a>
</div>
<div class="method-description">
<p>
Expires the page that was cached with the <tt>options</tt> as a key.
Example:
</p>
<pre>
expire_page :controller => "lists", :action => "show"
</pre>
<p><a class="source-toggle" href="#"
onclick="toggleCode('M000111-source');return false;">[Source]</a></p>
<div class="method-source-code" id="M000111-source">
<pre>
<span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/caching.rb, line 118</span>
118: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">expire_page</span>(<span class="ruby-identifier">options</span> = {})
119: <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">perform_caching</span>
120: <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:action</span>].<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Array</span>)
121: <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:action</span>].<span class="ruby-identifier">dup</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">action</span><span class="ruby-operator">|</span>
122: <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">expire_page</span>(<span class="ruby-identifier">url_for</span>(<span class="ruby-identifier">options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">:only_path</span> =<span class="ruby-operator">></span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:skip_relative_url_root</span> =<span class="ruby-operator">></span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:action</span> =<span class="ruby-operator">></span> <span class="ruby-identifier">action</span>)))
123: <span class="ruby-keyword kw">end</span>
124: <span class="ruby-keyword kw">else</span>
125: <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">expire_page</span>(<span class="ruby-identifier">url_for</span>(<span class="ruby-identifier">options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">:only_path</span> =<span class="ruby-operator">></span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:skip_relative_url_root</span> =<span class="ruby-operator">></span> <span class="ruby-keyword kw">true</span>)))
126: <span class="ruby-keyword kw">end</span>
127: <span class="ruby-keyword kw">end</span>
</pre>
</div>
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>